Interested in working with us? We offer a superb REMOTE work opportunity for a DEVOP.
Working with Draft Episodes
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.
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:
Despite being able to specify any episode property in the request, the only required information is the
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
permalink. You can find a list of all the editable properties in the API Reference.
Uploading 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.
Publishing 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.
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
RECORDED and it will be made publicly available for listening.
Scheduling 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
RECORDED, and at the date and time specified by
auto_published_at, will be made publicly available for listening.
IMPORTANT: 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.