{ "openapi": "3.1.0", "info": { "title": "Taad API", "version": "1", "description": "Your recordings, transcripts, notes, to-dos and calendar, from your own code. Send audio to be transcribed and written up, ask questions across recordings, and hear about changes by webhook. Keys are made in Taad: Settings → Developers." }, "servers": [ { "url": "https://api.taad.app" } ], "tags": [ { "name": "Account" }, { "name": "Recordings" }, { "name": "To-dos" }, { "name": "Calendar" }, { "name": "Search" }, { "name": "Exports" }, { "name": "Wallet" }, { "name": "Ask" }, { "name": "Webhooks" } ], "paths": { "/v1/me": { "get": { "operationId": "me.get", "tags": [ "Account" ], "summary": "The key you're calling with", "description": "What the key is, where it reaches and what it may do. Handy as a first call, and in a test that checks it holds the key it thinks it holds.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "key" }, "id": { "type": "string", "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string" }, "livemode": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "workspace" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] } }, "required": [ "id", "object", "name", "kind" ], "additionalProperties": false }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "recordings:read", "recordings:write", "audio:read", "todos:read", "todos:write", "calendar:read", "calendar:write", "ask", "webhooks" ] } }, "read_only": { "type": "boolean" }, "spend_from": { "type": "string", "enum": [ "plan_then_wallet", "wallet_only" ] }, "weekly_cap_usd": { "anyOf": [ { "type": "number", "description": "US dollars" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "owner": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ], "additionalProperties": false } }, "required": [ "object", "id", "name", "livemode", "kind", "workspace", "scopes", "read_only", "spend_from", "weekly_cap_usd", "expires_at", "created_at", "owner" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/workspaces": { "get": { "operationId": "workspaces.list", "tags": [ "Account" ], "summary": "The workspace the key reaches", "description": "A personal key reaches its maker's Personal workspace; an organization's key reaches that organization. One item either way.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "workspace" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] } }, "required": [ "id", "object", "name", "kind" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "const": false }, "next_cursor": { "type": "null" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/recordings": { "get": { "operationId": "recordings.list", "tags": [ "Recordings" ], "summary": "List recordings", "description": "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.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "status", "in": "query", "required": false, "schema": { "default": "ready", "type": "string", "enum": [ "recording", "queued", "transcribing", "identifying_speakers", "writing_notes", "ready", "failed", "any" ] } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } }, { "name": "recorded_after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } }, { "name": "recorded_before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "app", "import", "api" ] } }, { "name": "client_reference_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "metadata", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, { "name": "expand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "notes" ] }, { "maxItems": 1, "type": "array", "items": { "type": "string", "enum": [ "notes" ] } } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "recording" }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "recording", "queued", "transcribing", "identifying_speakers", "writing_notes", "ready", "failed" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "title": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "workspace" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] } }, "required": [ "id", "object", "name", "kind" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "app", "import", "api" ] }, "language": { "type": "string" }, "recorded_at": { "type": "string", "description": "ISO 8601 in UTC" }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false } }, "calendar_event_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "place": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name", "color" ], "additionalProperties": false }, { "type": "null" } ] }, "client_reference_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cost": { "anyOf": [ { "type": "object", "properties": { "held_usd": { "type": "number", "description": "US dollars" }, "charged_usd": { "type": "number", "description": "US dollars" }, "plan_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "held_usd", "charged_usd", "plan_ms" ], "additionalProperties": false }, { "type": "null" } ] }, "app_url": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "notes": { "type": "object", "properties": { "object": { "type": "string", "const": "notes" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "summary_markdown": { "type": [ "string", "null" ] }, "taad_notes_markdown": { "type": [ "string", "null" ] }, "your_notes_markdown": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "who": { "type": [ "string", "null" ] }, "todo_id": { "anyOf": [ { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "text", "who", "todo_id" ], "additionalProperties": false } }, "shape": { "type": "string" }, "focus": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "object", "recording_id", "summary_markdown", "taad_notes_markdown", "your_notes_markdown", "action_items", "shape", "focus", "version", "updated_at" ], "additionalProperties": false }, "todos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } }, "calendar_event": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "null" } ] }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "speaker", "start_ms", "end_ms", "text" ], "additionalProperties": false } } }, "required": [ "id", "object", "livemode", "status", "failure", "title", "workspace", "source", "language", "recorded_at", "duration_ms", "speakers", "calendar_event_id", "place", "client_reference_id", "metadata", "cost", "app_url", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read" }, "post": { "operationId": "recordings.create", "tags": [ "Recordings" ], "summary": "Send audio or a transcript", "description": "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`).\n\n**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.\n\nA 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.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "recording" }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "recording", "queued", "transcribing", "identifying_speakers", "writing_notes", "ready", "failed" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "title": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "workspace" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] } }, "required": [ "id", "object", "name", "kind" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "app", "import", "api" ] }, "language": { "type": "string" }, "recorded_at": { "type": "string", "description": "ISO 8601 in UTC" }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false } }, "calendar_event_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "place": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name", "color" ], "additionalProperties": false }, { "type": "null" } ] }, "client_reference_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cost": { "anyOf": [ { "type": "object", "properties": { "held_usd": { "type": "number", "description": "US dollars" }, "charged_usd": { "type": "number", "description": "US dollars" }, "plan_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "held_usd", "charged_usd", "plan_ms" ], "additionalProperties": false }, { "type": "null" } ] }, "app_url": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "notes": { "type": "object", "properties": { "object": { "type": "string", "const": "notes" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "summary_markdown": { "type": [ "string", "null" ] }, "taad_notes_markdown": { "type": [ "string", "null" ] }, "your_notes_markdown": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "who": { "type": [ "string", "null" ] }, "todo_id": { "anyOf": [ { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "text", "who", "todo_id" ], "additionalProperties": false } }, "shape": { "type": "string" }, "focus": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "object", "recording_id", "summary_markdown", "taad_notes_markdown", "your_notes_markdown", "action_items", "shape", "focus", "version", "updated_at" ], "additionalProperties": false }, "todos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } }, "calendar_event": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "null" } ] }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "speaker", "start_ms", "end_ms", "text" ], "additionalProperties": false } } }, "required": [ "id", "object", "livemode", "status", "failure", "title", "workspace", "source", "language", "recorded_at", "duration_ms", "speakers", "calendar_event_id", "place", "client_reference_id", "metadata", "cost", "app_url", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:write", "x-taad-paid": true, "x-taad-errors": [ "insufficient_balance", "key_cap_reached", "duplicate_reference", "file_too_large", "too_long", "unsupported_media_type", "unreadable_audio", "unsafe_url", "queue_full" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "audio_url": { "description": "An https link Taad fetches the audio from (up to 200 MB). It must answer within 10 minutes and redirect at most 3 times. With a test key, `sample:no-speech`, `sample:unreadable`, `sample:too-long`, `sample:slow` and `sample:insufficient-credits` misbehave on purpose.", "type": "string", "maxLength": 2048 }, "transcript": { "description": "A transcript instead of audio: SubRip (.srt) or WebVTT text, plain text (\"Name: words\" lines), or segments. Taad writes the notes from it.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 5000000 }, { "minItems": 1, "maxItems": 50000, "type": "array", "items": { "type": "object", "properties": { "speaker": { "description": "Who said it, as you call them (\"Sara\"). Lines with the same name are one voice.", "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "start_ms", "end_ms", "text" ] } } ] }, "title": { "description": "Left out, Taad writes one from what was said.", "type": "string", "maxLength": 200 }, "language": { "description": "What was spoken, as a language code. Left out, Taad hears it.", "type": "string", "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$" }, "recorded_at": { "description": "When it was recorded (ISO 8601); now when left out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "client_reference_id": { "description": "Your own id for it, one per workspace: sending the same one again answers 409 `duplicate_reference` with the recording that has it.", "type": "string", "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Your own labels: up to 20 keys of 40 characters, values of 500" }, "speaker_names": { "description": "The people in it, in the order they first speak: the voices are named so once it is transcribed.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "summary_shape": { "description": "How the summary is laid out; your default when left out.", "type": "string", "enum": [ "auto", "meeting", "one_to_one", "standup", "sales_call", "interview", "class" ] }, "file": { "description": "The audio or video file itself (multipart only), up to 90 MB: MP3, M4A or MP4, WAV, FLAC, Ogg (Opus, Vorbis), WebM or AAC.", "type": "string", "format": "binary", "contentEncoding": "binary", "maxLength": 90000000 } } } }, "application/json": { "schema": { "type": "object", "properties": { "audio_url": { "description": "An https link Taad fetches the audio from (up to 200 MB). It must answer within 10 minutes and redirect at most 3 times. With a test key, `sample:no-speech`, `sample:unreadable`, `sample:too-long`, `sample:slow` and `sample:insufficient-credits` misbehave on purpose.", "type": "string", "maxLength": 2048 }, "transcript": { "description": "A transcript instead of audio: SubRip (.srt) or WebVTT text, plain text (\"Name: words\" lines), or segments. Taad writes the notes from it.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 5000000 }, { "minItems": 1, "maxItems": 50000, "type": "array", "items": { "type": "object", "properties": { "speaker": { "description": "Who said it, as you call them (\"Sara\"). Lines with the same name are one voice.", "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "start_ms", "end_ms", "text" ] } } ] }, "title": { "description": "Left out, Taad writes one from what was said.", "type": "string", "maxLength": 200 }, "language": { "description": "What was spoken, as a language code. Left out, Taad hears it.", "type": "string", "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$" }, "recorded_at": { "description": "When it was recorded (ISO 8601); now when left out.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "client_reference_id": { "description": "Your own id for it, one per workspace: sending the same one again answers 409 `duplicate_reference` with the recording that has it.", "type": "string", "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Your own labels: up to 20 keys of 40 characters, values of 500" }, "speaker_names": { "description": "The people in it, in the order they first speak: the voices are named so once it is transcribed.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "summary_shape": { "description": "How the summary is laid out; your default when left out.", "type": "string", "enum": [ "auto", "meeting", "one_to_one", "standup", "sales_call", "interview", "class" ] }, "file": { "description": "The audio or video file itself (multipart only), up to 90 MB: MP3, M4A or MP4, WAV, FLAC, Ogg (Opus, Vorbis), WebM or AAC.", "type": "string", "format": "binary", "contentEncoding": "binary", "maxLength": 90000000 } } } } } } } }, "/v1/recordings/{id}": { "get": { "operationId": "recordings.get", "tags": [ "Recordings" ], "summary": "Get a recording", "description": "One recording. `expand[]` adds its `notes`, `todos`, `calendar_event` or whole `transcript` (the transcript only when asked: it can be long).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "expand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "notes", "speakers", "todos", "calendar_event", "transcript" ] }, { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "notes", "speakers", "todos", "calendar_event", "transcript" ] } } ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "recording" }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "recording", "queued", "transcribing", "identifying_speakers", "writing_notes", "ready", "failed" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "title": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "workspace" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] } }, "required": [ "id", "object", "name", "kind" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "app", "import", "api" ] }, "language": { "type": "string" }, "recorded_at": { "type": "string", "description": "ISO 8601 in UTC" }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false } }, "calendar_event_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "place": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name", "color" ], "additionalProperties": false }, { "type": "null" } ] }, "client_reference_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cost": { "anyOf": [ { "type": "object", "properties": { "held_usd": { "type": "number", "description": "US dollars" }, "charged_usd": { "type": "number", "description": "US dollars" }, "plan_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "held_usd", "charged_usd", "plan_ms" ], "additionalProperties": false }, { "type": "null" } ] }, "app_url": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "notes": { "type": "object", "properties": { "object": { "type": "string", "const": "notes" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "summary_markdown": { "type": [ "string", "null" ] }, "taad_notes_markdown": { "type": [ "string", "null" ] }, "your_notes_markdown": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "who": { "type": [ "string", "null" ] }, "todo_id": { "anyOf": [ { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "text", "who", "todo_id" ], "additionalProperties": false } }, "shape": { "type": "string" }, "focus": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "object", "recording_id", "summary_markdown", "taad_notes_markdown", "your_notes_markdown", "action_items", "shape", "focus", "version", "updated_at" ], "additionalProperties": false }, "todos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } }, "calendar_event": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "null" } ] }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "speaker", "start_ms", "end_ms", "text" ], "additionalProperties": false } } }, "required": [ "id", "object", "livemode", "status", "failure", "title", "workspace", "source", "language", "recorded_at", "duration_ms", "speakers", "calendar_event_id", "place", "client_reference_id", "metadata", "cost", "app_url", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read", "x-taad-errors": [ "not_found" ] }, "patch": { "operationId": "recordings.update", "tags": [ "Recordings" ], "summary": "Update a recording", "description": "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).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "recording" }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "recording", "queued", "transcribing", "identifying_speakers", "writing_notes", "ready", "failed" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "title": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "workspace" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] } }, "required": [ "id", "object", "name", "kind" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "app", "import", "api" ] }, "language": { "type": "string" }, "recorded_at": { "type": "string", "description": "ISO 8601 in UTC" }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false } }, "calendar_event_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "place": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name", "color" ], "additionalProperties": false }, { "type": "null" } ] }, "client_reference_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cost": { "anyOf": [ { "type": "object", "properties": { "held_usd": { "type": "number", "description": "US dollars" }, "charged_usd": { "type": "number", "description": "US dollars" }, "plan_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "held_usd", "charged_usd", "plan_ms" ], "additionalProperties": false }, { "type": "null" } ] }, "app_url": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "notes": { "type": "object", "properties": { "object": { "type": "string", "const": "notes" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "summary_markdown": { "type": [ "string", "null" ] }, "taad_notes_markdown": { "type": [ "string", "null" ] }, "your_notes_markdown": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "who": { "type": [ "string", "null" ] }, "todo_id": { "anyOf": [ { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "text", "who", "todo_id" ], "additionalProperties": false } }, "shape": { "type": "string" }, "focus": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "object", "recording_id", "summary_markdown", "taad_notes_markdown", "your_notes_markdown", "action_items", "shape", "focus", "version", "updated_at" ], "additionalProperties": false }, "todos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } }, "calendar_event": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "null" } ] }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "speaker", "start_ms", "end_ms", "text" ], "additionalProperties": false } } }, "required": [ "id", "object", "livemode", "status", "failure", "title", "workspace", "source", "language", "recorded_at", "duration_ms", "speakers", "calendar_event_id", "place", "client_reference_id", "metadata", "cost", "app_url", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:write", "x-taad-errors": [ "not_found", "duplicate_reference", "version_conflict" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "client_reference_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "speakers": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "additionalProperties": false } } } } } }, "/v1/recordings/{id}/transcript": { "get": { "operationId": "recordings.transcript", "tags": [ "Recordings" ], "summary": "Get a transcript", "description": "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "format", "in": "query", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "txt", "md", "srt", "vtt" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "speaker", "start_ms", "end_ms", "text" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read", "x-taad-errors": [ "not_found", "not_ready" ] } }, "/v1/recordings/{id}/notes": { "get": { "operationId": "recordings.notes", "tags": [ "Recordings" ], "summary": "Get a recording's notes", "description": "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "notes" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "summary_markdown": { "type": [ "string", "null" ] }, "taad_notes_markdown": { "type": [ "string", "null" ] }, "your_notes_markdown": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "who": { "type": [ "string", "null" ] }, "todo_id": { "anyOf": [ { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "text", "who", "todo_id" ], "additionalProperties": false } }, "shape": { "type": "string" }, "focus": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "object", "recording_id", "summary_markdown", "taad_notes_markdown", "your_notes_markdown", "action_items", "shape", "focus", "version", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read", "x-taad-errors": [ "not_found" ] } }, "/v1/recordings/{id}/speakers": { "get": { "operationId": "recordings.speakers", "tags": [ "Recordings" ], "summary": "List a recording's speakers", "description": "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}.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "const": false }, "next_cursor": { "type": "null" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read", "x-taad-errors": [ "not_found" ] } }, "/v1/todos": { "get": { "operationId": "todos.list", "tags": [ "To-dos" ], "summary": "List to-dos", "description": "The to-dos the key reaches, newest first. With `updated_after`, oldest change first, for a sync that never misses one.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "recording_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "done", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "due_before", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "todos:read" }, "post": { "operationId": "todos.create", "tags": [ "To-dos" ], "summary": "Add a to-do", "description": "Added at the bottom of the list, in the workspace the key reaches. Link it to a recording with `recording_id`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "todos:write", "x-taad-errors": [ "not_found", "limit_reached" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "default": "medium", "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "default": false, "type": "boolean" }, "subtasks": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "done": { "default": false, "type": "boolean" } }, "required": [ "title" ], "additionalProperties": false } }, "who": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false } } } } } }, "/v1/todos/{id}": { "get": { "operationId": "todos.get", "tags": [ "To-dos" ], "summary": "Get a to-do", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "todos:read", "x-taad-errors": [ "not_found" ] }, "patch": { "operationId": "todos.update", "tags": [ "To-dos" ], "summary": "Update a to-do", "description": "Only the fields sent change. `done: true` marks it done now.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "todos:write", "x-taad-errors": [ "not_found" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "subtasks": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "done": { "default": false, "type": "boolean" } }, "required": [ "title" ], "additionalProperties": false } }, "who": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "additionalProperties": false } } } } }, "delete": { "operationId": "todos.delete", "tags": [ "To-dos" ], "summary": "Delete a to-do", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "todo" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "object", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "todos:write", "x-taad-errors": [ "not_found" ] } }, "/v1/calendar_events": { "get": { "operationId": "calendar_events.list", "tags": [ "Calendar" ], "summary": "List calendar events", "description": "Events on the calendar from `from` to `to` (days, at most 366 apart; the next 30 days when neither is given), by day and time. Or every event changed since `updated_after`, oldest change first, for a sync. `recording_id` keeps to the events heard in one recording. Suggestions heard in a recording and not accepted yet show only with `include_suggested=true`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "updated_after", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } }, { "name": "recording_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "include_suggested", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "calendar:read" }, "post": { "operationId": "calendar_events.create", "tags": [ "Calendar" ], "summary": "Add a calendar event", "description": "With a `recurrence`, a repeating event: its occurrences are made as the calendar is read, each an event of its own sharing a `series_id`. The answer is the first.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "calendar:write", "x-taad-errors": [ "invalid_request" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "default": "other", "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "default": null, "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "recurrence": { "default": null, "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq" ] }, { "type": "null" } ] }, "alerts": { "default": [], "maxItems": 5, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 10080 } } }, "required": [ "title", "day" ], "additionalProperties": false } } } } } }, "/v1/calendar_events/{id}": { "get": { "operationId": "calendar_events.get", "tags": [ "Calendar" ], "summary": "Get a calendar event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "calendar:read", "x-taad-errors": [ "not_found" ] }, "patch": { "operationId": "calendar_events.update", "tags": [ "Calendar" ], "summary": "Update a calendar event", "description": "Only the fields sent change. For a repeating event, `scope` says how far: `one` (this occurrence; the default), `following` (this one and those after it) or `series` (all of them), as in the app. Events from a connected Google or Outlook calendar are changed there (422).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "calendar:write", "x-taad-errors": [ "not_found", "unprocessable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq" ] }, { "type": "null" } ] }, "alerts": { "maxItems": 5, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 10080 } }, "scope": { "default": "one", "type": "string", "enum": [ "one", "following", "series" ] } }, "additionalProperties": false } } } } }, "delete": { "operationId": "calendar_events.delete", "tags": [ "Calendar" ], "summary": "Delete a calendar event", "description": "For a repeating event, `scope` says how far: `one` (the default), `following` or `series`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "scope", "in": "query", "required": false, "schema": { "default": "one", "type": "string", "enum": [ "one", "following", "series" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "calendar_event" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "object", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "calendar:write", "x-taad-errors": [ "not_found", "unprocessable" ] } }, "/v1/search": { "post": { "operationId": "search", "tags": [ "Search" ], "summary": "Search recordings", "description": "Finds what was said or written in the transcripts, notes and summaries the key reaches: by the `words` (give or take a typo), by `meaning`, or `both` ranked together (the default). Best first.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "search_hit" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "transcript", "notes", "summary" ] }, "snippet": { "type": "string" }, "start_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "speaker": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "recorded_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "score": { "type": "number" } }, "required": [ "object", "recording_id", "kind", "snippet", "start_ms", "speaker", "title", "recorded_at", "score" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "const": false }, "next_cursor": { "type": "null" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read", "x-taad-errors": [ "rate_limited" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "mode": { "default": "both", "type": "string", "enum": [ "words", "meaning", "both" ] }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "limit": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "query" ], "additionalProperties": false } } } } } }, "/v1/recordings/{id}/exports": { "post": { "operationId": "exports.create", "tags": [ "Exports" ], "summary": "Export a recording", "description": "Markdown (`md`) and text (`txt`) are ready in the answer, the text in `content`. A PDF takes a few seconds: the answer is `processing`; get it with GET /v1/exports/{id} until it is `ready` with its `download_url`. Files are kept a day. `parts` picks what goes in (all of them by default).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^exp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "export" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "format": { "type": "string", "enum": [ "md", "txt", "pdf" ] }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "content": { "type": [ "string", "null" ] }, "download_url": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "description": "ISO 8601 in UTC" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "recording_id", "format", "status", "content", "download_url", "filename", "expires_at", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read", "x-taad-errors": [ "not_found", "not_ready", "rate_limited" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "md", "txt", "pdf" ] }, "parts": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "summary", "action_items", "taad_notes", "your_notes", "transcript" ] } } }, "required": [ "format" ], "additionalProperties": false } } } } } }, "/v1/exports/{id}": { "get": { "operationId": "exports.get", "tags": [ "Exports" ], "summary": "Get an export", "description": "An export and, once `ready`, a fresh `download_url` (and the text of a Markdown or text one). Exports are kept a day.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^exp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "export" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "format": { "type": "string", "enum": [ "md", "txt", "pdf" ] }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "content": { "type": [ "string", "null" ] }, "download_url": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "description": "ISO 8601 in UTC" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "recording_id", "format", "status", "content", "download_url", "filename", "expires_at", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:read", "x-taad-errors": [ "not_found" ] } }, "/v1/usage": { "get": { "operationId": "usage.get", "tags": [ "Wallet" ], "summary": "The wallet, this week's minutes and this key's spend", "description": "What is in the API wallet (the person's for a personal key, the organization's for its keys), what running calls hold, and what is free for a new paid call. For a personal key, the person's plan and this week's minutes: with a paid plan and `spend_from` set to `plan_then_wallet`, sending audio uses those minutes first. And what this key spent this week against its cap. Test keys see the same wallet; their calls never spend from it.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "usage" }, "wallet": { "type": "object", "properties": { "balance_usd": { "type": "number", "description": "US dollars" }, "held_usd": { "type": "number", "description": "US dollars" }, "available_usd": { "type": "number", "description": "US dollars" } }, "required": [ "balance_usd", "held_usd", "available_usd" ], "additionalProperties": false }, "plan": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "enum": [ "individual", "free" ] }, "minutes": { "type": "number" }, "used": { "type": "number" }, "held": { "type": "number" }, "left": { "type": "number" }, "week_starts_at": { "type": "string", "description": "ISO 8601 in UTC" }, "resets_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "name", "minutes", "used", "held", "left", "week_starts_at", "resets_at" ], "additionalProperties": false }, { "type": "null" } ] }, "spend_from": { "type": "string", "enum": [ "plan_then_wallet", "wallet_only" ] }, "key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$" }, "spent_this_week_usd": { "type": "number", "description": "US dollars" }, "held_usd": { "type": "number", "description": "US dollars" }, "weekly_cap_usd": { "anyOf": [ { "type": "number", "description": "US dollars" }, { "type": "null" } ] }, "cap_left_usd": { "anyOf": [ { "type": "number", "description": "US dollars" }, { "type": "null" } ] }, "resets_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "spent_this_week_usd", "held_usd", "weekly_cap_usd", "cap_left_usd", "resets_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "object", "wallet", "plan", "spend_from", "key" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/prices": { "get": { "operationId": "prices.list", "tags": [ "Wallet" ], "summary": "The price list", "description": "What each paid call costs, in US dollars, and what a normal call of that size costs us. A call that costs us more than a normal one (a recording full of overlapping voices, a long question) is charged that difference too, at our cost, never multiplied. No key needed.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "price_list" }, "currency": { "type": "string", "const": "usd" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "price" }, "id": { "type": "string", "enum": [ "audio", "transcript", "transcribe_again", "rewrite", "ask_one", "ask_many" ] }, "description": { "type": "string" }, "unit": { "type": "string", "enum": [ "hour", "started_hour", "call" ] }, "price_usd": { "type": "number", "description": "US dollars" }, "normal_cost_usd": { "type": "number", "description": "US dollars" } }, "required": [ "object", "id", "description", "unit", "price_usd", "normal_cost_usd" ], "additionalProperties": false } }, "extra_at_cost": { "type": "string" }, "free": { "type": "string" }, "max_file_hours": { "type": "number" } }, "required": [ "object", "currency", "data", "extra_at_cost", "free", "max_file_hours" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/wallet/entries": { "get": { "operationId": "wallet_entries.list", "tags": [ "Wallet" ], "summary": "What went in and out of the wallet", "description": "The wallet's ledger, newest first: top-ups, refunds, charges (each says what for) and adjustments. The balance is their sum.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "top_up", "refund", "charge", "adjustment" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wle_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "wallet_entry" }, "kind": { "type": "string", "enum": [ "top_up", "refund", "charge", "adjustment" ] }, "amount_usd": { "type": "number", "description": "US dollars" }, "description": { "type": "string" }, "key_id": { "anyOf": [ { "type": "string", "pattern": "^key_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "kind", "amount_usd", "description", "key_id", "created_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ] } }, "/v1/recordings/{id}/transcribe_again": { "post": { "operationId": "recordings.transcribe_again", "tags": [ "Recordings" ], "summary": "Transcribe a recording again", "description": "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "recording" }, "livemode": { "type": "boolean" }, "status": { "type": "string", "enum": [ "recording", "queued", "transcribing", "identifying_speakers", "writing_notes", "ready", "failed" ] }, "failure": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "title": { "type": "string" }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "workspace" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "organization" ] } }, "required": [ "id", "object", "name", "kind" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "app", "import", "api" ] }, "language": { "type": "string" }, "recorded_at": { "type": "string", "description": "ISO 8601 in UTC" }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false } }, "calendar_event_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "place": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "name", "color" ], "additionalProperties": false }, { "type": "null" } ] }, "client_reference_id": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "cost": { "anyOf": [ { "type": "object", "properties": { "held_usd": { "type": "number", "description": "US dollars" }, "charged_usd": { "type": "number", "description": "US dollars" }, "plan_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "held_usd", "charged_usd", "plan_ms" ], "additionalProperties": false }, { "type": "null" } ] }, "app_url": { "type": "string" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "notes": { "type": "object", "properties": { "object": { "type": "string", "const": "notes" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "summary_markdown": { "type": [ "string", "null" ] }, "taad_notes_markdown": { "type": [ "string", "null" ] }, "your_notes_markdown": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "who": { "type": [ "string", "null" ] }, "todo_id": { "anyOf": [ { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "text", "who", "todo_id" ], "additionalProperties": false } }, "shape": { "type": "string" }, "focus": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "object", "recording_id", "summary_markdown", "taad_notes_markdown", "your_notes_markdown", "action_items", "shape", "focus", "version", "updated_at" ], "additionalProperties": false }, "todos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "todo" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "due": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ] }, "done": { "type": "boolean" }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "title", "done" ], "additionalProperties": false } }, "who": { "type": [ "string", "null" ] }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "description", "due", "priority", "done", "completed_at", "subtasks", "who", "recording_id", "created_at", "updated_at" ], "additionalProperties": false } }, "calendar_event": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "calendar_event" }, "workspace_id": { "type": "string", "pattern": "^wsp_[0-9A-HJKMNP-TV-Z]{26}$" }, "title": { "type": "string" }, "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "meeting", "call", "deadline", "reminder", "class", "other" ] }, "notes": { "type": [ "string", "null" ] }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "freq": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "interval": { "default": 1, "type": "integer", "minimum": 1, "maximum": 12 }, "until": { "default": null, "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "days": { "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "required": [ "freq", "interval", "until" ], "additionalProperties": false }, { "type": "null" } ] }, "series_id": { "anyOf": [ { "type": "string", "pattern": "^cal_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "alerts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "recording_id": { "anyOf": [ { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "said_at_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "user", "recording", "import", "connected" ] }, "suggested": { "type": "boolean" }, "read_only": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "workspace_id", "title", "day", "start", "end", "category", "notes", "recurrence", "series_id", "alerts", "recording_id", "said_at_ms", "source", "suggested", "read_only", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "null" } ] }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sp_[1-9]\\d{0,3}$" }, "name": { "type": [ "string", "null" ] }, "is_you": { "type": [ "boolean", "null" ] } }, "required": [ "id", "name", "is_you" ], "additionalProperties": false }, { "type": "null" } ] }, "start_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "text": { "type": "string" } }, "required": [ "speaker", "start_ms", "end_ms", "text" ], "additionalProperties": false } } }, "required": [ "id", "object", "livemode", "status", "failure", "title", "workspace", "source", "language", "recorded_at", "duration_ms", "speakers", "calendar_event_id", "place", "client_reference_id", "metadata", "cost", "app_url", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:write", "x-taad-paid": true, "x-taad-errors": [ "insufficient_balance", "key_cap_reached", "not_ready", "unprocessable" ] } }, "/v1/recordings/{id}/rewrite": { "post": { "operationId": "recordings.rewrite", "tags": [ "Recordings" ], "summary": "Rewrite a recording's summary", "description": "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "notes" }, "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "summary_markdown": { "type": [ "string", "null" ] }, "taad_notes_markdown": { "type": [ "string", "null" ] }, "your_notes_markdown": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "who": { "type": [ "string", "null" ] }, "todo_id": { "anyOf": [ { "type": "string", "pattern": "^tdo_[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] } }, "required": [ "text", "who", "todo_id" ], "additionalProperties": false } }, "shape": { "type": "string" }, "focus": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "cost_usd": { "type": "number", "description": "What the rewrite was charged (0 with a test key)." } }, "required": [ "object", "recording_id", "summary_markdown", "taad_notes_markdown", "your_notes_markdown", "action_items", "shape", "focus", "version", "updated_at", "cost_usd" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "recordings:write", "x-taad-paid": true, "x-taad-errors": [ "insufficient_balance", "key_cap_reached", "not_ready", "unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "focus": { "description": "What the summary keeps to, in your words (\"the pricing questions\"); null clears the one it has.", "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "template_id": { "description": "One of your note templates, by its id in Taad.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "shape": { "type": "string", "enum": [ "auto", "meeting", "one_to_one", "standup", "sales_call", "interview", "class" ] } } } } } } } }, "/v1/ask": { "post": { "operationId": "ask.create", "tags": [ "Ask" ], "summary": "Ask about your recordings", "description": "Answers a question from what was said in your recordings, in Markdown, with citations: the recording, where in it, and the words. About one recording: $0.05; across several (up to 40): $0.15. Charged only when it answers.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ask_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "ask" }, "livemode": { "type": "boolean" }, "question": { "type": "string" }, "answer_markdown": { "type": "string", "description": "The answer in Markdown. `[1]`, `[2]`… point at `citations`, in order." }, "citations": { "type": "array", "items": { "type": "object", "properties": { "recording_id": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "start_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "end_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quote": { "type": "string", "description": "The words said there, as transcribed." } }, "required": [ "recording_id", "start_ms", "end_ms", "quote" ], "additionalProperties": false } }, "recording_ids": { "type": "array", "items": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" }, "description": "The recordings the answer was drawn from." }, "cost_usd": { "type": "number", "description": "US dollars" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "livemode", "question", "answer_markdown", "citations", "recording_ids", "cost_usd", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "ask", "x-taad-paid": true, "x-taad-errors": [ "insufficient_balance", "key_cap_reached", "unprocessable", "unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000 }, "recording_ids": { "description": "The recordings to ask about. Left out: the 40 newest finished ones (within `since` and `until`).", "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "string", "pattern": "^rec_[0-9A-HJKMNP-TV-Z]{26}$" } }, "since": { "description": "Only recordings made from then.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" }, "until": { "description": "Only recordings made before then.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2}))?$" } }, "required": [ "question" ] } } } } } }, "/v1/webhook_endpoints": { "get": { "operationId": "webhook_endpoints.list", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "The endpoints that receive this workspace's events: the live ones for a live key, the sandbox's for a test key. At most 10 of each.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "failing", "manual" ] }, { "type": "null" } ] }, "failing_since": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "url", "description", "events", "enabled", "disabled_reason", "failing_since", "livemode", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks" }, "post": { "operationId": "webhook_endpoints.create", "tags": [ "Webhooks" ], "summary": "Add a webhook endpoint", "description": "Every event the endpoint takes is POSTed to `url` as JSON, transcripts and notes included, and signed the Standard Webhooks way (`webhook-id`, `webhook-timestamp`, `webhook-signature`). The answer holds the endpoint's `secret` (whsec_…), shown only this once: keep it to check signatures. The address must be https and public: private, loopback and link-local addresses are refused, when added and at every delivery. An endpoint made with a test key receives the sandbox's events (`livemode: false`).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "failing", "manual" ] }, { "type": "null" } ] }, "failing_since": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "secret": { "type": "string", "description": "whsec_…: check each delivery's `webhook-signature` with it. Shown only now." } }, "required": [ "id", "object", "url", "description", "events", "enabled", "disabled_reason", "failing_since", "livemode", "created_at", "updated_at", "secret" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks", "x-taad-errors": [ "unsafe_url", "limit_reached", "invalid_request" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "https:// only, and only a public address" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "events": { "maxItems": 14, "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } } }, "required": [ "url" ] } } } } } }, "/v1/webhook_endpoints/{id}": { "get": { "operationId": "webhook_endpoints.get", "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "failing", "manual" ] }, { "type": "null" } ] }, "failing_since": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "url", "description", "events", "enabled", "disabled_reason", "failing_since", "livemode", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks", "x-taad-errors": [ "not_found" ] }, "patch": { "operationId": "webhook_endpoints.update", "tags": [ "Webhooks" ], "summary": "Change a webhook endpoint", "description": "Change its address, its description or the events it takes, or turn it off (`enabled: false`). `enabled: true` works as `POST …/enable`: what it missed is sent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "failing", "manual" ] }, { "type": "null" } ] }, "failing_since": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "url", "description", "events", "enabled", "disabled_reason", "failing_since", "livemode", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks", "x-taad-errors": [ "unsafe_url", "invalid_request", "not_found" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "https:// only, and only a public address" }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "events": { "maxItems": 14, "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } }, "enabled": { "type": "boolean" } } } } } } }, "delete": { "operationId": "webhook_endpoints.delete", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Nothing more is sent to it, not even deliveries still waiting for a retry.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "object", "deleted" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks", "x-taad-errors": [ "not_found" ] } }, "/v1/webhook_endpoints/{id}/test": { "post": { "operationId": "webhook_endpoints.test", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Sends an `endpoint.test` event to this endpoint now, signed as every delivery is, and answers with what the endpoint answered: its status and the first kilobyte of its body. Works on an endpoint that is off; a test never counts towards turning one off.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_test" }, "event_id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "delivered": { "type": "boolean", "description": "The endpoint answered 2xx" }, "status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The endpoint's HTTP status; null when it couldn't be reached" }, "body": { "description": "The first kilobyte of its answer", "type": [ "string", "null" ] }, "error": { "description": "Why it wasn't delivered", "type": [ "string", "null" ] } }, "required": [ "object", "event_id", "delivered", "status", "body", "error" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks", "x-taad-errors": [ "not_found" ] } }, "/v1/webhook_endpoints/{id}/rotate_secret": { "post": { "operationId": "webhook_endpoints.rotate_secret", "tags": [ "Webhooks" ], "summary": "Rotate the signing secret", "description": "Makes a new secret, shown only in this answer. For the next 24 hours every delivery is signed with both the new and the old one (two signatures in `webhook-signature`, space-separated), so you can switch without missing a delivery.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "failing", "manual" ] }, { "type": "null" } ] }, "failing_since": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "secret": { "type": "string", "description": "whsec_…: check each delivery's `webhook-signature` with it. Shown only now." }, "previous_secret_expires_at": { "type": "string", "description": "ISO 8601 in UTC" } }, "required": [ "id", "object", "url", "description", "events", "enabled", "disabled_reason", "failing_since", "livemode", "created_at", "updated_at", "secret", "previous_secret_expires_at" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks", "x-taad-errors": [ "not_found" ] } }, "/v1/webhook_endpoints/{id}/enable": { "post": { "operationId": "webhook_endpoints.enable", "tags": [ "Webhooks" ], "summary": "Turn an endpoint back on", "description": "Turns it on and sends what it missed: every event of the last 30 days that it takes and hasn't received, oldest first. An endpoint is turned off after four days of failed deliveries, and its owner is emailed; nothing is lost meanwhile. `replayed` says how many events were queued.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "webhook_endpoint" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "anyOf": [ { "type": "string", "enum": [ "failing", "manual" ] }, { "type": "null" } ] }, "failing_since": { "anyOf": [ { "type": "string", "description": "ISO 8601 in UTC" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "updated_at": { "type": "string", "description": "ISO 8601 in UTC" }, "replayed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "object", "url", "description", "events", "enabled", "disabled_reason", "failing_since", "livemode", "created_at", "updated_at", "replayed" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-scope": "webhooks", "x-taad-errors": [ "not_found" ] } }, "/v1/events": { "get": { "operationId": "events.list", "tags": [ "Webhooks" ], "summary": "List events", "description": "Every event of the last 30 days, oldest first, delivered or not: the way to catch up after downtime, or to work without webhooks. An event is listed a couple of seconds after it happens (so one is never skipped). A key sees the events its scopes can read (`recording.*` needs `recordings:read`, `todo.*` `todos:read`, `calendar_event.*` `calendar:read`); one with `webhooks` sees them all, as its endpoints receive them. Keep `next_cursor` and pass it as `after` next time to get only what's new. A cursor older than 30 days answers 410 `cursor_expired`: start again from `GET /v1/recordings?updated_after=`.", "parameters": [ { "name": "after", "in": "query", "required": false, "description": "`next_cursor` from an earlier call", "schema": { "description": "`next_cursor` from an earlier call", "type": "string", "maxLength": 500 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted", "endpoint.test" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted", "endpoint.test" ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "livemode": { "type": "boolean" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "object", "type", "created_at", "livemode", "sequence", "data" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-errors": [ "cursor_expired" ] } }, "/v1/events/{id}": { "get": { "operationId": "events.get", "tags": [ "Webhooks" ], "summary": "Get an event", "description": "An event of the last 30 days, as it was sent, if the key's scopes can read it (as for the list).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string", "enum": [ "recording.created", "recording.ready", "recording.failed", "recording.updated", "recording.removed", "todo.created", "todo.updated", "todo.completed", "todo.deleted", "calendar_event.created", "calendar_event.updated", "calendar_event.deleted", "usage.balance_low", "usage.exhausted", "endpoint.test" ] }, "created_at": { "type": "string", "description": "ISO 8601 in UTC" }, "livemode": { "type": "boolean" }, "sequence": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "object", "type", "created_at", "livemode", "sequence", "data" ], "additionalProperties": false } } } }, "400": { "description": "The request isn't valid (`invalid_request`, `key_in_url`): the message says which field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or one that isn't good: `missing_key`, `malformed_key`, `unknown_key`, `revoked_key`, `expired_key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment: `payment_required` (no paid plan and no money in the API wallet), `insufficient_balance`, `key_cap_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed: `missing_scope`, `read_only_key`, `browser_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found, or outside what this key reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` or `queue_full`: wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] } ], "x-taad-errors": [ "not_found" ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "`Authorization: Bearer taad_…` (or `taadtest_…` for the sandbox). Never in a URL, never in a web page." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "billing_error", "permission_error", "not_found_error", "idempotency_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "doc_url": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "doc_url", "request_id" ], "additionalProperties": {} } }, "required": [ "error" ], "additionalProperties": false } } } }