Huebsch Docs

Transform written content into audio productions via REST API.

Getting Started

1. Obtain your access token — Contact Huebsch to get your client credentials and available voices configured
2. Submit content — POST to /api/intake/production/{token} with your article content
3. Receive webhook — When processing completes, Huebsch POSTs the finished track to your webhook URL

Here's a minimal example:

curl -X POST https://huebsch.schoenreden.com/api/intake/production/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "type": "doc",
    "content": [{
      "type": "article",
      "attrs": {
        "title": "My First Article",
        "slug": "/my-first-article",
        "webhook": "https://your-server.com/webhook"
      },
      "content": [{
        "type": "paragraph",
        "attrs": { "voiceName": "Hannah", "proofreadPromptName": "Default" },
        "content": [{ "type": "text", "text": "Hello, world." }]
      }]
    }]
  }'

The API validates your request and returns { "ok": true, "val": "accepted" }. Minutes later, your webhook receives the finished track with audio URL, duration, and chapter markers.

Need help? Reach out via your Slack channel — we're happy to help with onboarding.

Base URL

https://huebsch.schoenreden.com

All endpoint paths are relative to this base URL.

Authentication

Most endpoints require an accessToken in the URL path. This token identifies your client and should be kept confidential.

Public endpoints (no token required): /api/track, /api/beacon

POST requests require Content-Type: application/json.

Endpoints

Response Format

All responses use the Result pattern:

// Success
{ "ok": true, "val": "accepted" }

// Error
{ "ok": false, "val": { "error": "message", "code": "422.1" } }

Error responses may include additional fields:

{
  "ok": false,
  "val": {
    "error": "Validation failed",
    "code": "422.2",
    "message": "Invalid field value",
    "issues": [{ "code": "invalid_type", "expected": "string", "path": ["title"], "message": "Invalid input: expected string, received undefined" }]
  }
}

Webhooks

Intake endpoints return immediately with { "ok": true, "val": "accepted" } after validating the request. Audio production happens asynchronously.

To receive notification when production completes, include a webhook URL in your request. Huebsch will POST to this URL with a Track object:

{
  "ok": true,
  "val": {
    "id": "track-uuid",
    "slug": "/client-slug/2024/01/my-article",
    "title": "Article Title",
    "asset": "https://cdn.example.com/audio.mp3",
    "duration": 245.5,
    "cover": "https://example.com/cover.jpg",
    "chapters": [
      { "name": "Introduction", "at": 0 },
      { "name": "Main Content", "at": 45.2 }
    ],
    "clients": {
      "id": "client-uuid",
      "slug": "client-slug",
      "name": "Client Name",
      "cover": "https://example.com/client-cover.jpg"
    }
  }
}

See Track API - Chapters and Track API - Clients for field details.

If your production needs a fix, the webhook delivers an error (codes):

{
  "ok": false,
  "val": {
    "error": "voice \"Unknown\" not found",
    "code": "422.8"
  }
}

Delivery is considered successful when your endpoint returns a 2xx status code within 10 seconds. Slow or failed deliveries are retried up to 20 times over ~24 hours.

Webhook requests include the following headers:

User-Agent: HuebschWebhook (+https://huebsch.schoenreden.com; hi@schoenreden.com)
X-Huebsch-Delivery-Id: 3f9a2c8e1b7d4a6f0e5c9b2a1d8f7e3c6b4a2f9d8e1c7b5a0f3d6e9c2b8a1f4d

X-Huebsch-Delivery-Id is an opaque token, unique per delivery and stable across every retry, so you can treat it as an idempotency key to dedupe redeliveries — for example, when your handler succeeds but is slow enough to hit the 10-second timeout and gets retried.

Audio Output

Productions are delivered as MP3:

• Format: MP3 (audio/mpeg)
• Sample rate: 44.1 kHz
• Channels: Stereo
• Loudness: -14 LUFS (broadcast standard)

Chapter markers (from marker nodes) are included in the webhook payload and displayed in the web player.

ID3 Metadata

ID3 tags store metadata (title, artist, cover art, chapters) directly in the audio file. MP3 files include the following ID3v2 tags:

Custom metadata for traceability (visible in ID3 tag readers, not standard players):

AI Provenance

Every MP3 is marked as AI-generated: IPTC digital source type tags, a signed C2PA manifest and an inaudible watermark (EU AI Act Art. 50(2)). Details, the Huebsch root and the public check at /verify: AI Provenance.

Error Codes

Errors use the same Result format whether returned immediately or via webhook:

{
  "ok": false,
  "val": { "error": "message", "code": "422.2" }
}

Handle both sources identically in your code.

API Response

Errors returned immediately from the API call.

Error code prefixes map to HTTP status codes: 401.x → HTTP 401, 404.x → HTTP 404, etc.

Webhook Callback

Errors delivered to your webhook URL when your production needs a fix. Internal failures are not delivered: we are notified and republish once resolved, and the webhook then delivers the finished track as usual. If no callback arrives within a few hours, contact support.

Support

Status Page: Check status.schoenreden.com for current system status and incident updates.

Slack: We prefer Slack for quick communication. Reach out via your shared channel for questions, issues, or feature requests.