Chats API reference

Chats in the Taad API: list chats, start a chat, get a chat, delete a chat, ask in a chat, confirm a proposed change, undo an action.

List chats

The chats started over the API with this account's keys, the latest first. The apps' own chats aren't listed.

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

`application/json`

curl -X GET "https://example.com/v1/chats"

{  "object": "list",  "data": [    {      "id": "string",      "object": "chat",      "livemode": true,      "title": "string",      "recording_id": "string",      "answering": true,      "messages": [        {          "id": "string",          "object": "chat_message",          "chat_id": "string",          "role": "user",          "text_markdown": "string",          "citations": [            {              "recording_id": "string",              "start_ms": -9007199254740991,              "end_ms": -9007199254740991,              "quote": "string"            }          ],          "recording_ids": [            "string"          ],          "actions": [            {              "id": "string",              "object": "chat_action",              "chat_id": "string",              "label": "string",              "tool": "string",              "kind": "create",              "status": "proposed"            }          ],          "status": "answering",          "error": {            "code": "string",            "message": "string"          },          "cost_usd": 0,          "created_at": "string"        }      ],      "created_at": "string",      "updated_at": "string"    }  ],  "has_more": true,  "next_cursor": "string"}

Starts a chat with its first question and answers it from the recordings the key reaches, with citations, as the apps' Chats do; it may add things (a to-do, an event: done at once, undo them) or propose changes (confirm them). Answers the chat with both messages once the answer is written (up to 3 minutes). A personal key's chat shows in its maker's Chats in the apps; an organization key's stays here.

Price: what answering it really cost us, plus a markup (50% unless your account says otherwise), from the API wallet; it holds up to $1.00 while it answers and is never charged more, and an answer that fails on our side is not charged. The apps' daily AI allowance is never used.

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

application/json

TypeScript Definitions

Use the request body type in TypeScript.

message*string

Length1 <= length <= 8000

recording_id?string

Start it about this recording: its questions read it first.

Match^rec_[0-9A-HJKMNP-TV-Z]{26}$

Response Body

`application/json`

curl -X POST "https://example.com/v1/chats" \  -H "Content-Type: application/json" \  -d '{    "message": "string"  }'

{  "id": "string",  "object": "chat",  "livemode": true,  "title": "string",  "recording_id": "string",  "answering": true,  "messages": [    {      "id": "string",      "object": "chat_message",      "chat_id": "string",      "role": "user",      "text_markdown": "string",      "citations": [        {          "recording_id": "string",          "start_ms": -9007199254740991,          "end_ms": -9007199254740991,          "quote": "string"        }      ],      "recording_ids": [        "string"      ],      "actions": [        {          "id": "string",          "object": "chat_action",          "chat_id": "string",          "label": "string",          "tool": "string",          "kind": "create",          "status": "proposed"        }      ],      "status": "answering",      "error": {        "code": "string",        "message": "string"      },      "cost_usd": 0,      "created_at": "string"    }  ],  "created_at": "string",  "updated_at": "string"}

Get a chat

A chat with its messages, oldest first, each answer's actions as they are now.

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`

curl -X GET "https://example.com/v1/chats/string"

{  "id": "string",  "object": "chat",  "livemode": true,  "title": "string",  "recording_id": "string",  "answering": true,  "messages": [    {      "id": "string",      "object": "chat_message",      "chat_id": "string",      "role": "user",      "text_markdown": "string",      "citations": [        {          "recording_id": "string",          "start_ms": -9007199254740991,          "end_ms": -9007199254740991,          "quote": "string"        }      ],      "recording_ids": [        "string"      ],      "actions": [        {          "id": "string",          "object": "chat_action",          "chat_id": "string",          "label": "string",          "tool": "string",          "kind": "create",          "status": "proposed"        }      ],      "status": "answering",      "error": {        "code": "string",        "message": "string"      },      "cost_usd": 0,      "created_at": "string"    }  ],  "created_at": "string",  "updated_at": "string"}

Delete a chat

Deletes the chat and its messages (from the apps too, for a personal key's). An answer still arriving stops.

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

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/chats/string"

{  "id": "string",  "object": "chat",  "deleted": true}

Ask in a chat

Asks the next question in a chat: the answer reads what was asked and answered before in it. Answers the answer once it is written (up to 3 minutes). An answer still arriving in the chat: 409 not_ready.

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.

message*string

Length1 <= length <= 8000

recording_id?string

A recording this question is about: always readable in the answer, whatever else it reads.

Match^rec_[0-9A-HJKMNP-TV-Z]{26}$

Response Body

`application/json`

curl -X POST "https://example.com/v1/chats/string/messages" \  -H "Content-Type: application/json" \  -d '{    "message": "string"  }'

{  "id": "string",  "object": "chat_message",  "chat_id": "string",  "role": "user",  "text_markdown": "string",  "citations": [    {      "recording_id": "string",      "start_ms": -9007199254740991,      "end_ms": -9007199254740991,      "quote": "string"    }  ],  "recording_ids": [    "string"  ],  "actions": [    {      "id": "string",      "object": "chat_action",      "chat_id": "string",      "label": "string",      "tool": "string",      "kind": "create",      "status": "proposed"    }  ],  "status": "answering",  "error": {    "code": "string",    "message": "string"  },  "cost_usd": 0,  "created_at": "string"}

Confirm a proposed change

Makes a change an answer proposed (mark a to-do done, move an event, rewrite a summary…), once, as Confirm in the apps; confirming twice is once. It needs the key's scope for what it changes (todos:write, calendar:write, recordings:write). Too old, or no longer possible: 409 with why.

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

action_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

Response Body

`application/json`

curl -X POST "https://example.com/v1/chats/string/actions/string/confirm"

{  "id": "string",  "object": "chat_action",  "chat_id": "string",  "label": "string",  "tool": "string",  "kind": "create",  "status": "proposed"}

Undo an action

Takes back what an answer added or a confirmed change, as Undo in the apps; twice is once.

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

action_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

Response Body

`application/json`

curl -X POST "https://example.com/v1/chats/string/actions/string/undo"

{  "id": "string",  "object": "chat_action",  "chat_id": "string",  "label": "string",  "tool": "string",  "kind": "create",  "status": "proposed"}

Chats

List chatsCopy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

429application/json

Start a chatCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

429application/json

Get a chatCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

429application/json

Delete a chatCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

429application/json

Ask in a chatCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

429application/json

Confirm a proposed changeCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

429application/json

Undo an actionCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

List chats

Authorization

Query Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Start a chat

Authorization

Header Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Get a chat

Authorization

Path Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Delete a chat

Authorization

Path Parameters

Header Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Ask in a chat

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Confirm a proposed change

Authorization

Path Parameters

Header Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Undo an action

Authorization

Path Parameters

Header Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`