Documentation

Feed anatomy, the publishing API, and how to move an existing show without losing subscribers.

Migrating in

Point us at your current feed. We copy every enclosure, rewrite the URLs, and give you a redirect record to put on the old host so existing subscribers follow automatically.

import.sh

longform import --feed https://old-host.example/feed.xml \
  --show 'The Long Way Round' --keep-guids

# 312 episodes · 41.2 GB · done in 6m14s

Keep --keep-guids unless you want every subscriber's app to re-download the entire back catalogue. We have seen a migration generate 40 TB of pointless traffic because a GUID scheme changed.

Feed anatomy

We emit RSS 2.0 with the iTunes and Podcasting 2.0 namespaces. Everything below is generated for you, but you can override any field per episode.

episode.json

{
  "title": "142 — The last switchboard operator",
  "guid": "lf_9c31f0a2",
  "enclosure": {
    "url": "https://cdn.as.13381338.xyz/e/lf_9c31f0a2.mp3",
    "length": 86114304,
    "type": "audio/mpeg"
  },
  "duration": 5642,
  "transcript": "https://cdn.as.13381338.xyz/t/lf_9c31f0a2.vtt",
  "chapters": "https://cdn.as.13381338.xyz/c/lf_9c31f0a2.json"
}

Authentication

Bearer tokens scoped to a show or to the whole account. Tokens for analytics can be made read-only and time-boxed, which is how you give an advertiser access.

Episodes

Method	Path	Purpose
`GET`	`/v1/shows/{id}/episodes`	list with cursor
`POST`	`/v1/shows/{id}/episodes`	create, returns an upload URL
`PATCH`	`/v1/episodes/{id}`	edit metadata or schedule
`POST`	`/v1/episodes/{id}/publish`	publish now or at a time
`DELETE`	`/v1/episodes/{id}`	unpublish and tombstone

Ad markers

Mark break points in the master and let the ad server fill them at request time. Markers are sample-accurate and survive re-encoding.

json

{"breaks": [{"at": 0, "max": 1},
            {"at": 942.5, "max": 2},
            {"at": 2411.0, "max": 2},
            {"at": -1, "max": 1}]}

Private feeds

Each subscriber gets a feed URL containing an opaque token. Revoking a membership invalidates the token on the next poll, and already-downloaded episodes are not clawed back — because they cannot be.

Analytics export

Daily CSV drops to your own object storage, or pull it: GET /v1/shows/{id}/analytics?from=2026-07-01&granularity=day. Rows are immutable after the 48-hour correction window.