Recordings
List, fetch, and create recordings, and read their transcripts and outputs.
A recording is a piece of media (audio or video) in a space, together with its transcript and any AI-generated outputs. This is the recording-centric flow — as opposed to Transcripts, which transcribes a URL without creating anything.
To create a recording you either upload a file and call POST /v1/recordings with the returned object_id, or import from a URL.
List recordings
GET https://app.castmagic.io/v1/recordings
Newest-first. Results are paginated with an opaque cursor — see Pagination below.
Query Parameters
space_id
String
Restrict to one space
query
String
Match against recording titles
limit
Integer
Default 25, max 100
cursor
String
A next_cursor from a previous page, to fetch the next
{
"recordings": [
{
"id": "e1...",
"title": "Episode 12 — Pricing",
"space": { "id": "a1...", "name": "Acme Podcast" },
"created_at": "2026-08-21T22:00:00Z",
"published_at": null,
"language": "en",
"transcript_status": "completed",
"duration_minutes": 42,
"has_transcript": true,
"number": 12,
"episode_number": 12,
"season_number": 2,
"rss": {
"guid": "acme-ep-12",
"published_at": "2026-08-20T14:00:00Z",
"episode_number": 12
}
}
],
"count": 1,
"next_cursor": "MjAyNi0wOC0yMVQyMjowMDowMHxlMS4uLg"
}Pagination
The list is paginated newest-first with a keyset cursor. To walk the full library, request pages until next_cursor is null, passing each response's next_cursor as the next request's cursor:
Cursors are opaque — don't construct or parse them; an unrecognizable cursor returns 400. A page may contain fewer items than limit (recordings in inactive spaces are filtered out) yet still carry a next_cursor, so always page until it is null rather than stopping on a short page.
Recording fields
number
Castmagic's per-space ordinal for the recording (assigned on creation)
episode_number
Podcast episode number, when set
season_number
Podcast season number, when set
published_at
When the recording appeared in Castmagic
rss
Feed provenance for RSS-imported recordings (see below); null for uploads and URL imports
For recordings imported from an RSS feed, rss carries the feed's own identifiers — distinct from published_at (which is when it appeared in Castmagic):
rss field
Description
guid
The feed item's GUID
published_at
The feed's original publish date
episode_number
The feed's <itunes:episode> number, when set
Fetch a recording
GET https://app.castmagic.io/v1/recordings/:id
Returns a single recording, wrapped under recording, with the same shape as the list items above.
Create a recording
POST https://app.castmagic.io/v1/recordings
Create a recording from an uploaded object and start transcription. Numbering is automatic. Transcription and — if the space has it enabled — content generation run automatically, so subscribe a webhook to transcript.completed and output.completed instead of polling.
Request Body
object_id*
String
The object_id from POST /v1/uploads
space_id
String
Defaults to the upload's space
title
String
Defaults to the uploaded filename
language
String
Language code for transcription
speakers_expected
Integer
Hint for the number of speakers
context_prompt
String
Context to guide transcription and generation
Fetch a recording's transcript
GET https://app.castmagic.io/v1/recordings/:id/transcript
Requires a completed transcript (400 otherwise). json returns speaker utterances; text and document formats return the raw body with a matching content type.
Query Parameters
format
String
json (default) · txt · vtt · srt · csv · pdf · docx
language
String
Translate to a supported language code (requires automation); preserves the space's custom spellings and boosted words
include_timestamp
Boolean
false to omit timestamps from txt
Fetch a recording's outputs
GET https://app.castmagic.io/v1/recordings/:id/outputs
Generated content for a recording. text is markdown for AI-written items. Pass type to filter to one output type (e.g. episode_overview).
Query Parameters
type
String
Filter to a single output type
Last updated