Transistor API

The Transistor API is built around the JSON:API specification. Our API allows you to manage podcasts, episodes, and private podcast subscribers. Endpoints accept JSON or form-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes.

Authentication

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.


Endpoints

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.

Sparse fieldsets

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.

Including related resources

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.

Root

Get authenticated user

Retrieve details of the user account that is authenticating to the API.

GET /v1

Parameters

None.

Response

A single User resource

Example

Request

$ curl https://api.transistor.fm/v1 -G \
  -H "x-api-key: {api_key}"

Response

$ {
  "data": {
    "id": "1",
    "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"
    }
  }
}

Shows

Get shows

Retrieve a paginated list of shows in descending order by updated date.

GET /v1/shows

Parameters

Field Type Details Description
private Boolean Filter for private shows
query String Search query
pagination Hash
pagination[page] Integer Default: 0 Page number
pagination[per] Integer Default: 10 Resources per page

Response

An array of Show resources

Example

Request

$ curl https://api.transistor.fm/v1/shows -G \
  -H "x-api-key: {api_key}" \
  -d "pagination[page]=1" \
  -d "pagination[per]=5" \
  -d "fields[show][]=title" \
  -d "fields[show][]=description"

Response

$ {
  "data": [
    {
      "id": "1",
      "type": "show",
      "attributes": {
        "title": "The Caffeine Show",
        "description": "A podcast covering all things coffee and caffeine"
      },
      "relationships": {}
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 1
  }
}

Get a show

Retrive a single show (podcast).

GET /v1/shows/:id

Parameters

Field Type Details Description
id Required String Show ID or slug

Response

A single Show resource

Example

Request

$ curl https://api.transistor.fm/v1/shows/:id -G \
  -H "x-api-key: {api_key}"

Response

$ {
  "data": {
    "id": "1",
    "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,
      "password_protected_feed": false,
      "breaker": null,
      "castbox": null,
      "castro": null,
      "feed_url": "https://feeds.transistor.fm/the-caffeine-show",
      "google_podcasts": null,
      "iHeartRadio": null,
      "overcast": null,
      "pandora": null,
      "pocket_casts": null,
      "radioPublic": null,
      "soundcloud": null,
      "stitcher": null,
      "tuneIn": null,
      "spotify": null,
      "apple_podcasts": null
    },
    "relationships": {
      "episodes": {
        "data": []
      }
    }
  }
}

Update a show

Update a show with any or all of the following attributes.

PATCH /v1/shows/:id

Parameters

Field Type Details Description
id Required String Show ID or slug
show Required Hash
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

Response

A single Show resource

Example

Request

$ curl https://api.transistor.fm/v1/shows/:id -X PATCH \
  -H "x-api-key: {api_key}" \
  -d "show[title]=Updated Title" \
  -d "show[author]=Updated Author" \
  -d "fields[show][]=title" \
  -d "fields[show][]=author"

Response

$ {
  "data": {
    "id": "1",
    "type": "show",
    "attributes": {
      "title": "Updated Title",
      "author": "Updated Author"
    },
    "relationships": {}
  }
}

Episodes

Get episodes

Retrieve a paginated list of episodes in descending order by published date.

GET /v1/episodes

Parameters

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
pagination Hash
pagination[page] Integer Default: 0 Page number
pagination[per] Integer Default: 10 Resources per page

Response

An array of Episode resources

Example

Request

$ curl https://api.transistor.fm/v1/episodes -G \
  -H "x-api-key: {api_key}" \
  -d show_id=1 \
  -d "pagination[page]=1" \
  -d "pagination[per]=5" \
  -d "fields[episode][]=title" \
  -d "fields[episode][]=summary"

Response

$ {
  "data": [
    {
      "id": "1",
      "type": "episode",
      "attributes": {
        "title": "How To Roast Coffee",
        "summary": "A primer on roasting coffee"
      },
      "relationships": {}
    },
    {
      "id": "2",
      "type": "episode",
      "attributes": {
        "title": "The Effects of Caffeine",
        "summary": "A lightly scientific overview on how caffeine affects the brain"
      },
      "relationships": {}
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 2
  }
}

Get an episode

Retrieve a single podcast episode.

GET /v1/episodes/:id

Parameters

Field Type Details Description
id Required String Episode ID

Response

A single Episode resource

Example

Request

$ curl https://api.transistor.fm/v1/episodes/:id -G \
  -H "x-api-key: {api_key}" \
  -d "include[]=show" \
  -d "fields[show][]=title" \
  -d "fields[show][]=summary"

Response

$ {
  "data": {
    "id": "1",
    "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",
      "media_url": "https://media.transistor.fm/ffecbd39.mp3",
      "image_url": null,
      "author": "Jimmy Podcaster",
      "summary": "A primer on roasting coffee",
      "description": "This podcast talks about some <strong>strong</strong> coffee!",
      "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/a2abe547",
      "formatted_summary": "A primer on roasting coffee",
      "embed_html": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/a2abe547\"></iframe>",
      "embed_html_dark": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/a2abe547/dark\"></iframe>",
      "audio_processing": false,
      "type": "full"
    },
    "relationships": {
      "show": {
        "data": {
          "id": "1",
          "type": "show"
        }
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "show",
      "attributes": {
        "title": "The Caffeine Show"
      },
      "relationships": {}
    }
  ]
}

Create an episode

Create a new draft episode for the specified show. Note that publishing an episode involves a separate endpoint.

POST /v1/episodes

Parameters

Field Type Details Description
episode Required Hash
episode[show_id] Required String Show ID or slug
episode[audio_url] String URL to an episode's new audio file
episode[author] String Episode author
episode[description] String Longer episode description which may contain HTML
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

Response

A single Episode resource

Example

Request

$ curl https://api.transistor.fm/v1/episodes -X POST \
  -H "x-api-key: {api_key}" \
  -d show_id=1 \
  -d "episode[title]=Awesome podcast" \
  -d "episode[summary]=A podcast about awesome things" \
  -d "episode[season]=2" \
  -d "episode[number]=1"

Response

$ {
  "data": {
    "id": "1",
    "type": "episode",
    "attributes": {
      "title": "Awesome podcast",
      "number": 1,
      "season": 2,
      "status": "draft",
      "published_at": null,
      "duration": null,
      "explicit": false,
      "keywords": null,
      "media_url": "https://media.transistor.fm/10336c33.mp3",
      "image_url": null,
      "author": null,
      "summary": "A podcast about awesome things",
      "description": null,
      "created_at": "2020-10-25 05:48:47 UTC",
      "updated_at": "2020-10-25 05:48:47 UTC",
      "formatted_published_at": null,
      "duration_in_mmss": "00:00",
      "share_url": "https://share.transistor.fm/s/04156187",
      "formatted_summary": "A podcast about awesome things",
      "embed_html": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/04156187\"></iframe>",
      "embed_html_dark": "<iframe width=\"100%\" height=\"180\" frameborder=\"no\" scrolling=\"no\" seamless src=\"https://share.transistor.fm/e/04156187/dark\"></iframe>",
      "audio_processing": false,
      "type": "full"
    },
    "relationships": {
      "show": {
        "data": {
          "id": "1",
          "type": "show"
        }
      }
    }
  }
}

Update an episode

Update a single podcast episode. Note that publishing or unpublishing an episode involves a separate endpoint.

PATCH /v1/episodes/:id

Parameters

Field Type Details Description
id Required String Episode ID
episode Required Hash
episode[audio_url] String URL to an episode's new audio file
episode[author] String Episode author
episode[description] String Longer episode description which may contain HTML
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

Response

A single Episode resource

Example

Request

$ curl https://api.transistor.fm/v1/episodes/:id -X PATCH \
  -H "x-api-key: {api_key}" \
  -d "episode[title]=Updated podcast" \
  -d "fields[episode][]=title"

Response

$ {
  "data": {
    "id": "1",
    "type": "episode",
    "attributes": {
      "title": "Updated podcast"
    },
    "relationships": {}
  }
}

Publish, schedule, or unpublish an episode

Publish a single episode now or in the past, schedule for the future, or revert to a draft.

PATCH /v1/episodes/:id/publish

Parameters

Field Type Details Description
id Required String Episode ID
episode Required Hash
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

Response

A single Episode resource

Example

Request

$ curl https://api.transistor.fm/v1/episodes/:id/publish -X PATCH \
  -H "x-api-key: {api_key}" \
  -d "episode[status]=published" \
  -d "fields[episode][]=status"

Response

$ {
  "data": {
    "id": "1",
    "type": "episode",
    "attributes": {
      "status": "published"
    },
    "relationships": {}
  }
}

Subscribers

Get a list of subscribers

Retrieve a list of all subscribers for a single private podcast.

GET /v1/subscribers

Parameters

Field Type Details Description
show_id Required String Show ID or slug
query String Search query
pagination Hash
pagination[page] Integer Default: 0 Page number
pagination[per] Integer Default: 10 Resources per page

Response

An array of Subscriber resources

Example

Request

$ curl https://api.transistor.fm/v1/subscribers -G \
  -H "x-api-key: {api_key}" \
  -d show_id=1 \
  -d "pagination[page]=1" \
  -d "pagination[per]=5" \
  -d "fields[subscriber][]=email"

Response

$ {
  "data": [
    {
      "id": "1",
      "type": "subscriber",
      "attributes": {
        "email": "[email protected]"
      },
      "relationships": {}
    },
    {
      "id": "2",
      "type": "subscriber",
      "attributes": {
        "email": "[email protected]"
      },
      "relationships": {}
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 1,
    "totalCount": 2
  }
}

Retrieve a single private podcast subscriber.

GET /v1/subscribers/:id

Parameters

Field Type Details Description
id Required String Subscriber ID

Response

A single Subscriber resource

Example

Request

$ curl https://api.transistor.fm/v1/subscribers/:id -G \
  -H "x-api-key: {api_key}"

Response

$ {
  "data": {
    "id": "1",
    "type": "subscriber",
    "attributes": {
      "email": "[email protected]",
      "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/bb8242a0b48ec5"
    },
    "relationships": {
      "show": {
        "data": {
          "id": "1",
          "type": "show"
        }
      }
    }
  }
}

Create a single subscriber

Add a single subscriber to a private podcast, and send an instructional email.

POST /v1/subscribers

Parameters

Field Type Details Description
show_id Required String Show ID or slug
email Required String Email address

Response

A single Subscriber resource

Example

Request

$ curl https://api.transistor.fm/v1/subscribers -X POST \
  -H "x-api-key: {api_key}" \
  -d show_id=1 \
  -d email=[email protected] \
  -d "fields[subscriber][]=email"

Response

$ {
  "data": {
    "id": "3",
    "type": "subscriber",
    "attributes": {
      "email": "[email protected]"
    },
    "relationships": {}
  }
}

Create multiple subscribers

Add a batch of multiple subcsribers to a private podcast, and send them instructional emails.

POST /v1/subscribers/batch

Parameters

Field Type Details Description
show_id Required String Show ID or slug
emails Required [String] Array of email addresses

Response

An array of Subscriber resources

Example

Request

$ curl https://api.transistor.fm/v1/subscribers/batch -X POST \
  -H "x-api-key: {api_key}" \
  -d show_id=1 \
  -d "emails[][email protected]" \
  -d "emails[][email protected]" \
  -d "fields[subscriber][]=email"

Response

$ {
  "data": [
    {
      "id": "3",
      "type": "subscriber",
      "attributes": {
        "email": "[email protected]"
      },
      "relationships": {}
    },
    {
      "id": "4",
      "type": "subscriber",
      "attributes": {
        "email": "[email protected]"
      },
      "relationships": {}
    }
  ]
}

Update a single subscriber

Update a single private podcast subscriber.

PATCH /v1/subscribers/:id

Parameters

Field Type Details Description
id Required String Subscriber ID
subscriber Required Hash
subscriber[email] Required String Subscriber's email address

Response

A single Subscriber resource

Example

Request

$ curl https://api.transistor.fm/v1/subscribers/:id -X PATCH \
  -H "x-api-key: {api_key}" \
  -d "subscriber[email][email protected]" \
  -d "fields[subscriber][]=email"

Response

$ {
  "data": {
    "id": "1",
    "type": "subscriber",
    "attributes": {
      "email": "[email protected]"
    },
    "relationships": {}
  }
}

Delete a single subscriber by email address

Remove a single private podcast subscriber and revoke their access to the podcast.

DELETE /v1/subscribers

Parameters

Field Type Details Description
show_id Required String Show ID or slug
email Required String Email address

Response

A single Subscriber resource

Example

Request

$ curl https://api.transistor.fm/v1/subscribers -X DELETE \
  -H "x-api-key: {api_key}" \
  -d show_id=1 \
  -d email=[email protected]

Response

$ {
  "data": {
    "id": "1",
    "type": "subscriber",
    "attributes": {
      "email": "[email protected]",
      "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/bc3fbcd09298e4"
    },
    "relationships": {
      "show": {
        "data": {
          "id": "1",
          "type": "show"
        }
      }
    }
  }
}

Delete a single subscriber by ID

Remove a single private podcast subscriber and revoke their access to the podcast.

DELETE /v1/subscribers/:id

Parameters

Field Type Details Description
id Required String Subscriber ID

Response

A single Subscriber resource

Example

Request

$ curl https://api.transistor.fm/v1/subscribers/:id -X DELETE \
  -H "x-api-key: {api_key}"

Response

$ {
  "data": {
    "id": "1",
    "type": "subscriber",
    "attributes": {
      "email": "[email protected]",
      "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/bcf87c7a37bc63"
    },
    "relationships": {
      "show": {
        "data": {
          "id": "1",
          "type": "show"
        }
      }
    }
  }
}

Webhooks

Subscribe to webhook

Subscribe to a webhook with the given event name and show.

POST /v1/webhooks

Parameters

Field Type Details Description
event_name Required String
One of
Event name
show_id Required String Podcast show ID
url Required String Target URL

Response

A single Webhook resource

Example

Request

$ curl https://api.transistor.fm/v1/webhooks -X POST \
  -H "x-api-key: {api_key}" \
  -d "fields[event_name]=episode_created" \
  -d "fields[show_id]=1" \
  -d "fields[url]=http://example.com/incoming_web_hooks"

Response

$ {
  "data": {
    "id": "1",
    "type": "webhook",
    "attributes": {
      "event_name": "episode_created",
      "url": "http://example.com/incoming_web_hooks",
      "created_at": null,
      "updated_at": null
    },
    "relationships": {
      "user": {
        "data": {
          "id": "1",
          "type": "user"
        }
      },
      "show": {
        "data": {
          "id": "1",
          "type": "show"
        }
      }
    }
  }
}

Unsubscribe from webhook

Unsubscribe from a webhook.

DELETE /v1/webhooks/:id

Parameters

Field Type Details Description
id Required String Webhook ID

Response

A single Webhook resource

Example

Request

$ curl https://api.transistor.fm/v1/webhooks/:id -X DELETE \
  -H "x-api-key: {api_key}"

Response

$ {
  "data": {
    "id": "1",
    "type": "webhook",
    "attributes": {
      "event_name": "episode_created",
      "url": "http://example.com/incoming_web_hooks",
      "created_at": null,
      "updated_at": null
    },
    "relationships": {
      "user": {
        "data": {
          "id": "1",
          "type": "user"
        }
      },
      "show": {
        "data": {
          "id": "1",
          "type": "show"
        }
      }
    }
  }
}

Resources

API Resources are data objects returned by successful API requests, representing a Shows, Episodes, or Subscribers.

User

The current Transistor user account authenticated for the API.

Fields

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

Relationships

None.

Show

An individual Transistor show (podcast).

Fields

Name Type Description
apple_podcasts String Apple Podcasts URL
author String Podcast author
breaker String Breaker URL
castbox String Castbox URL
castro String Castro URL
category String Primary category
copyright String Copyright information
created_at Datetime Timestamp of creation
description String Podcast description
explicit Boolean Podcast contains explicit content
feed_url String Podcast RSS Feed URL
google_podcasts String Google Podcasts URL
iHeartRadio String iHeartRadio URL
image_url String Podcast artwork image 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
password_protected_feed Boolean Podcast requires a password for access
playlist_limit Integer Playlist embed player episode limit
pocket_casts String Pocket Casts URL
private Boolean Podcast is private and subscribers are managed by admins
radioPublic String RadioPublic URL
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
stitcher String Stitcher 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

Relationships

Name Type
episodes An array of Episode resources
subscribers An array of Subscriber resources

Episode

An individual Transistor podcast episode record.

Fields

Name Type Description
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
duration Integer Duration of episode in seconds
duration_in_mmss String Duration of episode in minutes and seconds. e.g. 34:12
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_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
status String Publishing status: published, scheduled, or draft
summary String Episode summary short description
title String Episode title
type String Full, trailer, or bonus episode
updated_at Datetime Timestamp of last update

Relationships

Name Type
show A single Show resource

Subscriber

An individual subscriber record for an enhanced private podcast.

Fields

Name Type Description
created_at Datetime Timestamp of creation
email String Subscriber's email address
has_downloads Boolean Subscriber has downloaded at least one episode
last_notified_at Datetime Timestamp of when subscriber was last emailed
subscribe_url String URL for subscriber's private landing page
updated_at Datetime Timestamp of last update

Relationships

Name Type
show A single Show resource

Webhook

An individual subscription to a Transistor webhook. Limited to a maximum of 50 webhooks per user account.

Fields

Name Type Description
created_at String
event_name String
updated_at String
url String

Relationships

Name Type
user A single User resource
show A single Show resource

Back to the top