Skip to main content
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. 
X-BuildBetter-Api-Key: ORGANIZATION_API_KEY
Base URL: 
https://api.buildbetter.app/v3/rest
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.

​
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

GET /recordings/{recordingId}

Fetch one recording by public UUID.
GET https://api.buildbetter.app/v3/rest/recordings/01905241-7d4a-7c48-9c14-83f4f65d52f1
X-BuildBetter-Api-Key: ORGANIZATION_API_KEY
Response:
{
  "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": []
}
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

GET /recordings/{recordingId}/transcript

Fetch transcript text for one recording. Use the optional type query parameter to choose the transcript shape.
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.

​
Utterance response

{
  "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

{
  "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.