TaadDocs
Help CenterAPIPolicies

Recordings

List recordings

GET
/v1/recordings

The recordings the key reaches, newest recorded first. Only ready ones unless you ask for a status (or any). With updated_after, they come oldest change first instead, so a sync that pages to the end never misses one: keep the last updated_at you saw and pass it next time. Filter by your own client_reference_id or metadata[key]=value; expand[]=notes adds each one's notes.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Query Parameters

limit?integer
Range1 <= value <= 100
Default20
cursor?string
Lengthlength <= 500
status?string
Default"ready"

Value in

  • "recording"
  • "queued"
  • "transcribing"
  • "identifying_speakers"
  • "writing_notes"
  • "ready"
  • "failed"
  • "any"
created_after?string
Match^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2}))?$
created_before?string
Match^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2}))?$
recorded_after?string
Match^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2}))?$
recorded_before?string
Match^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2}))?$
updated_after?string
Match^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2}))?$
source?string

Value in

  • "app"
  • "import"
  • "api"
client_reference_id?string
Length1 <= length <= 200
metadata?
expand?|array<>

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/recordings"
{  "object": "list",  "data": [    {      "id": "string",      "object": "recording",      "livemode": true,      "status": "recording",      "failure": {        "code": "string",        "message": "string"      },      "title": "string",      "workspace": {        "id": "string",        "object": "workspace",        "name": "string",        "kind": "personal"      },      "source": "app",      "language": "string",      "recorded_at": "string",      "duration_ms": -9007199254740991,      "speakers": [        {          "id": "string",          "name": "string",          "is_you": true        }      ],      "calendar_event_id": "string",      "place": {        "name": "string",        "color": "string"      },      "client_reference_id": "string",      "metadata": {        "property1": "string",        "property2": "string"      },      "cost": {        "held_usd": 0,        "charged_usd": 0,        "plan_ms": -9007199254740991      },      "app_url": "string",      "created_at": "string",      "updated_at": "string",      "notes": {        "object": "notes",        "recording_id": "string",        "summary_markdown": "string",        "taad_notes_markdown": "string",        "your_notes_markdown": "string",        "action_items": [          {            "text": "string",            "who": "string",            "todo_id": "string"          }        ],        "shape": "string",        "focus": "string",        "version": "string",        "updated_at": "string"      },      "todos": [        {          "id": "string",          "object": "todo",          "workspace_id": "string",          "title": "string",          "description": "string",          "due": "string",          "priority": "low",          "done": true,          "completed_at": "string",          "subtasks": [            {              "title": "string",              "done": true            }          ],          "who": "string",          "recording_id": "string",          "created_at": "string",          "updated_at": "string"        }      ],      "calendar_event": {        "id": "string",        "object": "calendar_event",        "workspace_id": "string",        "title": "string",        "day": "string",        "start": "string",        "end": "string",        "category": "meeting",        "notes": "string",        "recurrence": {          "freq": "daily",          "interval": 1,          "until": null,          "days": [            0          ]        },        "series_id": "string",        "alerts": [          -9007199254740991        ],        "recording_id": "string",        "said_at_ms": -9007199254740991,        "source": "user",        "suggested": true,        "read_only": true,        "created_at": "string",        "updated_at": "string"      },      "transcript": [        {          "speaker": {            "id": "string",            "name": "string",            "is_you": true          },          "start_ms": -9007199254740991,          "end_ms": -9007199254740991,          "text": "string"        }      ]    }  ],  "has_more": true,  "next_cursor": "string"}
POST
/v1/recordings

Makes a recording from a file (multipart, up to 90 MB), an audio_url Taad fetches (up to 200 MB), or a transcript. It answers 202 at once with the recording, status: "queued"; it is then transcribed, its speakers told apart, and its notes, summary, to-dos and dates written, and recording.ready is sent (or recording.failed).

Price: audio $0.90 an hour, by the second; a transcript $0.05 per started hour of talk. The length is read from the file's own header and held before anything starts (Taad-Held-Usd, cost.held_usd); a file whose length can't be read holds 4 hours, the longest allowed. Once it is done you are charged for its real length, plus anything it cost us over a normal recording of that length, at our cost. A recording that fails on our side, or in which nothing was heard, is not charged.

A personal key may pay with your plan's weekly minutes first (Settings → Developers); an organization's key always pays from the organization's API wallet.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/recordings" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "object": "recording",  "livemode": true,  "status": "recording",  "failure": {    "code": "string",    "message": "string"  },  "title": "string",  "workspace": {    "id": "string",    "object": "workspace",    "name": "string",    "kind": "personal"  },  "source": "app",  "language": "string",  "recorded_at": "string",  "duration_ms": -9007199254740991,  "speakers": [    {      "id": "string",      "name": "string",      "is_you": true    }  ],  "calendar_event_id": "string",  "place": {    "name": "string",    "color": "string"  },  "client_reference_id": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "cost": {    "held_usd": 0,    "charged_usd": 0,    "plan_ms": -9007199254740991  },  "app_url": "string",  "created_at": "string",  "updated_at": "string",  "notes": {    "object": "notes",    "recording_id": "string",    "summary_markdown": "string",    "taad_notes_markdown": "string",    "your_notes_markdown": "string",    "action_items": [      {        "text": "string",        "who": "string",        "todo_id": "string"      }    ],    "shape": "string",    "focus": "string",    "version": "string",    "updated_at": "string"  },  "todos": [    {      "id": "string",      "object": "todo",      "workspace_id": "string",      "title": "string",      "description": "string",      "due": "string",      "priority": "low",      "done": true,      "completed_at": "string",      "subtasks": [        {          "title": "string",          "done": true        }      ],      "who": "string",      "recording_id": "string",      "created_at": "string",      "updated_at": "string"    }  ],  "calendar_event": {    "id": "string",    "object": "calendar_event",    "workspace_id": "string",    "title": "string",    "day": "string",    "start": "string",    "end": "string",    "category": "meeting",    "notes": "string",    "recurrence": {      "freq": "daily",      "interval": 1,      "until": null,      "days": [        0      ]    },    "series_id": "string",    "alerts": [      -9007199254740991    ],    "recording_id": "string",    "said_at_ms": -9007199254740991,    "source": "user",    "suggested": true,    "read_only": true,    "created_at": "string",    "updated_at": "string"  },  "transcript": [    {      "speaker": {        "id": "string",        "name": "string",        "is_you": true      },      "start_ms": -9007199254740991,      "end_ms": -9007199254740991,      "text": "string"    }  ]}

Get a recording

GET
/v1/recordings/{id}

One recording. expand[] adds its notes, todos, calendar_event or whole transcript (the transcript only when asked: it can be long).

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 64

Query Parameters

expand?|array<>

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/recordings/string"
{  "id": "string",  "object": "recording",  "livemode": true,  "status": "recording",  "failure": {    "code": "string",    "message": "string"  },  "title": "string",  "workspace": {    "id": "string",    "object": "workspace",    "name": "string",    "kind": "personal"  },  "source": "app",  "language": "string",  "recorded_at": "string",  "duration_ms": -9007199254740991,  "speakers": [    {      "id": "string",      "name": "string",      "is_you": true    }  ],  "calendar_event_id": "string",  "place": {    "name": "string",    "color": "string"  },  "client_reference_id": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "cost": {    "held_usd": 0,    "charged_usd": 0,    "plan_ms": -9007199254740991  },  "app_url": "string",  "created_at": "string",  "updated_at": "string",  "notes": {    "object": "notes",    "recording_id": "string",    "summary_markdown": "string",    "taad_notes_markdown": "string",    "your_notes_markdown": "string",    "action_items": [      {        "text": "string",        "who": "string",        "todo_id": "string"      }    ],    "shape": "string",    "focus": "string",    "version": "string",    "updated_at": "string"  },  "todos": [    {      "id": "string",      "object": "todo",      "workspace_id": "string",      "title": "string",      "description": "string",      "due": "string",      "priority": "low",      "done": true,      "completed_at": "string",      "subtasks": [        {          "title": "string",          "done": true        }      ],      "who": "string",      "recording_id": "string",      "created_at": "string",      "updated_at": "string"    }  ],  "calendar_event": {    "id": "string",    "object": "calendar_event",    "workspace_id": "string",    "title": "string",    "day": "string",    "start": "string",    "end": "string",    "category": "meeting",    "notes": "string",    "recurrence": {      "freq": "daily",      "interval": 1,      "until": null,      "days": [        0      ]    },    "series_id": "string",    "alerts": [      -9007199254740991    ],    "recording_id": "string",    "said_at_ms": -9007199254740991,    "source": "user",    "suggested": true,    "read_only": true,    "created_at": "string",    "updated_at": "string"  },  "transcript": [    {      "speaker": {        "id": "string",        "name": "string",        "is_you": true      },      "start_ms": -9007199254740991,      "end_ms": -9007199254740991,      "text": "string"    }  ]}

Update a recording

PATCH
/v1/recordings/{id}

Change the title, your client_reference_id (one per workspace), your metadata (merged: a key set to null is removed; at most 20 keys), or the speakers' names. A name given to a voice goes into its written notes too, as in the app. Send If-Match with the updated_at you read to change it only if no one else did meanwhile (412 version_conflict otherwise).

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 64

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/recordings/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "object": "recording",  "livemode": true,  "status": "recording",  "failure": {    "code": "string",    "message": "string"  },  "title": "string",  "workspace": {    "id": "string",    "object": "workspace",    "name": "string",    "kind": "personal"  },  "source": "app",  "language": "string",  "recorded_at": "string",  "duration_ms": -9007199254740991,  "speakers": [    {      "id": "string",      "name": "string",      "is_you": true    }  ],  "calendar_event_id": "string",  "place": {    "name": "string",    "color": "string"  },  "client_reference_id": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "cost": {    "held_usd": 0,    "charged_usd": 0,    "plan_ms": -9007199254740991  },  "app_url": "string",  "created_at": "string",  "updated_at": "string",  "notes": {    "object": "notes",    "recording_id": "string",    "summary_markdown": "string",    "taad_notes_markdown": "string",    "your_notes_markdown": "string",    "action_items": [      {        "text": "string",        "who": "string",        "todo_id": "string"      }    ],    "shape": "string",    "focus": "string",    "version": "string",    "updated_at": "string"  },  "todos": [    {      "id": "string",      "object": "todo",      "workspace_id": "string",      "title": "string",      "description": "string",      "due": "string",      "priority": "low",      "done": true,      "completed_at": "string",      "subtasks": [        {          "title": "string",          "done": true        }      ],      "who": "string",      "recording_id": "string",      "created_at": "string",      "updated_at": "string"    }  ],  "calendar_event": {    "id": "string",    "object": "calendar_event",    "workspace_id": "string",    "title": "string",    "day": "string",    "start": "string",    "end": "string",    "category": "meeting",    "notes": "string",    "recurrence": {      "freq": "daily",      "interval": 1,      "until": null,      "days": [        0      ]    },    "series_id": "string",    "alerts": [      -9007199254740991    ],    "recording_id": "string",    "said_at_ms": -9007199254740991,    "source": "user",    "suggested": true,    "read_only": true,    "created_at": "string",    "updated_at": "string"  },  "transcript": [    {      "speaker": {        "id": "string",        "name": "string",        "is_you": true      },      "start_ms": -9007199254740991,      "end_ms": -9007199254740991,      "text": "string"    }  ]}

Get a transcript

GET
/v1/recordings/{id}/transcript

The transcript as pages of segments (who spoke, when, what they said), up to 500 a page. Or the whole of it as a file with format=txt, md, srt or vtt (subtitles), answered as text. While a recording is still being transcribed and has no words yet, the answer is 409 not_ready with retry_after in seconds.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 64

Query Parameters

format?string
Default"json"

Value in

  • "json"
  • "txt"
  • "md"
  • "srt"
  • "vtt"
limit?integer
Range1 <= value <= 500
Default100
cursor?string
Lengthlength <= 500

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/recordings/string/transcript"
{  "object": "list",  "data": [    {      "speaker": {        "id": "string",        "name": "string",        "is_you": true      },      "start_ms": -9007199254740991,      "end_ms": -9007199254740991,      "text": "string"    }  ],  "has_more": true,  "next_cursor": "string"}

Get a recording's notes

GET
/v1/recordings/{id}/notes

The summary, Taad's notes and the person's own notes as Markdown, the action items (with the to-do each became), and a version that changes whenever they do.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 64

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/recordings/string/notes"
{  "object": "notes",  "recording_id": "string",  "summary_markdown": "string",  "taad_notes_markdown": "string",  "your_notes_markdown": "string",  "action_items": [    {      "text": "string",      "who": "string",      "todo_id": "string"    }  ],  "shape": "string",  "focus": "string",  "version": "string",  "updated_at": "string"}
GET
/v1/recordings/{id}/speakers

The voices in the transcript, sp_1, sp_2… in the order they first speak, with the names given to them. Name them with PATCH /v1/recordings/{id}.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string
Lengthlength <= 64

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/recordings/string/speakers"
{  "object": "list",  "data": [    {      "id": "string",      "name": "string",      "is_you": true    }  ],  "has_more": false,  "next_cursor": null}
POST
/v1/recordings/{id}/transcribe_again

Hears the whole recording again from its audio, as Transcribe Again in the apps, then writes its notes again. The notes it had are kept as a version, so Undo in the apps brings them back. Priced as sending its audio: its length, held now and charged when it is done. Answers 202 with the recording.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/recordings/string/transcribe_again"
{  "id": "string",  "object": "recording",  "livemode": true,  "status": "recording",  "failure": {    "code": "string",    "message": "string"  },  "title": "string",  "workspace": {    "id": "string",    "object": "workspace",    "name": "string",    "kind": "personal"  },  "source": "app",  "language": "string",  "recorded_at": "string",  "duration_ms": -9007199254740991,  "speakers": [    {      "id": "string",      "name": "string",      "is_you": true    }  ],  "calendar_event_id": "string",  "place": {    "name": "string",    "color": "string"  },  "client_reference_id": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "cost": {    "held_usd": 0,    "charged_usd": 0,    "plan_ms": -9007199254740991  },  "app_url": "string",  "created_at": "string",  "updated_at": "string",  "notes": {    "object": "notes",    "recording_id": "string",    "summary_markdown": "string",    "taad_notes_markdown": "string",    "your_notes_markdown": "string",    "action_items": [      {        "text": "string",        "who": "string",        "todo_id": "string"      }    ],    "shape": "string",    "focus": "string",    "version": "string",    "updated_at": "string"  },  "todos": [    {      "id": "string",      "object": "todo",      "workspace_id": "string",      "title": "string",      "description": "string",      "due": "string",      "priority": "low",      "done": true,      "completed_at": "string",      "subtasks": [        {          "title": "string",          "done": true        }      ],      "who": "string",      "recording_id": "string",      "created_at": "string",      "updated_at": "string"    }  ],  "calendar_event": {    "id": "string",    "object": "calendar_event",    "workspace_id": "string",    "title": "string",    "day": "string",    "start": "string",    "end": "string",    "category": "meeting",    "notes": "string",    "recurrence": {      "freq": "daily",      "interval": 1,      "until": null,      "days": [        0      ]    },    "series_id": "string",    "alerts": [      -9007199254740991    ],    "recording_id": "string",    "said_at_ms": -9007199254740991,    "source": "user",    "suggested": true,    "read_only": true,    "created_at": "string",    "updated_at": "string"  },  "transcript": [    {      "speaker": {        "id": "string",        "name": "string",        "is_you": true      },      "start_ms": -9007199254740991,      "end_ms": -9007199254740991,      "text": "string"    }  ]}
POST
/v1/recordings/{id}/rewrite

Writes the summary again, about what focus names, in a shape, or with one of your note templates, and answers the notes once it is written (usually within a minute). The summary it had is kept as a version, so Undo in the apps brings it back. $0.05, charged only when it is written.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer taad_… (or taadtest_… for the sandbox). Never in a URL, never in a web page.

In: header

Path Parameters

id*string

Header Parameters

Idempotency-Key?string

Any unique string (a UUID). Sending the same request again with the same key answers the first answer, and a paid call is never charged twice. Kept 24 hours.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/recordings/string/rewrite" \  -H "Content-Type: application/json" \  -d '{}'
{  "object": "notes",  "recording_id": "string",  "summary_markdown": "string",  "taad_notes_markdown": "string",  "your_notes_markdown": "string",  "action_items": [    {      "text": "string",      "who": "string",      "todo_id": "string"    }  ],  "shape": "string",  "focus": "string",  "version": "string",  "updated_at": "string",  "cost_usd": 0}