Speakers

List, create, and update the speakers in a space, and assign them to transcript speaker labels on a recording.

Speakers are people who appear across a space's recordings. Each speaker can carry a name, contact details, a bio, pronouns, and a role. Once a recording is transcribed, you can map its raw transcript labels (Speaker 0, Speaker 1, …) to space speakers — see Speaker assignment on a recording.

Tier: reads (GET) are core; all writes — creating/updating speakers and assigning/unassigning labels — require automation. Base URL https://app.castmagic.io.

List speakers

GET https://app.castmagic.io/v1/spaces/:space_id/speakers

Tier: core

200: OK

{
    "space": { "id": "a1...", "name": "Acme Podcast" },
    "speakers": [
        {
            "id": "s1...",
            "name": "Jane Doe",
            "email": "[e-mail]",
            "bio": "Host of Acme Podcast",
            "pronouns": "she/her",
            "role": "Host",
            "ai_summary": "Frequently discusses pricing strategy..."
        }
    ],
    "count": 1
}

Create a speaker

POST https://app.castmagic.io/v1/spaces/:space_id/speakers

Tier: automation

Request Body

Name	Type	Description
name*	String	Speaker name
email	String	Contact email
bio	String	Short biography
pronouns	String	e.g. she/her
role	String	Role name, e.g. Host or Guest (resolved in-space)
emoji	String	Optional avatar emoji

role is matched by name against the space's existing roles. If the space has no roles yet, a Guest role is created automatically.

201: Created

{
    "speaker": {
        "id": "s2...",
        "name": "John Roe",
        "email": null,
        "bio": null,
        "pronouns": null,
        "role": "Guest",
        "ai_summary": null
    }
}

Update a speaker

PATCH https://app.castmagic.io/v1/speakers/:id

Tier: automation

Update any of name, email, bio, pronouns, emoji, or speaker_role_id. A supplied speaker_role_id must belong to the speaker's space.

200: OK

{
    "speaker": {
        "id": "s2...",
        "name": "John Roe",
        "email": "[e-mail]",
        "bio": "Guest expert",
        "pronouns": "he/him",
        "role": "Guest",
        "ai_summary": null
    }
}

404: Not Found

{ "error": "Speaker not found: s2..." }

Speaker assignment on a recording

A completed transcript has raw speaker labels (Speaker 0, Speaker 1, …). These endpoints read those labels and map each one to a speaker in the recording's space.

List a recording's speaker labels

GET https://app.castmagic.io/v1/recordings/:id/speakers

Tier: core

Returns every transcript label and the space speaker it's assigned to, or null if unassigned. speaker has the same shape as the space speakers list.

200: OK

{
    "recording": { "id": "e1...", "title": "Episode 12 — Pricing" },
    "speaker_labels": [
        {
            "label": "Speaker 0",
            "speaker": {
                "id": "s1...",
                "name": "Jane Doe",
                "email": "[e-mail]",
                "bio": "Host of Acme Podcast",
                "pronouns": "she/her",
                "role": "Host",
                "ai_summary": null
            }
        },
        { "label": "Speaker 1", "speaker": null }
    ],
    "count": 2
}

Assign a label to a speaker

POST https://app.castmagic.io/v1/recordings/:id/speakers/assign

Tier: automation

Map a transcript label to a space speaker. Replaces any existing assignment for that label.

Request Body

Name	Type	Description
label*	String	A label present in the recording's transcript
speaker_id*	String	Id of a speaker in the recording's space

200: OK

{
    "assigned": {
        "label": "Speaker 0",
        "speaker": { "id": "s1...", "name": "Jane Doe", "role": "Host", "...": "..." }
    }
}

400: Bad Request Label not in transcript

{ "error": "label not found in transcript. Labels: Speaker 0, Speaker 1" }

404: Not Found Speaker not in this space

{ "error": "Speaker not found in this space: s9..." }

Unassign a label

POST https://app.castmagic.io/v1/recordings/:id/speakers/unassign

Tier: automation

Remove a label's assignment. Takes the same label and speaker_id body.

200: OK

{
    "unassigned": { "label": "Speaker 0", "speaker_id": "s1..." }
}