> For the complete documentation index, see [llms.txt](https://docs.castmagic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.castmagic.io/endpoints/speakers.md).

# 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](#speaker-assignment-on-a-recording).

{% hint style="info" %}
**Tier:** reads (`GET`) are `core`; all writes — creating/updating speakers and assigning/unassigning labels — require `automation`. Base URL `https://app.castmagic.io`.
{% endhint %}

## List speakers

<mark style="color:blue;">`GET`</mark> `https://app.castmagic.io/v1/spaces/:space_id/speakers`

**Tier:** `core`

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "space": { "id": "a1...", "name": "Acme Podcast" },
    "speakers": [
        {
            "id": "s1...",
            "name": "Jane Doe",
            "email": "jane@example.com",
            "bio": "Host of Acme Podcast",
            "pronouns": "she/her",
            "role": "Host",
            "ai_summary": "Frequently discusses pricing strategy..."
        }
    ],
    "count": 1
}
```

{% endtab %}
{% endtabs %}

## Create a speaker

<mark style="color:green;">`POST`</mark> `https://app.castmagic.io/v1/spaces/:space_id/speakers`

**Tier:** `automation`

#### Request Body

| Name                                   | Type   | Description                                           |
| -------------------------------------- | ------ | ----------------------------------------------------- |
| name<mark style="color:red;">\*</mark> | 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                                 |

{% hint style="info" %}
`role` is matched by name against the space's existing roles. If the space has no roles yet, a `Guest` role is created automatically.
{% endhint %}

{% tabs %}
{% tab title="201: Created" %}

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

{% endtab %}
{% endtabs %}

## Update a speaker

<mark style="color:orange;">`PATCH`</mark> `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.

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "speaker": {
        "id": "s2...",
        "name": "John Roe",
        "email": "john@example.com",
        "bio": "Guest expert",
        "pronouns": "he/him",
        "role": "Guest",
        "ai_summary": null
    }
}
```

{% endtab %}

{% tab title="404: Not Found" %}

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

{% endtab %}
{% endtabs %}

## 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

<mark style="color:blue;">`GET`</mark> `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](#list-speakers).

{% tabs %}
{% tab title="200: OK" %}

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

{% endtab %}
{% endtabs %}

### Assign a label to a speaker

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark>       | String | A label present in the recording's transcript |
| speaker\_id<mark style="color:red;">\*</mark> | String | Id of a speaker in the recording's space      |

{% tabs %}
{% tab title="200: OK" %}

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

{% endtab %}

{% tab title="400: Bad Request Label not in transcript" %}

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

{% endtab %}

{% tab title="404: Not Found Speaker not in this space" %}

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

{% endtab %}
{% endtabs %}

### Unassign a label

<mark style="color:green;">`POST`</mark> `https://app.castmagic.io/v1/recordings/:id/speakers/unassign`

**Tier:** `automation`

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

{% tabs %}
{% tab title="200: OK" %}

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

{% endtab %}
{% endtabs %}