API: Episode Chapters

In this page

The Episode Chapter object

Chapters are like bookmarks within your episode. Chapters are mainly used to give listeners an easy way to fast forward to specific minute marks throughout your episode, and are especially useful in long audio files. A chapter has the following properties:

Property Type Description
chapter_id Numeric Unique chapter identifier
starts_at Numeric The position, in milliseconds, relative to the beginning of the audio file, at which the chapter begins
title String Chapter’s title
external_url String An optional URL linking to a resource related to the chapter that provides extra information
image_url String Chapter’s small image URL
image_original_url String Chapter’s original size image URL

Retrieving an Episode’s Chapters

GET /v2/episodes/EPISODE-ID/chapters

Authenticated: no

This API returns a paginated list of Chapters for the given Episode. The chapter list is sorted chronologically, from first to last.

Example

curl https://api.spreaker.com/v2/episodes/8900550/chapters?limit=2
{
    "response": {
        "items": [{
            "chapter_id": 2933540,
            "starts_at": 1803,
            "title": "YVR_Intro",
            "external_url": null,
            "image_url": null,
            "image_original_url": null
        }, {
            "chapter_id": 2933541,
            "starts_at": 285388,
            "title": "[CLIP]   HILLARY Clinton  Took Me Through Hell  Says 12yr. Old RAPE Victim!",
            "external_url": null,
            "image_url": null,
            "image_original_url": null
        }],
        "next_url": "https://api.spreaker.com/v2/episodes/8900550/chapters?last_id=2933541&limit=2"
    }
}

Adding a Chapter

POST /v2/episodes/EPISODE-ID/chapters

Authenticated: yes.Owner: yes

Adds a new chapter to the given episode. This API needs to be authenticated with the episode’s author credentials, and supports all the parameters of the Updating a Chapter API.

The only required parameters are starts_at and title: all other parameters are optional and can be edited later.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "starts_at=0" -F "title=More about me" -F "external_url=https://pracucci.com" -F "image_file=@me.jpg" https://api.spreaker.com/v2/episodes/7822454/chapters
{
    "response": {
        "chapter": {
            "chapter_id": 2961426,
            "starts_at": 0,
            "title": "More about me",
            "external_url": "https://pracucci.com",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/54c8848ef3dfa0f0934fa2d47626a5b7.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/54c8848ef3dfa0f0934fa2d47626a5b7.jpg"
        }
    }
}

Updating a Chapter

POST /v2/episodes/EPISODE-ID/chapters/CHAPTER-ID

Authenticated: yes. Owner: yes

Updates the given chapter’s data. This API needs to be authenticated with the episode’s author credentials, and supports these parameters, none of which are required, as you should specify only the ones you want to update:

Parameter Type Description
starts_at Numeric -
title String Max length: 120
external_url String -
image_file File At least 400x400, Max size: 5MB, Formats: JPG, PNG. If the value of this parameter is a remove string, it will remove the previously uploaded image for this episode.
image_crop String Comma-separated coordinates (top left X, top left Y, bottom right X, bottom right Y) used to crop an image_file. If not specified, the image_file will not be cropped. This parameter is effective only if the request contains an image_file.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "title=More about me" https://api.spreaker.com/v2/episodes/7822454/chapters/2961426
{
    "response": {
        "chapter": {
            "chapter_id": 2961426,
            "starts_at": 0,
            "title": "More about me",
            "external_url": "https://pracucci.com",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/54c8848ef3dfa0f0934fa2d47626a5b7.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/54c8848ef3dfa0f0934fa2d47626a5b7.jpg"
        }
    }
}

Deleting a Single Chapter

DELETE /v2/episodes/EPISODE-ID/chapters/CHAPTER-ID

Authenticated: yes. Owner: yes

Deletes the given episode’s chapter. This API needs to be authenticated with the episode’s author credentials.

Example

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/episodes/7822454/chapters/2961426

Deleting All of the Episode’s Chapters

DELETE /v2/episodes/EPISODE-ID/chapters

Authenticated: yes. Owner: yes

Deletes all the chapters for the given episode. This API needs to be authenticated with the episode’s author credentials.

Example

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/episodes/7822454/chapters