Track API

Fetch metadata for a published audio track.

Endpoint

POST /api/track

Quick Test

curl -X POST https://huebsch.schoenreden.com/api/track \
  -H "Content-Type: application/json" \
  -d '{"slug":"/2024/01/my-article"}'

Request Body

{
  "slug": "/2024/01/my-article"
}

Field	Type	Required	Description
`slug`	string	Yes	Track slug (must start with `/`). Use the slug you submitted during intake — the system resolves it to your client automatically.

Response

Success

{
  "ok": true,
  "val": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "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"
    }
  }
}

Field	Type	Description
`id`	uuid	Track identifier
`slug`	string	Full track slug with client slug prepended (e.g., `/my-client/2024/article`)
`title`	string	Track title
`asset`	url	Audio file URL (MP3)
`duration`	number	Duration in seconds
`cover`	url \| null	Cover image URL
`chapters`	array \| null	Chapter markers (see below)
`clients`	object \| null	Client information (see below)

Chapters

Chapter markers for navigation within the audio. Created from marker nodes in the production content.

{
  "chapters": [
    { "name": "Introduction", "at": 0 },
    { "name": "The Main Story", "at": 45.2 },
    { "name": "Conclusion", "at": 180.5 }
  ]
}

Field	Type	Description
`name`	string	Chapter title
`at`	number	Start time in seconds from beginning

Chapters are displayed in the web player and can be used by podcast apps that support chapter markers.

Clients

Information about the client (publisher) that owns this track.

{
  "clients": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "my-publication",
    "name": "My Publication",
    "cover": "https://example.com/publication-logo.jpg"
  }
}

Field	Type	Description
`id`	uuid	Client identifier
`slug`	string	Client URL slug
`name`	string	Client display name
`cover`	url \| null	Client logo/cover image

Returns null if the track has no associated client.

Error

{
  "ok": false,
  "val": {
    "error": "Unable to find track",
    "code": "404.1"
  }
}

404.1 means no track exists under the slug. 503.8 means the lookup failed; retry later.

For error codes, see Error Codes.

Usage

Retrieve track metadata after receiving a webhook notification
Power custom players or integrations with track data
The chapters array enables navigation UI in audio players

Track API

On this page