/transcriptions

Create transcription

post

Creates a new transcription for the specified recording.

Path parameters

recordingIdstringRequired

Recording ID.

Example: a56f6ad7-37fe-4a37-9319-3174630ba57a

Body

application/json

recordingIdstringRequired

The recording ID for which the transcription should be created.

Example: a56f6ad7-37fe-4a37-9319-3174630ba57a

Responses

201

The transcription job was scheduled successfully.

application/json

401

Access token is missing or invalid

404

The requested resource doesn't exist

429

You are rate limited

application/json

post

/transcriptions

HTTPcURLJavaScriptPython

POST /v1/transcriptions HTTP/1.1
Host: api.whereby.dev
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "recordingId": "a56f6ad7-37fe-4a37-9319-3174630ba57a"
}

No content

Get transcriptions

get

Returns a list of transcriptions

Query parameters

roomNamestringOptional

The name of the room

cursorstringOptional

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request.

Example: 8f4031bfc7640c5f267b11b6fe0c2507

limitinteger · min: 1 · max: 100Optional

The limit for the pagination - the maximum number of results that will be returned within a single API response.

Default: 50

sortByanyOptional

Sort results by a field. Accepted fields are: roomName, startDate and durationInSeconds. Accepted sort values are 'asc' and 'desc'.

Example: roomName:asc

Responses

200

A JSON array representing the transcriptions.

application/json

401

Access token is missing or invalid

429

You are rate limited

application/json

get

/transcriptions

HTTPcURLJavaScriptPython

GET /v1/transcriptions HTTP/1.1
Host: api.whereby.dev
Accept: */*

{
  "results": [
    {
      "transcriptionId": "b438fda0-83e2-4835-92f9-c845ee3d5ea7",
      "roomSessionId": "e2f29530-46ec-4cee-8b27-e565cb5bb2e9",
      "roomName": "/room-prefix-793e9ec1-c686-423d-9043-9b7a10c553fd",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-01-01T00:01:00.000Z",
      "state": "ready",
      "durationInSeconds": 60,
      "type": "LIVE_TRANSCRIPTION",
      "filename": "room-prefix-793e9ec1-c686-423d-9043-9b7a10c553fd-2025-01-01T00:00:00.000Z.md",
      "storageType": "WHEREBY_HOSTED"
    }
  ]
}

Get transcription

get

Returns the specified transcription metadata.

Path parameters

transcriptionIdstringRequired

Transcription ID.

Example: b438fda0-83e2-4835-92f9-c845ee3d5ea7

Responses

200

A JSON object representing the transcription.

application/json

transcriptionIdstringRequired

The ID of the transcription.

roomSessionIdstringRequired

The ID of the room session.

filenamestringOptional

The filename of the transcription that was written to either Whereby or self hosted storage buckets (see: storageType).

roomNamestringRequired

The name of the room.

startDatestring · date-timeRequired

When the transcription starts. Always in UTC, regardless of the input timezone.

endDatestring · date-timeRequired

When the transcription ends. Always in UTC, regardless of the input timezone.

statestring · enumRequired

The state of the transcription

• ready - The transcription is ready to be downloaded
• failed - The transcription failed to be generated
• in_progress - The transcription is still being generated

Possible values:

createdAtstring · date-timeRequired

When the transcription was created. Always in UTC, regardless of the input timezone.

durationInSecondsnumberOptional

The total billable time in seconds for this transcription.

Example: 42

typestring · enumRequired

The type of the transcription

• LIVE_TRANSCRIPTION - Session Transcription
• RECORDING_TRANSCRIPTION - generated based on a recording

Possible values:

storageTypestring · enumOptional

The storage type of the transcription

• WHEREBY_HOSTED - files kept with Whereby
• SELF_HOSTED - files stored in external location

Possible values:

401

Access token is missing or invalid

404

The requested resource doesn't exist

429

You are rate limited

application/json

get

/transcriptions/{transcriptionId}

HTTPcURLJavaScriptPython

GET /v1/transcriptions/{transcriptionId} HTTP/1.1
Host: api.whereby.dev
Accept: */*

{
  "transcriptionId": "b438fda0-83e2-4835-92f9-c845ee3d5ea7",
  "roomSessionId": "e2f29530-46ec-4cee-8b27-e565cb5bb2e9",
  "roomName": "/room-prefix-793e9ec1-c686-423d-9043-9b7a10c553fd",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2025-01-01T00:01:00.000Z",
  "state": "ready",
  "durationInSeconds": 60,
  "type": "LIVE_TRANSCRIPTION",
  "filename": "room-prefix-793e9ec1-c686-423d-9043-9b7a10c553fd-2025-01-01T00:00:00.000Z.md",
  "storageType": "WHEREBY_HOSTED"
}

Get transcription access link

get

Returns a URL that can be used to download the specified transcription. Available for Whereby-hosted transcriptions only.

Path parameters

transcriptionIdstringRequired

Transcription ID.

Example: b438fda0-83e2-4835-92f9-c845ee3d5ea7

Query parameters

validForSecondsinteger · min: 1 · max: 43200Optional

The number of seconds the access link is valid for.

Default: 3600

Responses

200

A JSON object representing the access link.

application/json

accessLinkstringRequired

The access link.

Example: https://s3.eu-central-1.amazonaws.com/recordings/1.mp4?AWSAccessKeyId=AKIAJ...

expiresintegerRequired

The timestamp when the access link expires.

Example: 1740819600000

401

Access token is missing or invalid

403

Not allowed to perform action

404

The requested resource doesn't exist

429

You are rate limited

application/json

get

/transcriptions/{transcriptionId}/access-link

HTTPcURLJavaScriptPython

GET /v1/transcriptions/{transcriptionId}/access-link HTTP/1.1
Host: api.whereby.dev
Accept: */*

{
  "accessLink": "https://s3.eu-central-1.amazonaws.com/recordings/1.mp4?AWSAccessKeyId=AKIAJ...",
  "expires": 1740819600000
}

Bulk delete transcriptions

post

Deletes multiple transcriptions at once. This is an asynchronous operation. The endpoint returns immediately, and schedules a background job to delete the transcriptions. The endpoint is idempotent, meaning it will return the same response even if the transcriptions have already been deleted, or the transcriptions doesn't exist.

Body

application/json

transcriptionIdsstring[]Required

The transcription ID to delete.

Example: b438fda0-83e2-4835-92f9-c845ee3d5ea7

Responses

204

The resources are scheduled for deletion.

401

Access token is missing or invalid

429

You are rate limited

application/json

post

/transcriptions/bulk-delete

HTTPcURLJavaScriptPython

POST /v1/transcriptions/bulk-delete HTTP/1.1
Host: api.whereby.dev
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "transcriptionIds": [
    "b438fda0-83e2-4835-92f9-c845ee3d5ea7"
  ]
}

No content

Delete transcription

delete

Deletes the specified transcription. The endpoint is idempotent, meaning it will return the same response even if the transcription has already been deleted.

Path parameters

transcriptionIdstringRequired

Transcription ID.

Example: b438fda0-83e2-4835-92f9-c845ee3d5ea7

Responses

204

The resource was deleted successfully.

401

Access token is missing or invalid

429

You are rate limited

application/json

delete

/transcriptions/{transcriptionId}

HTTPcURLJavaScriptPython

DELETE /v1/transcriptions/{transcriptionId} HTTP/1.1
Host: api.whereby.dev
Accept: */*

No content