Recordings | Caven Docs

All paths are relative to https://developers.caven.io/public/v1.

List recordings

GET /recordings

Scope: recordings:list

Parameter	Description
`limit`, `offset`	Offset pagination. Newest first.
`updatedSince`, `cursor`	Cursor pagination for syncing
`status`	`RECORDED`, `PROCESSING`, `TRANSCRIBED`, `SUMMARIZED` or `FAILED` (case-insensitive)
`uploadOrigin`	`DESKTOP`, `MOBILE`, `WEB` or `CALL`
`from`, `to`	ISO 8601 dates. Filters on when the meeting was recorded.
`search`	Case-insensitive match on the title
`tagId`	Only recordings with this tag
`userId`	Organization keys only: one member's recordings
`onPremDelivery`	`true`: only recordings marked for the on-prem connector (always cursor mode). `false`: only the others. See On-prem connector.

curl "https://developers.caven.io/public/v1/recordings?status=summarized&from=2026-09-01&limit=10" \
  -H "X-API-Key: sk_your_key_here"

Get a recording

GET /recordings/:id

Scope: recordings:get

{
  "data": {
    "id": "cmat10lv8f4yn83oy3iofv0n3",
    "title": "Weekly sync",
    "description": null,
    "duration": "22:45",
    "fileSize": null,
    "recordingType": null,
    "storageMode": "cloud",
    "notesUrl": null,
    "status": "SUMMARIZED",
    "transcriptionStatus": "completed",
    "summaryStatus": "completed",
    "uploadOrigin": "DESKTOP",
    "uploadState": "completed",
    "uploadProgress": 100,
    "isAudioOnly": false,
    "contentHost": "caven",
    "transcriptHost": "caven",
    "summaryHost": "caven",
    "notesHost": "caven",
    "mediaHost": "caven",
    "mediaSource": "r2",
    "onPremSourceManaged": false,
    "organizationId": null,
    "organizationFolderId": null,
    "folderName": null,
    "tags": [{ "id": "cmt...", "name": "Sales", "color": "#3b82f6" }],
    "counts": { "actionItems": 2, "transcripts": 1, "summaries": 1 },
    "recordedAt": "2026-10-05T15:24:30.542Z",
    "uploadedAt": "2026-10-05T15:24:30.542Z",
    "createdAt": "2026-10-05T15:24:30.542Z",
    "updatedAt": "2026-10-05T15:34:58.670Z",
    "userId": "cmjal5xyj0000vaz4po9spv16",
    "ownerName": "Jane Doe"
  }
}

Recording fields

Field	Description
`title`, `description`	As shown in Caven
`duration`	Display string: `mm:ss` or `h:mm:ss`
`status`	Overall processing state: `RECORDED`, `PROCESSING`, `TRANSCRIBED`, `SUMMARIZED`, `FAILED`
`transcriptionStatus`, `summaryStatus`	`idle`, `pending`, `processing`, `completed` or `failed`
`uploadOrigin`	Where the recording came from: `DESKTOP`, `MOBILE`, `WEB`, `CALL`
`uploadState`, `uploadProgress`	Whether the upload has fully arrived. Wait for `completed` / `100` before relying on the media.
`isAudioOnly`	`true` when there is no video
`contentHost`	Where the content lives: `caven`, `sharepoint` or `onprem`
`transcriptHost`, `summaryHost`, `notesHost`, `mediaHost`	The same, per type of content
`mediaSource`	Where the media file can be read from right now: `r2` (Caven storage), `sharepoint`, `onprem`, or `missing` when there is no media file
`onPremSourceManaged`	`true` when the media is managed by your organization's on-prem connector instead of by Caven
`organizationFolderId`, `folderName`	The organization folder, if the recording was filed in one
`tags`	Tags on the recording
`counts`	Number of action items, transcripts and summaries
`recordedAt`	When the meeting took place
`userId`, `ownerName`	Who recorded it

Check transcriptionStatus and summaryStatus before you fetch a transcript or summary. While they are pending or processing, the content endpoints return 404 TRANSCRIPT_NOT_AVAILABLE or 404 SUMMARY_NOT_AVAILABLE.

Transcript

GET /recordings/:id/transcript

Scope: transcripts:list

{
  "data": {
    "id": "cmuv...",
    "recordingId": "cmat10lv8f4yn83oy3iofv0n3",
    "language": "nl",
    "content": "[00:25] Speaker A:\nGood morning, shall we start?\n\n[00:31] Speaker B:\n...",
    "contentHost": "caven",
    "contentSource": "caven"
  }
}

content is plain text. Each turn starts with a [mm:ss] Speaker: line, followed by what was said.

Caven retrieves content stored in SharePoint or on your own server for you, so you always receive readable text. If that source can't be reached right now, you get 503 HOSTED_SOURCE_UNREACHABLE.

Summary

GET /recordings/:id/summary

Scope: summaries:list

{
  "data": {
    "id": "cmuvejep600gjrv92wzifu9ke",
    "recordingId": "cmat10lv8f4yn83oy3iofv0n3",
    "overview": "The team reviewed the Q4 roadmap...",
    "keyPoints": ["Launch moves to November", "..."],
    "actionItems": [{ "task": "Send the revised plan", "owner": "Speaker B", "deadline": null }],
    "decisions": [],
    "sections": [{ "id": "section-1", "title": "Roadmap", "content": "..." }],
    "language": "nl",
    "contentHost": "caven",
    "contentSource": "caven"
  }
}

sections follows the summary template that was used.

Notes

GET /recordings/:id/notes

Scope: transcripts:list

The free-text notes taken during the meeting:

{ "data": { "recordingId": "cmat...", "content": "...", "contentHost": "caven", "contentSource": "caven" } }

Returns 404 NOTES_NOT_AVAILABLE if nobody took notes.

Action items of a recording

GET /recordings/:id/action-items

Scope: action-items:list. Supports limit, offset, status and priority. Returns action item objects.

Speakers of a recording

GET /recordings/:id/speakers

Scope: speakers:list. Returns the speaker profiles recognized in this recording. With an organization key, the list is empty if the organization has turned off the speaker catalog.

Tags of a recording

GET /recordings/:id/tags

Scope: tags:list. Returns tag objects.