Working with Draft Episodes
Prerequisites
Before continuing, you should have already read:
What’s a Draft Episode?
If you’ve read the “Uploading an Episode” guide, you will already be familiar with uploading and publishing episodes. In that guide, we explain how to easily upload and publish a new episode to Spreaker, but what if you want to decouple the audio file upload request from episode metadata editing? Draft episodes have been designed to solve this specific use case.
Thus, a DRAFT episode is an episode that could still have no audio file associated with it, and has not yet been published. Working with draft episodes is a bit more complicated than simply uploading and publishing an episode, so you should consider draft episodes only when your use case doesn’t fit with any of the other APIs.
HISTORY: Draft episodes were introduced to Spreaker in order to allow episode metadata editing while the audio file uploaded to the web-based app, as well as decoupling both uploading and editing from publishing (which could be done later on).
Creating a Draft Episode
Creating a draft episode is as easy as invoking the following API:
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "title=Daily News" -F "show_id=SHOW-ID" https://api.spreaker.com/v2/episodes/draftsDespite being able to specify any episode property in the request, the only required information is the title and show_id. If successful, the response will contain the episode data, including the episode_id required to upload the audio file and edit the episode’s metadata.
Editing a Draft Episode’s Metadata
Once the episode has been created, you can edit its metadata, like the description, tags, or permalink. You can find a list of all the editable properties in the API Reference.
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "description=Amazing stories from the world" https://api.spreaker.com/v2/episodes/EPISODE-IDUploading an Audio File to a Draft Episode
Uploading an audio file to a draft episode basically means editing the episode’s media_file. The following example shows an upload request. If successful, your episode will immediately be queued up for processing.
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 https://api.spreaker.com/v2/episodes/EPISODE-IDPublishing a Draft Episode
Once you’ve uploaded an audio file to a draft episode, it becomes egibile for publishing. You are not required to publish it immediately, but you can publish a draft episode at any time in the future, both manually or by scheduling it to be published later.
Manual Publishing
To manually publish a draft episode, you have to edit the episode and set published_at to the current date and time (UTC timezone). If successful, the episode type will switch from DRAFT to RECORDED and it will be made publicly available for listening.
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "published_at=2017-05-27 12:00:00" https://api.spreaker.com/v2/episodes/EPISODE-IDScheduling to Auto-Publish Later
To schedule the episode to auto-publish later, you must edit the episode and set auto_published_at to the future date and time that it should be automatically published (UTC timezone). If successful, the episode type will switch from DRAFT to RECORDED, and at the date and time specified by auto_published_at, will be made publicly available for listening.
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "auto_published_at=2020-04-20 18:00:00" https://api.spreaker.com/v2/episodes/EPISODE-IDIMPORTANT: In order to publish a draft episode, it is required that the episode have an audio file associated with it (see Upload an Audio File), nevertheless, it’s not required that server-side processing be completed.
Unscheduling an episode scheduled to be published later
If the episode is scheduled to be published later and the future date / time has not yet been reached, you can switch it back to the unscheduled state by invoking the episode editing API with the parameter auto_published_at set to an empty string.
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "auto_published_at=" https://api.spreaker.com/v2/episodes/EPISODE-ID