Recordings API

The recordings endpoints are the core of most integrations. Poll for completed work, fetch full content, then mark recordings as filed after sending them to an external system.

List recordings

GET /api/v1/recordings

Scope: read:recordings

This is the primary polling endpoint for custom integrations. By default, it returns completed, unsynced recordings.

Query parameters

Parameter	Type	Default	Description
`status`	string	`COMPLETED`	`DRAFT`, `PENDING`, `CLAIMED`, `REVIEW_PENDING`, `COMPLETED`, `ARCHIVED`
`syncState`	string	`unsynced`	`unsynced`, `synced`, or `all`
`updatedSince`	ISO 8601	Not set	Filter by last update time
`cursor`	string	Not set	Pagination cursor from `meta.nextCursor`
`include`	string	Not set	`content` adds derived `contentText`; `contentJson` also adds canonical Tiptap JSON
`limit`	integer	`50`	Minimum `1`, maximum `100`

Default list responses are metadata-first and omit transcript and note or document bodies. Fetch GET /recordings/:id for full content. Use include=content when a list response needs derived plain text, or include=contentJson when it also needs canonical rich-text JSON.

Example request

GET /api/v1/recordings?status=COMPLETED&syncState=unsynced&limit=50
Authorization: Bearer ardela_pk_...

Example response

{
  "data": [{
    "id": "clxxx123",
    "title": "Client Meeting Notes",
    "status": "COMPLETED",
    "priority": "MEDIUM",
    "audioDuration": 180,
    "audioSize": 4521984,
    "notes": [{
      "id": "note_1",
      "templateName": "Meeting Notes",
      "templateId": "tmpl_123",
      "schemaVersion": 2,
      "contentRevision": 1,
      "sortOrder": 1,
      "createdAt": "2025-12-02T10:00:00.000Z"
    }],
    "documents": [{
      "id": "doc_1",
      "templateName": "Letter",
      "templateId": "tmpl_456",
      "schemaVersion": 2,
      "contentRevision": 1,
      "sortOrder": 2,
      "createdAt": "2025-12-02T10:00:00.000Z"
    }],
    "author": {
      "id": "user123",
      "name": "Jane Doe",
      "email": "jane@firm.com"
    },
    "client": {
      "id": "client123",
      "name": "Acme Corp",
      "referenceNumber": "CLI-001"
    },
    "matter": {
      "id": "matter123",
      "name": "Contract Review",
      "referenceNumber": "MAT-2025-001"
    },
    "createdAt": "2025-12-02T10:00:00.000Z",
    "updatedAt": "2025-12-02T10:30:00.000Z",
    "lastSyncedAt": null,
    "syncCount": 0
  }],
  "meta": {
    "count": 1,
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

Pagination

When meta.hasMore is true, pass meta.nextCursor as the cursor query parameter on the next request. Continue until hasMore is false.

Get a recording

GET /api/v1/recordings/:id

Scope: read:recordings

Returns full recording details including transcript, notes, documents, and sync metadata. Derived plain text is included for each note and document. Add ?include=contentJson when you also need the canonical Tiptap JSON.

Response fields

Field	Description
`transcript`	Full transcript text
`notes[]`, `documents[]`	Generated content blocks with template metadata
`contentText`	Derived plain text for a note or document; `null` when unavailable
`contentStatus`	`available` or `unavailable` for the derived content projection
`schemaVersion`	Version of the canonical stored content schema
`contentRevision`	Revision number of the stored content
`contentJson`	Canonical Tiptap JSON, included only with `?include=contentJson` and when content is available
`client`, `matter`	Linked client and matter with reference numbers
`author`	Recording author name and email
`lastSyncedAt`, `syncCount`	Filing history

List and detail responses include at most 50 note/document blocks per recording.

Mark recording filed

POST /api/v1/recordings/:id/filings

Scope: write:recordings

Call after successfully creating a document or note in an external CRM or practice management system. Updates sync metadata so the recording no longer appears in syncState=unsynced polls.

Request body

{
  "provider": "clio",
  "externalId": "doc_123",
  "externalUrl": "https://app.clio.com/documents/doc_123",
  "filedAt": "2026-05-30T12:00:00.000Z",
  "metadata": {
    "matterId": "matter_123",
    "documentType": "note"
  }
}

Field	Required	Description
`provider`	Yes	Your external system identifier, such as `clio` for a custom Clio workflow
`externalId`	Yes	ID of the created record in the external system
`externalUrl`	No	Link back to the external record
`filedAt`	No	ISO 8601 timestamp (defaults to now)
`metadata`	No	Provider-specific references (JSON object)

Rules

Recording must have status: COMPLETED. Filing a draft or in-progress recording returns 409.
Recording must belong to the API key's workspace
Repeating the same provider + externalId is idempotent and does not increment syncCount again

Example response

{
  "data": {
    "id": "clxxx123",
    "lastSyncedAt": "2026-05-30T12:00:00.000Z",
    "syncCount": 1,
    "syncMetadata": {
      "provider": "clio",
      "externalId": "doc_123",
      "externalUrl": "https://app.clio.com/documents/doc_123",
      "filedAt": "2026-05-30T12:00:00.000Z",
      "metadata": { "matterId": "matter_123" }
    }
  },
  "meta": {
    "replayed": false
  }
}

Status values

Status	Description
`DRAFT`	Being edited
`PENDING`	Queued for transcription
`CLAIMED`	Claimed by a transcriber and in progress
`REVIEW_PENDING`	Awaiting review
`COMPLETED`	Ready to sync
`ARCHIVED`	Archived

Priority levels

LOW · MEDIUM · HIGH · URGENT

Integrations: custom automation and CRM filing patterns
Webhooks: notifications for recording.completed
Errors & limits

On this page