The Transistor API is built around the JSON:API specification. Our API allows you to work with podcasts, episodes, private podcast subscribers, and analytics. Endpoints accept JSON or form-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes.
The Transistor API uses API keys to authenticate all requests. Your API keys can be viewed and reset in the Account Area of your Transistor Dashboard. Each API request must include an HTTP header x-api-key
with its value being your API key.
Authenticated requests grant you access to any podcast or episode you would have access to through the Dashboard, along with the same level of access depending on if you're an owner, an admin, or a regular team member of a podcast.
API requests are rate-limited to 10 requests per 10 seconds. If this limit is exceeded, you will be receive a 429
HTTP error code, and access will be blocked for 10 seconds. After these 10 seconds, you are free to use the API again.
If you are continually hitting the rate-limit, please review your use of the API and always cache responses when possible. The Transistor API is not meant to be the main data source for website content. If this is what you're looking for, you may want to simply parse the XML from your RSS Feed.
Because our API conforms to the JSON:API spec, each endpoint also accepts extra parameters that can be helpful in certain scenarios: sparse fieldsets and including related resources. We've included examples of these in some of our example requests and responses.
Sometimes you may wish to only have a handful of a resource's fields be returned from an API request, instead of the entire resource. Let's say you want to retrieve an Episode but only return the title and media_url. In your request you can specify fields[episode][]=title&fields[episode][]=media_url
.
You can also return a resource's related resources in one single API request instead of multiuple requests. For example, you may want to retrieve an Episode, but also include its parent Show resource. In your request you can specify include[]=show
. You can also combine this with sparse fieldsets to request an Episode's related Show, but only return the Show's title and RSS Feed URL, for example. include[]=show&fields[show][]=title&fields[show][]=feed_url
.
Retrieve details of the user account that is authenticating to the API.
GET
/v1
A single User resource
$ curl https://api.transistor.fm/v1 -G \
-H "x-api-key: your_api_key"
$ {
"data": {
"id": "173455",
"type": "user",
"attributes": {
"created_at": "2020-01-01 00:00:00 UTC",
"image_url": null,
"name": "Jimmy Podcaster",
"time_zone": "UTC",
"updated_at": "2020-06-01 00:00:00 UTC"
}
}
}
Retrieve analytics of downloads per day for an entire podcast. Defaults to the last 14 days.
GET
/v1/analytics/:id
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Show ID or slug | |
start_date | String | Optional starting date for analytics (dd-mm-yyyy). Required if using an ending date. | |
end_date | String | Optional ending date for analytics (dd-mm-yyyy). Required if using a starting date. |
A single ShowAnalytics resource
$ curl https://api.transistor.fm/v1/analytics/132543 -G \
-H "x-api-key: your_api_key" \
-d start_date=01-01-2020 \
-d end_date=31-12-2020 \
-d "include[]=show" \
-d "fields[show][]=title"
$ {
"data": {
"id": "the-caffeine-show",
"type": "show_analytics",
"attributes": {
"downloads": [
{
"date": "24-11-2024",
"downloads": 0
},
{
"date": "25-11-2024",
"downloads": 0
},
{
"date": "26-11-2024",
"downloads": 0
},
{
"date": "27-11-2024",
"downloads": 0
},
{
"date": "28-11-2024",
"downloads": 0
},
{
"date": "29-11-2024",
"downloads": 0
},
{
"date": "30-11-2024",
"downloads": 0
},
{
"date": "01-12-2024",
"downloads": 0
},
{
"date": "02-12-2024",
"downloads": 0
},
{
"date": "03-12-2024",
"downloads": 0
},
{
"date": "04-12-2024",
"downloads": 0
},
{
"date": "05-12-2024",
"downloads": 0
},
{
"date": "06-12-2024",
"downloads": 0
},
{
"date": "07-12-2024",
"downloads": 0
}
],
"start_date": "11-24-2024",
"end_date": "12-07-2024"
},
"relationships": {
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
},
"included": [
{
"id": "132543",
"type": "show",
"attributes": {
"title": "The Caffeine Show"
},
"relationships": {}
}
]
}
Retrieve analytics of downloads per day for all episodes of a podcast. Defaults to the last 7 days.
GET
/v1/analytics/:id/episodes
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Show ID or slug | |
start_date | String | Optional starting date for analytics (dd-mm-yyyy). Required if using an ending date. | |
end_date | String | Optional ending date for analytics (dd-mm-yyyy). Required if using a starting date. |
A single EpisodesAnalytics resource
$ curl https://api.transistor.fm/v1/analytics/132543/episodes -G \
-H "x-api-key: your_api_key" \
-d start_date=01-01-2021 \
-d end_date=07-01-2021 \
-d "include[]=show" \
-d "fields[show][]=title"
$ {
"data": {
"id": "the-caffeine-show",
"type": "episodes_analytics",
"attributes": {
"episodes": [
{
"id": 2,
"title": "Episode Two",
"published_at": "2024-11-29 05:23:18 UTC",
"downloads": [
{
"date": "11-24-2024",
"downloads": 0
},
{
"date": "11-25-2024",
"downloads": 0
},
{
"date": "11-26-2024",
"downloads": 0
},
{
"date": "11-27-2024",
"downloads": 0
},
{
"date": "11-28-2024",
"downloads": 0
},
{
"date": "11-29-2024",
"downloads": 0
},
{
"date": "11-30-2024",
"downloads": 0
}
]
},
{
"id": 1,
"title": "Episode One",
"published_at": "2024-11-27 05:23:18 UTC",
"downloads": [
{
"date": "11-24-2024",
"downloads": 0
},
{
"date": "11-25-2024",
"downloads": 0
},
{
"date": "11-26-2024",
"downloads": 0
},
{
"date": "11-27-2024",
"downloads": 0
},
{
"date": "11-28-2024",
"downloads": 0
},
{
"date": "11-29-2024",
"downloads": 0
},
{
"date": "11-30-2024",
"downloads": 0
}
]
}
],
"start_date": "11-24-2024",
"end_date": "11-30-2024"
},
"relationships": {
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
},
"included": [
{
"id": "132543",
"type": "show",
"attributes": {
"title": "The Caffeine Show"
},
"relationships": {}
}
]
}
Retrieve analytics of downloads per day for a single episode. Defaults to the last 14 days.
GET
/v1/analytics/episodes/:id
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Episode ID or slug | |
start_date | String | Optional starting date for analytics (dd-mm-yyyy). Required if using an ending date. | |
end_date | String | Optional ending date for analytics (dd-mm-yyyy). Required if using a starting date. |
A single EpisodeAnalytics resource
$ curl https://api.transistor.fm/v1/analytics/episodes/3056098 -G \
-H "x-api-key: your_api_key" \
-d start_date=01-01-2020 \
-d end_date=31-12-2020 \
-d "include[]=episode" \
-d "fields[episode][]=title"
$ {
"data": {
"id": "3056098",
"type": "episode_analytics",
"attributes": {
"downloads": [
{
"date": "24-11-2024",
"downloads": 0
},
{
"date": "25-11-2024",
"downloads": 0
},
{
"date": "26-11-2024",
"downloads": 0
},
{
"date": "27-11-2024",
"downloads": 0
},
{
"date": "28-11-2024",
"downloads": 0
},
{
"date": "29-11-2024",
"downloads": 0
},
{
"date": "30-11-2024",
"downloads": 0
},
{
"date": "01-12-2024",
"downloads": 0
},
{
"date": "02-12-2024",
"downloads": 0
},
{
"date": "03-12-2024",
"downloads": 0
},
{
"date": "04-12-2024",
"downloads": 0
},
{
"date": "05-12-2024",
"downloads": 0
},
{
"date": "06-12-2024",
"downloads": 0
},
{
"date": "07-12-2024",
"downloads": 0
}
],
"start_date": "11-24-2024",
"end_date": "12-07-2024"
},
"relationships": {
"episode": {
"data": {
"id": "3056098",
"type": "episode"
}
}
}
},
"included": [
{
"id": "3056098",
"type": "episode",
"attributes": {
"title": "How To Roast Coffee"
},
"relationships": {}
}
]
}
Field | Type | Details | Description |
---|---|---|---|
show_id | String | Show ID or slug | |
query | String | Search query | |
status | String |
One of
|
Publishing status: published, scheduled, or draft |
order | String |
One of
Default:
desc
|
Return order of episodes. Newest first (desc), or oldest first (asc) |
pagination[page] | Integer | Default: 0 | Page number |
pagination[per] | Integer | Default: 10 | Resources per page |
An array of Episode resources
$ curl https://api.transistor.fm/v1/episodes -G \
-H "x-api-key: your_api_key" \
-d show_id=132543 \
-d "pagination[page]=1" \
-d "pagination[per]=5" \
-d "fields[episode][]=title" \
-d "fields[episode][]=published_at"
$ {
"data": [
{
"id": "3056098",
"type": "episode",
"attributes": {
"title": "How To Roast Coffee",
"published_at": "2020-07-01 00:00:00 UTC"
},
"relationships": {}
},
{
"id": "3056099",
"type": "episode",
"attributes": {
"title": "The Effects of Caffeine",
"published_at": "2020-07-01 00:00:00 UTC"
},
"relationships": {}
}
],
"meta": {
"currentPage": 1,
"totalPages": 1,
"totalCount": 2
}
}
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Episode ID |
A single Episode resource
$ curl https://api.transistor.fm/v1/episodes/3056098 -G \
-H "x-api-key: your_api_key" \
-d "include[]=show" \
-d "fields[show][]=title" \
-d "fields[show][]=summary"
$ {
"data": {
"id": "3056098",
"type": "episode",
"attributes": {
"title": "How To Roast Coffee",
"number": 1,
"season": 1,
"status": "published",
"published_at": "2020-07-01 00:00:00 UTC",
"duration": 568,
"explicit": false,
"keywords": "coffee,caffeine,beans",
"alternate_url": null,
"media_url": "https://media.transistor.fm/5dd4274f/282f47aa.mp3",
"image_url": null,
"video_url": "https://www.youtube.com/watch?v=xcyHT1ZLd9Y",
"author": "Jimmy Podcaster",
"summary": "A primer on roasting coffee",
"description": "This podcast talks about some <strong>strong</strong> coffee!",
"slug": null,
"created_at": "2020-03-01 00:00:00 UTC",
"updated_at": "2020-03-01 00:00:00 UTC",
"formatted_published_at": "July 1, 2020",
"duration_in_mmss": "09:28",
"share_url": "https://share.transistor.fm/s/5dd4274f",
"transcript_url": null,
"transcripts": [],
"formatted_summary": "A primer on roasting coffee",
"formatted_description": "This podcast talks about some <strong>strong</strong> coffee!",
"embed_html": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/5dd4274f\"></iframe>",
"embed_html_dark": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/5dd4274f/dark\"></iframe>",
"audio_processing": false,
"type": "full",
"email_notifications": null
},
"relationships": {
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
},
"included": [
{
"id": "132543",
"type": "show",
"attributes": {
"title": "The Caffeine Show"
},
"relationships": {}
}
]
}
Authorize a URL for uploading a local audio file to be used when creating or updating an episode. If you already have a publicly available URL for your audio file, skip this step and use that URL in the episode[audio_url]
field when creating or updating an episode.
GET
/v1/episodes/authorize_upload
Field | Type | Details | Description |
---|---|---|---|
filename Required | String | Filename of the audio file you wish to upload |
A single AudioUpload resource
$ curl https://api.transistor.fm/v1/episodes/authorize_upload -G \
-H "x-api-key: your_api_key" \
-d filename=Episode1.mp3
$ {
"data": {
"id": "4615f114-5597-42e2-8cba-2f518d0816e1",
"type": "audio_upload",
"attributes": {
"upload_url": "https://transistorupload.s3.amazonaws.com/588ea179cb09e23eaf331d12f600ab9e.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJNPH...%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240402T175744Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=0c3bf1...",
"content_type": "audio/mpeg",
"expires_in": 600,
"audio_url": "https://transistorupload.s3.amazonaws.com/588ea179cb09e23eaf331d12f600ab9e.mp3"
}
}
}
Upload your audio file however you wish but it must be a PUT method HTTP request with the content_type
of the audio file included as a header. After a successful 200 response, you may then use the audio_url
as the episode[audio_url]
when creating or updating an episode.
$ curl -v -X PUT \
-H "Content-Type: audio/mpeg" \
-T /path/to/your/audio/Episode1.mp3 \
"upload_url_from_authorize_upload"
require "net/http"
file = "/path/to/your/audio/Episode1.mp3"
presigned_url = "upload_url_from_authorize_upload"
url = URI.parse(presigned_url)
Net::HTTP.start(url.host) do |http|
http.send_request("PUT", url.request_uri, File.read(file), { "content-type" => "audio/mpeg" })
end
Create a new draft episode for the specified show. Note that publishing an episode involves a separate endpoint.
POST
/v1/episodes
Field | Type | Details | Description |
---|---|---|---|
episode[show_id] Required | String | ID or Slug of the Show to add an episode to | |
episode[audio_url] | String | URL to an episode's new audio file | |
episode[transcript_text] | String | Full text of the episode transcript | |
episode[author] | String | Episode author | |
episode[description] | String | Longer episode description which may contain HTML and unformatted tags for chapters, people, supporters, etc | |
episode[explicit] | Boolean | Episode contains explicit content | |
episode[image_url] | String | Episode artwork image URL | |
episode[keywords] | String | Comma-separated list of keywords | |
episode[number] | Integer | Episode number | |
episode[season] | Integer | Season number | |
episode[summary] | String | Episode summary short description | |
episode[type] | String |
One of
|
Full, trailer, or bonus episode |
episode[title] | String | Episode title | |
episode[alternate_url] | String | Alternate episode URL overriding the share_url | |
episode[video_url] | String | YouTube video URL to be embedded on episode sharing pages and website pages | |
episode[email_notifications] | Boolean | Private podcast email notifications override (defaults to Show setting) | |
episode[increment_number] | Boolean | Automatically set the number to the next episode number of the current season |
A single Episode resource
$ curl https://api.transistor.fm/v1/episodes -X POST \
-H "x-api-key: your_api_key" \
-d "episode[show_id]=132543" \
-d "episode[title]=Awesome podcast" \
-d "episode[summary]=A podcast about awesome things" \
-d "episode[season]=2" \
-d "episode[number]=1"
$ {
"data": {
"id": "3056098",
"type": "episode",
"attributes": {
"title": "Awesome podcast",
"number": 1,
"season": 2,
"status": "draft",
"published_at": null,
"duration": null,
"explicit": false,
"keywords": null,
"alternate_url": null,
"media_url": "https://media.transistor.fm/e19d4f00/ac912eb6.mp3",
"image_url": null,
"video_url": null,
"author": null,
"summary": "A podcast about awesome things",
"description": null,
"slug": null,
"created_at": "2024-12-07 05:23:18 UTC",
"updated_at": "2024-12-07 05:23:18 UTC",
"formatted_published_at": null,
"duration_in_mmss": "00:00",
"share_url": "https://share.transistor.fm/s/e19d4f00",
"transcript_url": null,
"transcripts": [],
"formatted_summary": "A podcast about awesome things",
"formatted_description": "",
"embed_html": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/e19d4f00\"></iframe>",
"embed_html_dark": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/e19d4f00/dark\"></iframe>",
"audio_processing": false,
"type": "full",
"email_notifications": null
},
"relationships": {
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
}
}
Update a single podcast episode. Note that publishing or unpublishing an episode involves a separate endpoint.
PATCH
/v1/episodes/:id
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Episode ID | |
episode[audio_url] | String | URL to an episode's new audio file | |
episode[transcript_text] | String | Full text of the episode transcript | |
episode[author] | String | Episode author | |
episode[description] | String | Longer episode description which may contain HTML and unformatted tags for chapters, people, supporters, etc | |
episode[explicit] | Boolean | Episode contains explicit content | |
episode[image_url] | String | Episode artwork image URL | |
episode[keywords] | String | Comma-separated list of keywords | |
episode[number] | Integer | Episode number | |
episode[season] | Integer | Season number | |
episode[summary] | String | Episode summary short description | |
episode[type] | String |
One of
|
Full, trailer, or bonus episode |
episode[title] | String | Episode title | |
episode[alternate_url] | String | Alternate episode URL overriding the share_url | |
episode[video_url] | String | YouTube video URL to be embedded on episode sharing pages and website pages | |
episode[email_notifications] | Boolean | Private podcast email notifications override (defaults to Show setting) |
A single Episode resource
$ curl https://api.transistor.fm/v1/episodes/3056098 -X PATCH \
-H "x-api-key: your_api_key" \
-d "episode[title]=Updated podcast" \
-d "fields[episode][]=title"
$ {
"data": {
"id": "3056098",
"type": "episode",
"attributes": {
"title": "Updated podcast"
},
"relationships": {}
}
}
Publish a single episode now or in the past, schedule for the future, or revert to a draft.
PATCH
/v1/episodes/:id/publish
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Episode ID | |
episode[status] Required | String |
One of
|
Publishing status: published, scheduled, or draft |
episode[published_at] | String | Episode publishing date and time - in your podcast's time zone |
A single Episode resource
$ curl https://api.transistor.fm/v1/episodes/3056098/publish -X PATCH \
-H "x-api-key: your_api_key" \
-d "episode[status]=published" \
-d "fields[episode][]=status"
$ {
"data": {
"id": "3056098",
"type": "episode",
"attributes": {
"status": "published"
},
"relationships": {}
}
}
Field | Type | Details | Description |
---|---|---|---|
private | Boolean | Filter for private shows | |
query | String | Search query | |
pagination[page] | Integer | Default: 0 | Page number |
pagination[per] | Integer | Default: 10 | Resources per page |
An array of Show resources
$ curl https://api.transistor.fm/v1/shows -G \
-H "x-api-key: your_api_key" \
-d "pagination[page]=1" \
-d "pagination[per]=5" \
-d "fields[show][]=title" \
-d "fields[show][]=description"
$ {
"data": [
{
"id": "132543",
"type": "show",
"attributes": {
"title": "The Caffeine Show",
"description": "A podcast covering all things coffee and caffeine"
},
"relationships": {}
}
],
"meta": {
"currentPage": 1,
"totalPages": 1,
"totalCount": 1
}
}
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Show ID or slug |
A single Show resource
$ curl https://api.transistor.fm/v1/shows/132543 -G \
-H "x-api-key: your_api_key"
$ {
"data": {
"id": "132543",
"type": "show",
"attributes": {
"author": null,
"category": "Arts :: Food",
"copyright": null,
"created_at": "2020-02-01 00:00:00 UTC",
"description": "A podcast covering all things coffee and caffeine",
"explicit": false,
"image_url": null,
"keywords": "coffee,caffeine,beans",
"language": "en",
"multiple_seasons": false,
"owner_email": null,
"playlist_limit": 25,
"private": false,
"secondary_category": "Arts",
"show_type": "episodic",
"slug": "the-caffeine-show",
"time_zone": null,
"title": "The Caffeine Show",
"updated_at": "2020-06-01 00:00:00 UTC",
"website": null,
"feed_url": "https://feeds.transistor.fm/the-caffeine-show",
"apple_podcasts": null,
"amazon_music": null,
"deezer": null,
"spotify": null,
"podcast_addict": null,
"player_FM": null,
"anghami": null,
"castbox": null,
"castro": null,
"goodpods": null,
"iHeartRadio": null,
"overcast": null,
"pandora": null,
"pocket_casts": null,
"soundcloud": null,
"tuneIn": null,
"fountain": null,
"jiosaavn": null,
"gaana": null,
"email_notifications": false
},
"relationships": {
"episodes": {
"data": []
}
}
}
}
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Show ID or slug | |
show[author] | String | Podcast author | |
show[category] | String |
One of
|
Primary category |
show[copyright] | String | Copyright information | |
show[description] | String | Podcast description | |
show[explicit] | Boolean | Podcast contains explicit content | |
show[image_url] | String | Podcast artwork image URL | |
show[keywords] | String | Comma-separated list of keywords | |
show[language] | String |
One of
|
Podcast's spoken language |
show[owner_email] | String | Podcast owner email | |
show[secondary_category] | String |
One of
|
Secondary category |
show[show_type] | String |
One of
|
Publishing type. Episodic displays newest episodes, serial displays oldest first |
show[title] | String | Podcast title | |
show[time_zone] | String |
One of
|
Publishing time zone |
show[website] | String | Podcast website |
A single Show resource
$ curl https://api.transistor.fm/v1/shows/132543 -X PATCH \
-H "x-api-key: your_api_key" \
-d "show[title]=Updated Title" \
-d "show[author]=Updated Author" \
-d "fields[show][]=title" \
-d "fields[show][]=author"
$ {
"data": {
"id": "132543",
"type": "show",
"attributes": {
"title": "Updated Title",
"author": "Updated Author"
},
"relationships": {}
}
}
Retrieve a list of all subscribers for a single private podcast.
GET
/v1/subscribers
Field | Type | Details | Description |
---|---|---|---|
show_id Required | String | Show ID or slug | |
query | String | Search query | |
pagination[page] | Integer | Default: 0 | Page number |
pagination[per] | Integer | Default: 10 | Resources per page |
An array of Subscriber resources
$ curl https://api.transistor.fm/v1/subscribers -G \
-H "x-api-key: your_api_key" \
-d show_id=132543 \
-d "pagination[page]=1" \
-d "pagination[per]=5" \
-d "fields[subscriber][]=email"
$ {
"data": [
{
"id": "709423",
"type": "subscriber",
"attributes": {
"email": "arthur@example.com"
},
"relationships": {}
},
{
"id": "709424",
"type": "subscriber",
"attributes": {
"email": "beatrice@example.com"
},
"relationships": {}
}
],
"meta": {
"currentPage": 1,
"totalPages": 1,
"totalCount": 2
}
}
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Subscriber ID |
A single Subscriber resource
$ curl https://api.transistor.fm/v1/subscribers/709423 -G \
-H "x-api-key: your_api_key"
$ {
"data": {
"id": "709423",
"type": "subscriber",
"attributes": {
"email": "arthur@example.com",
"status": "default",
"feed_url": "https://subscribers.transistor.fm/a525f0993b659a",
"created_at": "2020-01-01 00:00:00 UTC",
"updated_at": "2020-06-01 00:00:00 UTC",
"last_notified_at": "2020-07-01 00:00:00 UTC",
"has_downloads": false,
"subscribe_url": "https://subscribe.transistor.fm/a525f0993b659a"
},
"relationships": {
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
}
}
Add a single subscriber to a private podcast, and send an optional instructional email.
POST
/v1/subscribers
Field | Type | Details | Description |
---|---|---|---|
show_id Required | String | Show ID or slug | |
email Required | String | Email address | |
skip_welcome_email | Boolean | Default: false | Do not send the instructional email |
A single Subscriber resource
$ curl https://api.transistor.fm/v1/subscribers -X POST \
-H "x-api-key: your_api_key" \
-d show_id=132543 \
-d email=carol@example.com \
-d "fields[subscriber][]=email"
$ {
"data": {
"id": "709427",
"type": "subscriber",
"attributes": {
"email": "carol@example.com"
},
"relationships": {}
}
}
Add a batch of multiple subscribers to a private podcast, and send them optional instructional emails.
POST
/v1/subscribers/batch
Field | Type | Details | Description |
---|---|---|---|
show_id Required | String | Show ID or slug | |
emails Required | [String] | Array of email addresses | |
skip_welcome_email | Boolean | Default: false | Do not send the instructional emails |
An array of Subscriber resources
$ curl https://api.transistor.fm/v1/subscribers/batch -X POST \
-H "x-api-key: your_api_key" \
-d show_id=132543 \
-d "emails[]=carol@example.com" \
-d "emails[]=derek@example.com" \
-d "fields[subscriber][]=email"
$ {
"data": [
{
"id": "709427",
"type": "subscriber",
"attributes": {
"email": "carol@example.com"
},
"relationships": {}
},
{
"id": "709428",
"type": "subscriber",
"attributes": {
"email": "derek@example.com"
},
"relationships": {}
}
]
}
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Subscriber ID | |
subscriber[email] Required | String | Subscriber's email address |
A single Subscriber resource
$ curl https://api.transistor.fm/v1/subscribers/709423 -X PATCH \
-H "x-api-key: your_api_key" \
-d "subscriber[email]=updated@example.com" \
-d "fields[subscriber][]=email"
$ {
"data": {
"id": "709423",
"type": "subscriber",
"attributes": {
"email": "updated@example.com"
},
"relationships": {}
}
}
Remove a single private podcast subscriber and revoke their access to the podcast.
DELETE
/v1/subscribers
Field | Type | Details | Description |
---|---|---|---|
show_id Required | String | Show ID or slug | |
email Required | String | Email address |
A single Subscriber resource
$ curl https://api.transistor.fm/v1/subscribers -X DELETE \
-H "x-api-key: your_api_key" \
-d show_id=132543 \
-d email=carol@example.com
$ {
"data": {
"id": "709423",
"type": "subscriber",
"attributes": {
"email": "carol@example.com",
"status": "default",
"feed_url": "https://subscribers.transistor.fm/3dfd2c264fb346",
"created_at": "2020-01-01 00:00:00 UTC",
"updated_at": "2020-06-01 00:00:00 UTC",
"last_notified_at": "2020-07-01 00:00:00 UTC",
"has_downloads": false,
"subscribe_url": "https://subscribe.transistor.fm/3dfd2c264fb346"
},
"relationships": {
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
}
}
Remove a single private podcast subscriber and revoke their access to the podcast.
DELETE
/v1/subscribers/:id
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Subscriber ID |
A single Subscriber resource
$ curl https://api.transistor.fm/v1/subscribers/709423 -X DELETE \
-H "x-api-key: your_api_key"
$ {
"data": {
"id": "709423",
"type": "subscriber",
"attributes": {
"email": "arthur@example.com",
"status": "default",
"feed_url": "https://subscribers.transistor.fm/9073bd32ab63d7",
"created_at": "2020-01-01 00:00:00 UTC",
"updated_at": "2020-06-01 00:00:00 UTC",
"last_notified_at": "2020-07-01 00:00:00 UTC",
"has_downloads": false,
"subscribe_url": "https://subscribe.transistor.fm/9073bd32ab63d7"
},
"relationships": {
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
}
}
Field | Type | Details | Description |
---|---|---|---|
show_id Required | String | Show ID or slug |
An array of Webhook resources
$ curl https://api.transistor.fm/v1/webhooks -G \
-H "x-api-key: your_api_key" \
-d show_id=132543
$ {
"data": [
{
"id": "104325",
"type": "webhook",
"attributes": {
"event_name": "episode_created",
"url": "http://example.com/incoming_web_hooks",
"created_at": null,
"updated_at": null
},
"relationships": {
"user": {
"data": {
"id": "173455",
"type": "user"
}
},
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
}
]
}
Field | Type | Details | Description |
---|---|---|---|
event_name Required | String |
One of
|
Name of webhook event |
show_id Required | String | Show ID or slug | |
url Required | String | Target URL for webhook delivery |
A single Webhook resource
$ curl https://api.transistor.fm/v1/webhooks -X POST \
-H "x-api-key: your_api_key" \
-d event_name=episode_created \
-d show_id=1 \
-d url=http://example.com/incoming_web_hooks
$ {
"data": {
"id": "104325",
"type": "webhook",
"attributes": {
"event_name": "episode_created",
"url": "http://example.com/incoming_web_hooks",
"created_at": null,
"updated_at": null
},
"relationships": {
"user": {
"data": {
"id": "173455",
"type": "user"
}
},
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
}
}
Field | Type | Details | Description |
---|---|---|---|
id Required | String | Webhook ID |
A single Webhook resource
$ curl https://api.transistor.fm/v1/webhooks/104325 -X DELETE \
-H "x-api-key: your_api_key"
$ {
"data": {
"id": "104325",
"type": "webhook",
"attributes": {
"event_name": "episode_created",
"url": "http://example.com/incoming_web_hooks",
"created_at": null,
"updated_at": null
},
"relationships": {
"user": {
"data": {
"id": "173455",
"type": "user"
}
},
"show": {
"data": {
"id": "132543",
"type": "show"
}
}
}
}
}
API Resources are data objects returned by successful API requests, representing Users, Shows, Episodes, Subscribers, Analytics, and Webhooks.
The current Transistor user account authenticated for the API.
Name | Type | Description |
---|---|---|
created_at | Datetime | Timestamp of creation |
image_url | String | Avatar image URL |
name | String | Full name |
time_zone | String | Current time zone |
updated_at | Datetime | Timestamp of last update |
An individual Transistor show (podcast).
Name | Type | Description |
---|---|---|
amazon_music | String | Amazon Music URL |
anghami | String | Anghami URL |
apple_podcasts | String | Apple Podcasts URL |
author | String | Podcast author |
castbox | String | Castbox URL |
castro | String | Castro URL |
category | String | Primary category |
copyright | String | Copyright information |
created_at | Datetime | Timestamp of creation |
deezer | String | Deezer URL |
description | String | Podcast description |
email_notifications | Boolean | Private podcast email notifications enabled or disabled |
explicit | Boolean | Podcast contains explicit content |
feed_url | String | Podcast RSS Feed URL |
fountain | String | Fountain URL |
gaana | String | Gaana URL |
goodpods | String | Goodpods URL |
iHeartRadio | String | iHeartRadio URL |
image_url | String | Podcast artwork image URL |
jiosaavn | String | JioSaavn URL |
keywords | String | Comma-separated list of keywords |
language | String | Podcast's spoken language |
multiple_seasons | Boolean | Podcast has multiple seasons |
overcast | String | Overcast URL |
owner_email | String | Podcast owner email |
pandora | String | Pandora URL |
player_FM | String | Player FM URL |
playlist_limit | Integer | Playlist embed player episode limit |
pocket_casts | String | Pocket Casts URL |
podcast_addict | String | Podcast Addict URL |
private | Boolean | Podcast is private and subscribers are managed by admins |
secondary_category | String | Secondary category |
show_type | String | Publishing type. Episodic displays newest episodes, serial displays oldest first |
slug | String | Podcast slug (used for API and RSS Feed URL) |
soundcloud | String | Soundcloud URL |
spotify | String | Spotify URL |
time_zone | String | Publishing time zone |
title | String | Podcast title |
tuneIn | String | TuneIn URL |
updated_at | Datetime | Timestamp of last update |
website | String | Podcast website |
Name | Type |
---|---|
episodes | An array of Episode resources |
subscribers | An array of Subscriber resources |
An individual Transistor podcast episode record.
Name | Type | Description |
---|---|---|
alternate_url | String | Alternate episode URL overriding the share_url |
audio_processing | Boolean | Denotes processing of audio after creating or updating the audio_url |
author | String | Episode author |
created_at | Datetime | Timestamp of creation |
description | String | Longer episode description which may contain HTML and unformatted tags for chapters, people, supporters, etc |
duration | Integer | Duration of episode in seconds |
duration_in_mmss | String | Duration of episode in minutes and seconds. e.g. 34:12 |
email_notifications | String | Private podcast email notifications override (defaults to Show setting) |
embed_html | String | Embeddable audio player HTML |
embed_html_dark | String | Dark theme of the embeddable audio player HTML |
explicit | Boolean | Episode contains explicit content |
formatted_description | String | HTML episode description including dynamic content like chapters, people, supporters, etc |
formatted_published_at | String | Formatted version of the published_at datetime field |
formatted_summary | String | Formatted episode summary short description |
image_url | String | Episode artwork image URL |
keywords | String | Comma-separated list of keywords |
media_url | String | Trackable audio MP3 URL |
number | Integer | Episode number |
published_at | Datetime | Episode publishing date and time - in your podcast's time zone |
season | Integer | Season number |
share_url | String | Social media sharing page URL |
slug | String | Slugified episode title used in Transistor websites. e.g. my-first-episode |
status | String | Publishing status: published, scheduled, or draft |
summary | String | Episode summary short description |
title | String | Episode title |
transcript_url | String | Shareable URL for the episode transcript |
transcripts | Array | An array of URLs to AI transcription formats |
type | String | Full, trailer, or bonus episode |
updated_at | Datetime | Timestamp of last update |
video_url | String | YouTube video URL to be embedded on episode sharing pages and website pages |
Name | Type |
---|---|
show | A single Show resource |
An individual subscriber record for a private podcast.
Name | Type | Description |
---|---|---|
created_at | Datetime | Timestamp of creation |
String | Subscriber's email address | |
feed_url | String | URL for subscriber's unique RSS Feed |
has_downloads | Boolean | Subscriber has downloaded at least one episode |
last_notified_at | Datetime | Timestamp of when subscriber was last emailed |
status | String | Email notification status - default, subscribed, or unsubscribed |
subscribe_url | String | URL for subscriber's private landing page |
updated_at | Datetime | Timestamp of last update |
Name | Type |
---|---|
show | A single Show resource |
Download analytics per day for a single podcast.
Name | Type | Description |
---|---|---|
downloads | Array | An array of download counts per day |
end_date | String | Ending date of the analytics date range |
start_date | String | Starting date of the analytics date range |
Name | Type |
---|---|
show | A single Show resource |
Download analytics per day for all episodes of a single podcast.
Name | Type | Description |
---|---|---|
end_date | String | |
episodes | Array | |
start_date | String |
Name | Type |
---|---|
show | A single Show resource |
Download analytics per day for a single episode.
Name | Type | Description |
---|---|---|
downloads | Array | An array of download counts per day |
end_date | String | Ending date of the analytics date range |
start_date | String | Starting date of the analytics date range |
Name | Type |
---|---|
episode | A single Episode resource |
Authorized audio upload resource, including the upload_url to upload the audio file to, and the content_type to use when uploading.
Name | Type | Description |
---|---|---|
audio_url | String | URL of your audio file after uploading is complete. To be used when creating or updating an episode |
content_type | String | Content type of the file to upload. audio/mpeg, audio/wav, etc |
expires_in | Integer | Amount of time in seconds before the authorized upload URL expires |
upload_url | String | Endpoint URL to upload your audio file to using HTTP PUT |
An individual subscription to a Transistor webhook. Limited to a maximum of 50 webhooks per user account.
Name | Type | Description |
---|---|---|
created_at | String | Timestamp of creation |
event_name | String | Name of webhook event |
updated_at | String | Timestamp of last update |
url | String | Target URL for webhook delivery |
Name | Type |
---|---|
user | A single User resource |
show | A single Show resource |