> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Recordings API

> Fetch recordings and transcripts through the BuildBetter REST API.

Use the Recordings REST API when you need stable recording resources or transcript output from an organization API key. This is the supported path for new recording and transcript integrations.

```bash theme={null}
X-BuildBetter-Api-Key: ORGANIZATION_API_KEY
```

Base URL:

```text theme={null}
https://api.buildbetter.app/v3/rest
```

<Warning>
  The GraphQL API is being deprecated for customer integrations. Move recording and transcript reads to the REST endpoints below. GraphQL `interview.monologues` is deprecated as of Wednesday, July 1, 2026.
</Warning>

## Recording IDs

Recording IDs are transitioning from internal BigInt IDs to public UUIDs. REST recording endpoints accept and return the public UUID value.

GraphQL still exposes `interview.id` as a BigInt for existing legacy queries. If your integration currently stores GraphQL BigInt IDs, plan to store the public recording UUID as you migrate REST recording reads. New and backfilled public IDs are UUIDv7 values.

## Get a recording

<Card title="GET /recordings/{recordingId}" icon="file-audio">
  Fetch one recording by public UUID.

  ```bash theme={null}
  GET https://api.buildbetter.app/v3/rest/recordings/01905241-7d4a-7c48-9c14-83f4f65d52f1
  X-BuildBetter-Api-Key: ORGANIZATION_API_KEY
  ```

  **Response:**

  ```json theme={null}
  {
    "id": "01905241-7d4a-7c48-9c14-83f4f65d52f1",
    "display_name": "Product Review Meeting",
    "source": "zoom",
    "started_at": "2026-06-18T17:00:00.000Z",
    "completed_at": "2026-06-18T17:30:00.000Z",
    "asset_url": "https://storage.example.com/presigned-recording-url",
    "asset_duration_seconds": 1800,
    "transcript_status": "completed",
    "summary": "The team reviewed recent customer feedback.",
    "metadata": []
  }
  ```
</Card>

`asset_uri` is never returned. `asset_url` is derived from the stored asset URI at request time and should be treated as a presigned URL that may expire.

## Get a transcript

<Card title="GET /recordings/{recordingId}/transcript" icon="file-lines">
  Fetch transcript text for one recording. Use the optional `type` query parameter to choose the transcript shape.

  ```bash theme={null}
  GET https://api.buildbetter.app/v3/rest/recordings/01905241-7d4a-7c48-9c14-83f4f65d52f1/transcript?type=utterance
  X-BuildBetter-Api-Key: ORGANIZATION_API_KEY
  ```

  `type` can be:

  * `utterance`: sentence-level transcript rows.
  * `monologue`: contiguous same-speaker transcript rows.

  When `type` is omitted, the API returns `utterance`.
</Card>

### Utterance response

```json theme={null}
{
  "type": "utterance",
  "recordingId": "01905241-7d4a-7c48-9c14-83f4f65d52f1",
  "utterances": [
    {
      "recordingId": "01905241-7d4a-7c48-9c14-83f4f65d52f1",
      "startSec": 0.8,
      "endSec": 4.2,
      "speaker": 1,
      "text": "Thanks everyone for joining."
    },
    {
      "recordingId": "01905241-7d4a-7c48-9c14-83f4f65d52f1",
      "startSec": 4.5,
      "endSec": 8.1,
      "speaker": 1,
      "text": "I wanted to walk through the customer feedback."
    }
  ]
}
```

### Monologue response

```json theme={null}
{
  "type": "monologue",
  "recordingId": "01905241-7d4a-7c48-9c14-83f4f65d52f1",
  "monologues": [
    {
      "recordingId": "01905241-7d4a-7c48-9c14-83f4f65d52f1",
      "startSec": 0.8,
      "endSec": 8.1,
      "speaker": 1,
      "text": "Thanks everyone for joining. I wanted to walk through the customer feedback."
    }
  ]
}
```

Transcript entries do not include internal database IDs. Use `recordingId`, `startSec`, `endSec`, and `speaker` as the stable public fields for rendering and synchronization.

## Legacy GraphQL transcript migration

Move transcript reads to `GET /recordings/{recordingId}/transcript`. During the transition, existing GraphQL integrations should avoid `interview.monologues` and use sentence-backed relationships on `interview`, such as `sentences` or `transcript_segments`, ordered by `start_sec`.

If you need contiguous same-speaker blocks, call the REST transcript endpoint with `type=monologue`.