> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publica.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Audiobook Tracks

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

:::info 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

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

### Response

```json
{
  "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.

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

:::tip 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

```bash
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

```bash
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)

```json
{
  "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"
  }
}
```

:::note 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

```bash
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

```bash
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)

```json
{
  "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      |

:::warning 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

```bash
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

```bash
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)

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

### Forbidden (403)

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

This occurs when the content belongs to a different tenant.

### Track Not Found (404)

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

### Track Does Not Belong to Content (404)

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

### Invalid Audio Format (422)

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

### Invalid Track IDs in Reorder (422)

```json
{
  "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

```bash
# 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": [{ "first_name": "Adventure", "last_name": "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

```bash
# 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](./content-v3-create.md) - Create audiobook content
- [Update Content](./content-v3-update.md) - Update audiobook metadata
- [Get Content](./content-v3-get.md) - Retrieve audiobook details
- [Overview](./content-v3-overview.md) - API overview

---