Audiobook Tracks

Manage audio tracks for audiobook content. Tracks are individual audio files (chapters, sections) that make up an audiobook.

Audiobooks Only

These endpoints only work with content where file_type is audio. Attempting to use these endpoints on non-audio content returns a 422 error.

---

Endpoints Overview

Method	Endpoint	Description
GET	/api/v3/content/{id}/tracks	List all tracks
POST	/api/v3/content/{id}/tracks	Add a new track
PUT	/api/v3/content/{id}/tracks/{track}	Update a track
PUT	/api/v3/content/{id}/tracks/order	Reorder tracks
DELETE	/api/v3/content/{id}/tracks/{track}	Delete a track

---

List Tracks

Retrieve all tracks for an audiobook, ordered by position.

Endpoint

GET /api/v3/content/{id}/tracks

Path Parameters

Parameter	Type	Description
id	string	Content internal ID

Example Request

curl -X GET "https://yourstore.publica.la/api/v3/content/468166/tracks" \
  -H "X-User-Token: your-api-token"

Response

{
  "data": [
    {
      "id": "1001",
      "title": "Chapter 1 - The Beginning",
      "order": 1,
      "duration": 1845,
      "size_in_kb": 45200,
      "created_at": "2025-01-15T10:30:00.000000Z",
      "updated_at": "2025-01-15T10:30:00.000000Z"
    },
    {
      "id": "1002",
      "title": "Chapter 2 - The Journey",
      "order": 2,
      "duration": 2130,
      "size_in_kb": 52100,
      "created_at": "2025-01-15T10:35:00.000000Z",
      "updated_at": "2025-01-15T10:35:00.000000Z"
    }
  ]
}

Track Fields

Field	Type	Description
id	string	Track internal ID (numeric as string)
title	string	Display title for the track
order	integer	Track position (1-based)
duration	integer	Duration in seconds
size_in_kb	integer|null	File size in kilobytes
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

---

Add Track

Upload a new audio track to an audiobook.

Endpoint

POST /api/v3/content/{id}/tracks

Path Parameters

Parameter	Type	Description
id	string	Content internal ID

Request Body

Field	Type	Description	Required
title	string	Display title for the track (max 255 chars)	Yes
file	string	Storage path to uploaded audio file (mutually exclusive with file_url)	Yes*
file_url	string	URL to download audio file from (mutually exclusive with file)	Yes*
order	integer	Track position, min 1 (defaults to last)	No

*Either file or file_url is required.

Supported Format

Supported audio format: MP3 only (audio/mpeg, audio/mp3). Maximum file size: 500 MB.

File Upload Options

• file_url: Provide a publicly accessible URL. The platform will download the audio file automatically.
• file: Provide a storage path from SFTP upload. Contact support to enable SFTP access for your account.

Example Request

curl -X POST "https://yourstore.publica.la/api/v3/content/468166/tracks" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chapter 3 - The Discovery",
    "file_url": "https://example.com/audio/chapter03.mp3"
  }'

Example with Order

curl -X POST "https://yourstore.publica.la/api/v3/content/468166/tracks" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Introduction",
    "file_url": "https://example.com/audio/intro.mp3",
    "order": 1
  }'

Response (201 Created)

{
  "data": {
    "id": "1003",
    "title": "Chapter 3 - The Discovery",
    "order": 3,
    "duration": 1920,
    "size_in_kb": 46800,
    "created_at": "2025-01-15T10:40:00.000000Z",
    "updated_at": "2025-01-15T10:40:00.000000Z"
  }
}

Track Processing

Audio files are processed asynchronously to extract duration and other metadata. Initial responses may show duration: 0 until processing completes.

---

Update Track

Modify an existing track's metadata.

Endpoint

PUT /api/v3/content/{id}/tracks/{track}

Path Parameters

Parameter	Type	Description
id	string	Content internal ID
track	string	Track internal ID

Request Body

All fields are optional. Only include fields you want to update.

Field	Type	Description
title	string	New display title (max 255 chars)
duration	integer	Duration in seconds
file	string	Storage path to new audio file (mutually exclusive with file_url)
file_url	string	URL to new audio file (mutually exclusive with file)

Example Request

curl -X PUT "https://yourstore.publica.la/api/v3/content/468166/tracks/1001" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chapter 1 - A New Beginning (Revised)"
  }'

Example: Replace Audio File

curl -X PUT "https://yourstore.publica.la/api/v3/content/468166/tracks/1001" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/audio/chapter01_remastered.mp3"
  }'

Response (200 OK)

{
  "data": {
    "id": "1001",
    "title": "Chapter 1 - A New Beginning (Revised)",
    "order": 1,
    "duration": 1890,
    "size_in_kb": 46100,
    "created_at": "2025-01-15T10:30:00.000000Z",
    "updated_at": "2025-01-15T11:00:00.000000Z"
  }
}

---

Reorder Tracks

Change the order of all tracks in an audiobook.

Endpoint

PUT /api/v3/content/{id}/tracks/order

Path Parameters

Parameter	Type	Description
id	string	Content internal ID

Request Body

Field	Type	Description	Required
track_ids	array	Ordered array of track IDs (strings)	Yes

All Track IDs Required

You must include all track IDs for the audiobook. The endpoint returns 422 if any track is missing or if extra IDs are provided.

Example Request

curl -X PUT "https://yourstore.publica.la/api/v3/content/468166/tracks/order" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "track_ids": ["1003", "1001", "1002"]
  }'

Response (204 No Content)

A successful reorder returns a 204 No Content response.

---

Delete Track

Remove a track from an audiobook.

Endpoint

DELETE /api/v3/content/{id}/tracks/{track}

Path Parameters

Parameter	Type	Description
id	string	Content internal ID
track	string	Track internal ID

Example Request

curl -X DELETE "https://yourstore.publica.la/api/v3/content/468166/tracks/1003" \
  -H "X-User-Token: your-api-token"

Response (204 No Content)

A successful deletion returns a 204 No Content response.

---

Error Handling

Content Not Audio (422)

{
  "message": "Content is not an audiobook"
}

Forbidden (403)

{
  "message": "This action is unauthorized."
}

This occurs when the content belongs to a different tenant.

Track Not Found (404)

{
  "message": "Track not found."
}

Track Does Not Belong to Content (404)

{
  "message": "Track not found."
}

Invalid Audio Format (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "file": ["The file must be a valid audio file (MP3)."]
  }
}

Invalid Track IDs in Reorder (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "track_ids": ["Some track IDs do not belong to this audiobook"]
  }
}

---

Complete Workflow Example

Create Audiobook with Tracks

# Step 1: Create audiobook content
curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "The Great Adventure Audiobook",
    "file_type": "audio",
    "lang": "en",
    "external_id": "AUDIO-ADVENTURE-001",
    "description": "An epic adventure narrated by professional voice actors",
    "prices": [{ "currency_id": "USD", "amount": 19.99 }],
    "author": ["Adventure Author"]
  }'

# Response: { "data": { "id": "468200", ... } }

# Step 2: Add tracks
curl -X POST "https://yourstore.publica.la/api/v3/content/468200/tracks" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Introduction",
    "file_url": "https://cdn.example.com/adventure/intro.mp3"
  }'

curl -X POST "https://yourstore.publica.la/api/v3/content/468200/tracks" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chapter 1 - The Call",
    "file_url": "https://cdn.example.com/adventure/ch01.mp3"
  }'

curl -X POST "https://yourstore.publica.la/api/v3/content/468200/tracks" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Chapter 2 - The Journey Begins",
    "file_url": "https://cdn.example.com/adventure/ch02.mp3"
  }'

# Step 3: Verify tracks
curl -X GET "https://yourstore.publica.la/api/v3/content/468200/tracks" \
  -H "X-User-Token: your-api-token"

Manage Existing Audiobook

# List current tracks
curl -X GET "https://yourstore.publica.la/api/v3/content/468200/tracks" \
  -H "X-User-Token: your-api-token"

# Update track title
curl -X PUT "https://yourstore.publica.la/api/v3/content/468200/tracks/1001" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Prologue (Updated)" }'

# Reorder tracks
curl -X PUT "https://yourstore.publica.la/api/v3/content/468200/tracks/order" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{ "track_ids": ["1003", "1001", "1002"] }'

# Delete a track
curl -X DELETE "https://yourstore.publica.la/api/v3/content/468200/tracks/1003" \
  -H "X-User-Token: your-api-token"

---

See Also

• Create Content - Create audiobook content
• Update Content - Update audiobook metadata
• Get Content - Retrieve audiobook details
• Overview - API overview

---