{ "openapi": "3.1.0", "info": { "title": "bidi API", "description": "The bidi API: your agents, their knowledge, conversations and leads, from your own code. Authenticate with a workspace API key as `Authorization: Bearer bidi_sk_...` (create one in Settings > Developers; the Team plan and up). Lists page with `limit` and `cursor` and answer `{\"data\": [...], \"next_cursor\": ...}`. Errors answer `{\"error\": {\"code\", \"message\", \"request_id\"}}` with stable snake_case codes. Sixty requests per key per minute, twenty of them chat; `Retry-After` says when to come back. Send `Idempotency-Key` on creating POSTs to make retries safe for 24 hours: the same key with the same body replays the first answer, with another body it is 422, and a streamed chat ignores it. Changes inside v2 are additive; a breaking change is v3. Every response carries `X-Bidi-Api-Version`. A mobile or desktop app carries a publishable key (`bidi_pk_...`) instead: it reaches the Chat operations only (anything else answers 403 `secret_key_required`) and its limits count each calling address on its own; the iOS and Android SDKs use it.", "version": "2026-10-01" }, "servers": [ { "url": "https://www.bidii.ai/api/v2" } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "summary": "The calling key", "description": "What the API knows about the key you sent: its label, scopes,\nallowlist and expiry, and the workspace it belongs to with its plan.\n`workspace.id` is the id webhook events carry as `workspace_id`.\nA key follows the role of the teammate who made it: `key.maker`\nsays what that role holds back now (the keys of a teammate who\nleft the workspace are revoked, or answer 401 key_maker_left). A\ncheap first call.", "operationId": "me_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "any", "security": [ { "bearerAuth": [] } ] } }, "/agents": { "get": { "tags": [ "Agents" ], "summary": "List agents", "description": "The workspace's agents (live assistants), newest first. A key with an\nagent allowlist sees only those agents.", "operationId": "list_agents_agents_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:read", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}": { "get": { "tags": [ "Agents" ], "summary": "Get an agent", "description": "One agent by id. An id from another workspace is not found.", "operationId": "get_agent_agents__agent_id__get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:read", "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Agents" ], "summary": "Update an agent", "description": "Change the agent's name or the websites its widget answers on. Other\nfields (plan, status, prompt) are not writable through the API. The\nwebsite list follows the dashboard's rules: the same cleaning, the same\ncap of changes per hour (429 past it), and the same audit entry.", "operationId": "patch_agent_agents__agent_id__patch", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPatch" }, "examples": { "rename": { "summary": "Rename the agent", "value": { "name": "Front desk" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/sources": { "get": { "tags": [ "Sources" ], "summary": "List an agent's sources", "description": "Every knowledge source of the agent with its indexing status, newest first.", "operationId": "list_sources_agents__agent_id__sources_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:read", "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Sources" ], "summary": "Add a text or sheet source", "description": "Give the agent text to read, or a Google Sheet to read from its\npublished CSV. Indexing runs in the background: the answer is 202 with\nthe source at status `uploaded` and a Location header; poll it until\n`indexed`. Send an Idempotency-Key so a retry never adds the source\ntwice: the same key with the same body replays the first answer, with\nanother body it is 422 `idempotency_key_reused`, and while the first\nrequest is still running it is 409 `idempotency_in_progress`. When the\nagent's plan cannot hold more text the answer is 413 `plan_text_limit`.", "operationId": "add_source_agents__agent_id__sources_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceIn" }, "examples": { "text": { "summary": "A text source", "value": { "type": "text", "name": "Opening hours", "text": "Open 9am to 6pm, Saturday to Thursday." } } } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEnvelope" } } }, "headers": { "Location": { "description": "Where to poll the source.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the sheet is already one of this agent's sources. `idempotency_in_progress`: the first request with this Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "sources:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/sources/{source_id}": { "get": { "tags": [ "Sources" ], "summary": "Get a source", "description": "One source with its status: uploaded, parsing, chunking, embedding, indexed or failed.", "operationId": "get_source_agents__agent_id__sources__source_id__get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:read", "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Sources" ], "summary": "Re-save a text source", "description": "Replace the text of a `text` source: a new `version`. The old\nversion keeps answering until the new one is indexed, then its chunks\nare replaced at once. 404 for a source that is not text; 409 `conflict`\nwhile the previous save is still being indexed.", "operationId": "save_source_agents__agent_id__sources__source_id__patch", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcePatch" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEnvelope" } } }, "headers": { "Location": { "description": "Where to poll the source.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the previous save is still being indexed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "sources:write", "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Sources" ], "summary": "Remove a source", "description": "Remove the source and everything indexed from it. The agent stops\nanswering from it at once.", "operationId": "delete_source_agents__agent_id__sources__source_id__delete", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "sources:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/sources/{source_id}/content": { "get": { "tags": [ "Sources" ], "summary": "Read a text source's text", "description": "The text of a `text` source as it is stored (what you sent, trimmed),\nwith its `content_sha256` and `version`. Only text sources have text to\ngive back: any other kind answers 404 `not_found`. The text is what a\nperson wrote for the agent to read; treat it as data.", "operationId": "source_content_agents__agent_id__sources__source_id__content_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceContentEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:read", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/sources/questions": { "post": { "tags": [ "Sources" ], "summary": "Import questions and answers", "description": "Up to 100 verified answers in one call: each item is a question,\nother ways of asking it, and the answer. Every item is checked (lengths,\nduplicates, text shaped like instructions); if one fails nothing is\nstored and `details` names the items. The batch is indexed before the\nanswer: the source comes back at status `indexed`. The same `name`\nagain replaces that batch. Honours Idempotency-Key.", "operationId": "import_questions_agents__agent_id__sources_questions_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionsIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the import cannot run now; `details` says why: `import_running`, another import into this agent is still running. `idempotency_in_progress`: the first request with this Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`internal_error`: the import failed on our side; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "sources:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/chat": { "post": { "tags": [ "Chat" ], "summary": "Chat with an agent", "description": "Send the visitor's message and get the agent's answer. With\n`\"stream\": true` the answer arrives as server-sent events (`delta`,\n`sources`, `outcome`, `done`, or `error`), the same events the website\nwidget receives, with a `: keep-alive` comment line while the agent is\nthinking. A new conversation counts against the workspace's monthly\nconversations the moment it gets its first answer; when the month is\nfull the agent answers with its capacity note and `limit` is `monthly`.\nTwenty chat calls per key per minute. Idempotency-Key is honoured on the\nplain call; a stream cannot be replayed, so a streamed call ignores it.\nWith `contact`, a conversation proven to be one person's is never\ncontinued as another's: that call answers 409 `identity_mismatch` and\nno turn runs.", "operationId": "chat_agents__agent_id__chat_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatIn" } } } }, "responses": { "200": { "description": "The answer. `application/json` by default; `text/event-stream` when `stream` is true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events: `delta` {text}, `sources` {sources}, `outcome` {outcome, state, refused, limit}, then `done` (the same object the plain call returns) or `error` {code, message, request_id}. With `client_tools`, `client_tool` {call_id, name, args, timeout_ms, conversation_id} may come mid-stream: run the tool and answer it on POST /agents/{agent_id}/chat/tool-results. Lines starting with `:` are keep-alives. `x-bidi-events` names each event's schema." }, "x-bidi-events": { "delta": { "$ref": "#/components/schemas/ChatStreamDelta" }, "sources": { "$ref": "#/components/schemas/ChatStreamSources" }, "outcome": { "$ref": "#/components/schemas/ChatStreamOutcome" }, "client_tool": { "$ref": "#/components/schemas/ChatStreamClientTool" }, "done": { "$ref": "#/components/schemas/ChatResponse" }, "error": { "$ref": "#/components/schemas/ChatStreamError" } } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`agent_unavailable`: the agent is paused. `identity_mismatch`: the conversation is another verified contact's; start a new one for this contact. `idempotency_in_progress`: the first request with this Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "`conversation_expired`: the conversation is over; start a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`identity_unavailable`: the agent's identity secret cannot be read right now, so `contact` cannot be verified; retry after `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "chat", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/chat/tool-results": { "post": { "tags": [ "Chat" ], "summary": "Answer a client tool call", "description": "Your app ran the client tool a streamed chat asked for (the\n`client_tool` event) and says how it went. Only the conversation the\ncall belongs to can answer it, once, before its `timeout_ms`; a second\nanswer, or a late one, is 409 `call_closed`, and a call this\nconversation never had is 404 `unknown_call`. Needs the actions feature\non the server (404 otherwise).", "operationId": "tool_result_agents__agent_id__chat_tool_results_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatToolResultIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatToolResultOut" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`call_closed`: the call was already answered or ran out of time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "chat", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List an agent's conversations", "description": "Conversations of the agent, newest first, across every channel (the\nwebsite widget, the hosted page, the API, email, Slack and voice). Filter\nby `state` and `channel`; page with `cursor`.", "operationId": "list_conversations_agents__agent_id__conversations_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." }, { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "ai_active", "handoff_requested", "human_active", "closed" ], "type": "string" }, { "type": "null" } ], "description": "Only conversations in this state.", "title": "State" }, "description": "Only conversations in this state." }, { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "website", "hosted", "api", "email", "slack", "voice_web" ], "type": "string" }, { "type": "null" } ], "description": "Only conversations on this channel: website (the chat bubble on a site), hosted (the chat page), api, email, slack or voice_web.", "title": "Channel" }, "description": "Only conversations on this channel: website (the chat bubble on a site), hosted (the chat page), api, email, slack or voice_web." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "conversations:read", "security": [ { "bearerAuth": [] } ] } }, "/conversations/{conversation_id}": { "get": { "tags": [ "Conversations" ], "summary": "Get a conversation", "description": "One conversation: its state, timestamps and the summary the inbox shows.", "operationId": "get_conversation_conversations__conversation_id__get", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "conversations:read", "security": [ { "bearerAuth": [] } ] } }, "/conversations/{conversation_id}/messages": { "get": { "tags": [ "Conversations" ], "summary": "List a conversation's messages", "description": "The messages in the order they were said, with the outcome and the\nsources behind each AI answer.", "operationId": "list_messages_conversations__conversation_id__messages_get", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "conversations:read", "security": [ { "bearerAuth": [] } ] } }, "/leads": { "get": { "tags": [ "Leads" ], "summary": "List leads", "description": "Leads across the workspace's agents, newest first: name, how to reach\nthem, what they asked about, the agent's own fields in `data`, the\nteam's notes, and the conversation they came from.", "operationId": "list_leads_leads_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only leads captured by this agent.", "title": "Agent Id" }, "description": "Only leads captured by this agent." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "new", "qualified", "closed" ], "type": "string" }, { "type": "null" } ], "description": "Only leads in this status.", "title": "Status" }, "description": "Only leads in this status." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "leads:read", "security": [ { "bearerAuth": [] } ] } }, "/leads/{lead_id}": { "get": { "tags": [ "Leads" ], "summary": "Get a lead", "description": "One lead by id.", "operationId": "get_lead_leads__lead_id__get", "parameters": [ { "name": "lead_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Lead Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "leads:read", "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Leads" ], "summary": "Update a lead", "description": "Change any of: `status` (new, qualified, closed), `name`, `contact`,\n`interest`, `notes`, and `data` (merged into the lead's fields by key;\na null removes a key; a select field takes only one of its options).\nSend at least one. A status change emits `lead.status_changed`; every\nchange emits `lead.updated`.", "operationId": "patch_lead_leads__lead_id__patch", "parameters": [ { "name": "lead_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Lead Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadChanges" }, "examples": { "qualify": { "summary": "Mark the lead qualified", "value": { "status": "qualified" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "leads:write", "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Leads" ], "summary": "Delete a lead", "description": "Delete the lead for good. The conversation it came from and any\nbooking made for it stay, no longer linked to it. The workspace's audit\nlog records that a lead was deleted, and by which key.", "operationId": "delete_lead_leads__lead_id__delete", "parameters": [ { "name": "lead_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Lead Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "leads:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/lead-fields": { "get": { "tags": [ "Leads" ], "summary": "List an agent's lead fields", "description": "The extra details this agent collects with a lead, in the order the\nowner arranged them: the key each value is stored under in a lead's\n`data`, its English and Arabic labels, its kind and, for a select, its\noptions.", "operationId": "list_lead_fields_agents__agent_id__lead_fields_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFieldList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "leads:read", "security": [ { "bearerAuth": [] } ] } }, "/tickets": { "get": { "tags": [ "Tickets" ], "summary": "List tickets", "description": "The workspace's tickets, newest first: whose move it is (`status`),\nwho has it, the conversation it belongs to, the team's own fields in\n`custom`, the `tags` the helpdesk rules wrote (narrow with `tag`), and\nhow long the first answer and the resolution took.", "operationId": "list_tickets_tickets_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only tickets of this agent.", "title": "Agent Id" }, "description": "Only tickets of this agent." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "new", "on_you", "on_customer", "on_hold", "closed" ], "type": "string" }, { "type": "null" } ], "description": "Only tickets in this status.", "title": "Status" }, "description": "Only tickets in this status." }, { "name": "assignee_user_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only tickets held by this member (a user id).", "title": "Assignee User Id" }, "description": "Only tickets held by this member (a user id)." }, { "name": "tag", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "description": "Only tickets carrying this tag (one the workspace's helpdesk rules wrote; see `tags` on the ticket).", "title": "Tag" }, "description": "Only tickets carrying this tag (one the workspace's helpdesk rules wrote; see `tags` on the ticket)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "tickets:read", "security": [ { "bearerAuth": [] } ] } }, "/tickets/{ticket_id}": { "get": { "tags": [ "Tickets" ], "summary": "Get a ticket", "description": "One ticket by id.", "operationId": "get_ticket_tickets__ticket_id__get", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "tickets:read", "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Tickets" ], "summary": "Update a ticket", "description": "Change any of: `status` (`on_hold`, `closed`, or `open` to release a\nhold or reopen), `priority`, `assignee_user_id` (null for nobody) and\n`custom` (merged by key and checked against the workspace's ticket\nfields). Send at least one. Every change emits `ticket.updated`;\nclosing emits `ticket.closed` as well and hands the visitor back to the\nassistant.", "operationId": "patch_ticket_tickets__ticket_id__patch", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketPatch" }, "examples": { "priority": { "summary": "Raise the priority", "value": { "priority": "high" } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the ticket cannot move to that status from where it is.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "tickets:write", "security": [ { "bearerAuth": [] } ] } }, "/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "The workspace's contacts, most recently seen first: who they are, how\nto reach them, their attributes and whether a host site verified them.\nFilter by `email`, `phone` or `external_id` to look one person up. A\nkey limited to some agents lists the contacts of those agents.", "operationId": "list_contacts_contacts_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." }, { "name": "email", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ], "description": "Only the contact with this email (any casing).", "title": "Email" }, "description": "Only the contact with this email (any casing)." }, { "name": "phone", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ], "description": "Only the contact with this phone number, however it is written.", "title": "Phone" }, "description": "Only the contact with this phone number, however it is written." }, { "name": "external_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Only the contact with this external_id.", "title": "External Id" }, "description": "Only the contact with this external_id." }, { "name": "verified", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Only verified (true) or unverified (false) contacts.", "title": "Verified" }, "description": "Only verified (true) or unverified (false) contacts." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "contacts:read", "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Contacts" ], "summary": "Create or update a contact", "description": "Add a person, or complete the contact they already are: matched by\n`external_id`, then by email, then by phone. Send at least one of the\nthree. A new contact answers 201 with a `Location`; an existing one\nanswers 200 with the values you sent written over it (an empty value\nleaves what is there) and `attributes` merged by key. An email or phone\nthat already belongs to another contact is kept for reading and does\nnot become a second key for the same number. New contacts emit\n`contact.created`. Needs a key that reaches every agent.", "operationId": "create_contact_contacts_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIn" }, "examples": { "signed_in": { "summary": "A signed-in customer", "value": { "external_id": "u_42", "name": "Sara", "email": "sara@example.ae", "attributes": { "plan": "Gold" } } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The person was already a contact and was completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } } } } }, "x-bidi-scope": "contacts:write", "security": [ { "bearerAuth": [] } ] } }, "/contacts/{contact_id}": { "get": { "tags": [ "Contacts" ], "summary": "Get a contact", "description": "One contact by id.", "operationId": "get_contact_contacts__contact_id__get", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "contacts:read", "security": [ { "bearerAuth": [] } ] }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Change any of `name`, `email`, `phone` and `attributes`. Only what\nyou send changes. An email or phone that already belongs to another\ncontact answers 409.", "operationId": "patch_contact_contacts__contact_id__patch", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactPatch" }, "examples": { "attribute": { "summary": "Change one attribute", "value": { "attributes": { "plan": "Platinum" } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: `details` says why: `contact_exists`, the email or phone belongs to another contact; `marketing_suppressed`, the person unsubscribed, so consent cannot be given for them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "contacts:write", "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "description": "Delete the contact, everything an agent remembers of them and their\nleads. Their conversations stay, no longer linked to a contact. Needs a\nkey that reaches every agent; a contact with leads needs `leads:write`\nas well (403 insufficient_scope otherwise, and nothing is deleted).", "operationId": "delete_contact_contacts__contact_id__delete", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "contacts:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/actions": { "get": { "tags": [ "Actions" ], "summary": "List an agent's actions", "description": "What the agent can do beyond answering: HTTP calls on verified hosts,\ncollect-data forms, client tools the host page runs, integrations. The\nheaders an HTTP action sends are never returned, only their names.", "operationId": "list_actions_agents__agent_id__actions_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:read", "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Actions" ], "summary": "Create an action", "description": "A new action, switched off unless `enabled` is true (an HTTP action\nswitches on only once its host is verified). The plan caps actions per\nagent (402 plan_required beyond it).", "operationId": "create_action_agents__agent_id__actions_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionIn" }, "examples": { "client_tool": { "summary": "A tool your page runs", "value": { "name": "open_cart", "kind": "client_tool", "description_en": "Open the cart on this page.", "description_ar": "يفتح سلة المشتريات في هذه الصفحة." } } } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`plan_required`: the agent already has as many actions as its plan allows, or the action waits for approval and the plan has no helpdesk; `required_plan` names the plan to move to. On the plan that holds the most actions there is none: `required_plan` is absent and the way out is removing one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`name_taken`: another action of this agent has that name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/actions/{action_id}": { "patch": { "tags": [ "Actions" ], "summary": "Update an action", "description": "Any field, `enabled`, or `headers` (they replace the stored ones;\n`{}` removes them).", "operationId": "patch_action_agents__agent_id__actions__action_id__patch", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Action Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionIn" }, "examples": { "switch_off": { "summary": "Switch the action off", "value": { "enabled": false } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`plan_required`: the action would wait for approval and the plan has no helpdesk; `required_plan` names the plan to move to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`name_taken`: another action of this agent has that name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:write", "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Actions" ], "summary": "Delete an action", "description": "The action is gone; what its forms gathered goes with it.", "operationId": "delete_action_agents__agent_id__actions__action_id__delete", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Action Id" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "agents:write", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/actions/{action_id}/calls": { "get": { "tags": [ "Actions" ], "summary": "List an action's calls", "description": "The action's calls in conversations, newest first: when, the outcome, why it failed or was not run,\nhow long it took and the conversation it came from. A request the team approved is one call, with who\ndecided it (their user id). Preview calls are left out. `failures_only` keeps what failed, was not run,\nor expired. What it was asked is the names of the action's inputs only, never their values; where the\nowner's system lives is not here (`GET /agents/{agent_id}/actions`, agents:read).", "operationId": "list_calls_agents__agent_id__actions__action_id__calls_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "action_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Action Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." }, { "name": "failures_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Failures Only" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "conversations:read", "security": [ { "bearerAuth": [] } ] } }, "/agents/{agent_id}/submissions": { "get": { "tags": [ "Actions" ], "summary": "List form submissions", "description": "What the agent's collect-data actions gathered in conversations,\nnewest first, each with the conversation it came from.", "operationId": "list_submissions_agents__agent_id__submissions_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." }, { "name": "action_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "leads:read", "security": [ { "bearerAuth": [] } ] } }, "/usage": { "get": { "tags": [ "Usage" ], "summary": "This month's usage", "description": "The workspace's pool (the plan's conversations plus this month's\ntop-ups, shared by every agent) and, per agent, what it counted and its\nmessages, for the current month in UTC. A conversation is counted once,\non its first answered message, on any channel.", "operationId": "get_usage_usage_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEnvelope" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "usage:read", "security": [ { "bearerAuth": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "The destinations this workspace sends events to, with the event types\neach one subscribes to. Create and edit them in Settings > Developers,\nor subscribe from code with POST /webhooks. A key limited to some agents\nlists the endpoints pinned to those agents only (the ones it may also\nremove), never one that takes every agent's events.\nThe scope is `webhooks:read` (a key with `webhooks:write` has it too).", "operationId": "list_webhooks_webhooks_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page, 1 to 100.", "default": 20, "title": "Limit" }, "description": "Rows per page, 1 to 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next_cursor of the previous page.", "title": "Cursor" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "webhooks:read", "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Subscribe a webhook", "description": "A REST hook: events of the types you name are POSTed to `url`, signed\nwith the `secret` this call answers (once; keep it). The same contract as\nan endpoint made in Settings > Developers: `X-Bidi-Signature:\nt=,v1=` over `.`, retries over 14 hours, and the\ndelivery log there. Up to 10 endpoints per workspace (409\ntoo_many_endpoints). A refused URL is 422 with the reason in `details`\n(`url_not_https`, `url_private`, `url_unresolved`, ...). Send\n`Idempotency-Key` so a retried subscribe makes one endpoint; the replay\nanswers the endpoint with `secret: null` (the secret is never stored in\nthe clear, so it is shown once only: rotate it in Settings > Developers\nif the first answer was lost). Each event type needs the key to hold the\nscope that reads its data (lead.* and form.submitted `leads:read`,\nticket.* `tickets:read`, conversation.* and message.created\n`conversations:read`, contact.created and campaign.sent `contacts:read`,\nusage.threshold `usage:read`, the rest `agents:read`); 403\ninsufficient_scope otherwise. This is what the Zapier and Make apps call\nwhen a Zap or scenario is switched on.", "operationId": "subscribe_webhooks_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookIn" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } } }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`too_many_endpoints`: the workspace already has 10 webhooks; remove one first. `idempotency_in_progress`: the first request with this Idempotency-Key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ] } }, "/webhooks/{webhook_id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Unsubscribe a webhook", "description": "Remove an endpoint and its delivery log; nothing more is sent to it.\nA key limited to some agents removes only the endpoints pinned to one\nof them. The endpoint a Build bot's webhook plugin sends through is the\nplugin's, and answers 404 here: disconnect the plugin instead.", "operationId": "unsubscribe_webhooks__webhook_id__delete", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers `key_maker_left`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (`maker_role_limit`; a publishable key says `insufficient_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Nothing by that id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: `plan_text_limit`, the agent's plan cannot hold more text (`limit_chars`, `used_chars`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request did not validate; `details` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; wait `Retry-After` seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Our fault; quote `request_id` to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-bidi-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "ActionEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/ActionOut" } }, "type": "object", "required": [ "data" ], "title": "ActionEnvelope" }, "ActionIn": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kind" }, "description_en": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description En" }, "description_ar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description Ar" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method" }, "url_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url Template" }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers" }, "input_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Schema" }, "output_pick": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Output Pick" }, "data_access": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data Access" }, "requires_approval": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Requires Approval" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled" }, "config": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Config" } }, "additionalProperties": false, "type": "object", "title": "ActionIn", "description": "Every field optional: a create needs the action's own, a change any." }, "ActionList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ActionOut" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ActionList" }, "ActionOut": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_id": { "type": "string", "title": "Agent Id" }, "name": { "type": "string", "title": "Name" }, "kind": { "type": "string", "title": "Kind", "description": "http, collect_data, client_tool or integration." }, "description_en": { "type": "string", "title": "Description En" }, "description_ar": { "type": "string", "title": "Description Ar" }, "method": { "type": "string", "title": "Method" }, "url_template": { "type": "string", "title": "Url Template" }, "host": { "type": "string", "title": "Host" }, "host_verified": { "type": "boolean", "title": "Host Verified" }, "input_schema": { "additionalProperties": true, "type": "object", "title": "Input Schema" }, "output_pick": { "items": { "type": "string" }, "type": "array", "title": "Output Pick" }, "data_access": { "type": "string", "title": "Data Access" }, "requires_approval": { "type": "boolean", "title": "Requires Approval" }, "enabled": { "type": "boolean", "title": "Enabled" }, "has_headers": { "type": "boolean", "title": "Has Headers" }, "header_names": { "items": { "type": "string" }, "type": "array", "title": "Header Names" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "agent_id", "name", "kind", "description_en", "description_ar", "method", "url_template", "host", "host_verified", "input_schema", "output_pick", "data_access", "requires_approval", "enabled", "has_headers", "header_names" ], "title": "ActionOut" }, "Agent": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name", "description": "The agent's display name." }, "status": { "type": "string", "title": "Status", "description": "live, paused or retired." }, "language": { "type": "string", "title": "Language", "description": "english, arabic or bilingual." }, "public_key": { "type": "string", "title": "Public Key", "description": "The key in the website snippet (pk_...). Not a secret." }, "allowed_origins": { "items": { "type": "string" }, "type": "array", "title": "Allowed Origins", "description": "The websites the widget answers on." }, "conversations_per_month": { "type": "integer", "title": "Conversations Per Month", "description": "The plan's monthly allowance for this agent." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "type": "object", "required": [ "id", "name", "status", "language", "public_key", "allowed_origins", "conversations_per_month" ], "title": "Agent" }, "AgentEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/Agent" } }, "type": "object", "required": [ "data" ], "title": "AgentEnvelope" }, "AgentList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Agent" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Pass it as `cursor` for the next page; null on the last." } }, "type": "object", "required": [ "data" ], "title": "AgentList" }, "AgentPatch": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Name", "description": "The agent's display name (1 to 120 characters)." }, "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 10 }, { "type": "null" } ], "title": "Allowed Origins", "description": "The websites the widget answers on, as origins (https://shop.example). An internationalised domain is stored in its DNS form (xn--...)." } }, "additionalProperties": false, "type": "object", "title": "AgentPatch" }, "AgentUsage": { "properties": { "agent_id": { "type": "string", "title": "Agent Id" }, "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status" }, "conversations": { "$ref": "#/components/schemas/UsageConversations" }, "messages": { "type": "integer", "title": "Messages" } }, "type": "object", "required": [ "agent_id", "name", "status", "conversations", "messages" ], "title": "AgentUsage" }, "CallApproval": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "title": "Status", "description": "pending, approved, rejected, expired or failed." }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "decided_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Decided At" }, "decided_by": { "anyOf": [ { "$ref": "#/components/schemas/CallDecider" }, { "type": "null" } ], "description": "Who approved or rejected it." } }, "type": "object", "required": [ "id", "status" ], "title": "CallApproval" }, "CallDecider": { "properties": { "user_id": { "type": "string", "title": "User Id", "description": "The team member's id, as a ticket's assignee_user_id." } }, "type": "object", "required": [ "user_id" ], "title": "CallDecider" }, "CallList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CallOut" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "CallList" }, "CallOut": { "properties": { "id": { "type": "string", "title": "Id" }, "at": { "type": "string", "title": "At" }, "outcome": { "type": "string", "title": "Outcome", "description": "worked, failed, refused (not run), waiting (for the team's approval), approved, rejected, expired, or sent (asked for approval before this record kept the request)." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Why it failed, was refused or expired, as a stable code (timeout, http_status, invalid_input, conversation_cap, closed, ...); null when the record names none." }, "detail": { "additionalProperties": true, "type": "object", "title": "Detail", "description": "What the reason names: the status a system answered, the inputs that did not fit, the vendor." }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latency Ms" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "The conversation it came from, while it exists." }, "ticket_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ticket Id", "description": "The ticket the team approves a request on." }, "inputs": { "items": { "type": "string" }, "type": "array", "title": "Inputs", "description": "The names of the action's inputs it was called with, never their values." }, "approval": { "anyOf": [ { "$ref": "#/components/schemas/CallApproval" }, { "type": "null" } ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/CallResult" }, { "type": "null" } ], "description": "An approved request: how the call went." } }, "type": "object", "required": [ "id", "at", "outcome", "detail", "inputs" ], "title": "CallOut" }, "CallResult": { "properties": { "outcome": { "type": "string", "title": "Outcome", "description": "worked or failed." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "detail": { "additionalProperties": true, "type": "object", "title": "Detail" } }, "type": "object", "required": [ "outcome" ], "title": "CallResult" }, "ChatIn": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/ChatMessage" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Messages", "description": "The last entry must be the visitor's new message (role user). Earlier entries are ignored when conversation_id is set: the stored conversation is the context." }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id", "description": "Continue this conversation; omit to start one." }, "conversation_token": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Conversation Token", "description": "With a publishable key: the `conversation_token` the conversation's first answer gave. Required to continue it (the id alone answers 404 conversation_not_found), because a publishable key ships inside the app and conversation ids are not secret." }, "stream": { "type": "boolean", "title": "Stream", "description": "true answers text/event-stream.", "default": false }, "locale": { "anyOf": [ { "type": "string", "maxLength": 10 }, { "type": "null" } ], "title": "Locale", "description": "Reserved: a hint for the reply language." }, "contact": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "properties": { "token": { "type": "string", "description": "A JWT (HS256) signed with the agent's identity secret." }, "user_id": { "type": "string", "description": "Your id for the person (the HMAC shape)." }, "user_hash": { "type": "string", "description": "HMAC-SHA256(identity secret, user_id) in hex." }, "email": { "type": "string", "description": "Shown to the team; proven only inside a JWT." }, "name": { "type": "string", "description": "Shown to the team; proven only inside a JWT." } }, "title": "Contact", "description": "Who the visitor is, in either identity shape: {\"token\": a JWT signed with the agent's identity secret} or {\"user_id\", \"user_hash\"}. Verified, it links the conversation to that contact (and its memory); one that does not verify answers 401 identity_rejected. A conversation proven to be one person's is never continued as another: send a different verified contact with its conversation_id and the call answers 409 identity_mismatch (omit conversation_id to start that person's own conversation)." }, "client_tools": { "items": { "type": "string" }, "type": "array", "maxItems": 20, "title": "Client Tools", "description": "The client tools your app can run (snake_case names, up to 20). Only the owner's declared client tools among them are offered, and only on a streamed call: the agent asks with a `client_tool` event and your app answers on POST /agents/{agent_id}/chat/tool-results." } }, "additionalProperties": false, "type": "object", "required": [ "messages" ], "title": "ChatIn" }, "ChatMessage": { "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ], "title": "Role" }, "content": { "type": "string", "maxLength": 1000, "minLength": 1, "title": "Content" } }, "additionalProperties": false, "type": "object", "required": [ "role", "content" ], "title": "ChatMessage" }, "ChatMessageOut": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "role": { "type": "string", "title": "Role" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content" } }, "type": "object", "required": [ "role" ], "title": "ChatMessageOut" }, "ChatResponse": { "properties": { "conversation_id": { "type": "string", "title": "Conversation Id", "description": "Send it back to continue this conversation." }, "conversation_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Token", "description": "Publishable keys only, on the answer that starts a conversation: send it back with conversation_id to continue it. Shown once; keep it with the id." }, "message": { "anyOf": [ { "$ref": "#/components/schemas/ChatMessageOut" }, { "type": "null" } ], "description": "The agent's answer; null when a person has taken over." }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "refused": { "type": "boolean", "title": "Refused" }, "sources": { "items": {}, "type": "array", "title": "Sources" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "lead_captured": { "type": "boolean", "title": "Lead Captured" }, "limit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Limit", "description": "`monthly` when the month's conversations are used up." }, "degraded": { "type": "boolean", "title": "Degraded" } }, "type": "object", "required": [ "conversation_id", "refused", "sources", "lead_captured", "degraded" ], "title": "ChatResponse" }, "ChatToolResultIn": { "properties": { "conversation_id": { "type": "string", "title": "Conversation Id", "description": "The conversation the `client_tool` event belongs to." }, "conversation_token": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Conversation Token", "description": "The event's `conversation_token` (publishable keys)." }, "call_id": { "type": "string", "title": "Call Id", "description": "The event's `call_id`." }, "ok": { "type": "boolean", "title": "Ok", "description": "false when your tool failed; the agent is told it did not work." }, "result": { "title": "Result", "description": "What the tool returned, as JSON (at most 8,000 characters). The agent reads it as data, never as instructions." }, "error": { "type": "string", "title": "Error", "description": "A short reason when ok is false (120 characters are kept).", "default": "" } }, "additionalProperties": false, "type": "object", "required": [ "conversation_id", "call_id", "ok" ], "title": "ChatToolResultIn" }, "ChatToolResultOut": { "properties": { "ok": { "type": "boolean", "title": "Ok" } }, "type": "object", "required": [ "ok" ], "title": "ChatToolResultOut" }, "Contact": { "properties": { "id": { "type": "string", "title": "Id" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Id", "description": "Your own id for this person; null when none was given." }, "name": { "type": "string", "title": "Name" }, "email": { "type": "string", "title": "Email" }, "phone": { "type": "string", "title": "Phone" }, "attributes": { "additionalProperties": true, "type": "object", "title": "Attributes", "description": "A flat object of text, numbers and booleans." }, "verified": { "type": "boolean", "title": "Verified", "description": "True when a host site proved this person's identity with an agent's identity secret." }, "source": { "type": "string", "title": "Source", "description": "How the contact first arrived: manual, import, identify, lead or api." }, "first_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Seen At" }, "last_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen At" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "consent_marketing": { "type": "boolean", "title": "Consent Marketing", "description": "The person explicitly agreed to campaign emails.", "default": false }, "consent_marketing_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Consent Marketing At" }, "locale": { "type": "string", "title": "Locale", "description": "The language campaign emails reach them in: en, ar, or empty.", "default": "" }, "marketing_status": { "type": "string", "title": "Marketing Status", "description": "subscribed, not_subscribed, unsubscribed, bounced or complained.", "default": "not_subscribed" } }, "type": "object", "required": [ "id", "name", "email", "phone", "attributes", "verified", "source" ], "title": "Contact" }, "ContactEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/Contact" } }, "type": "object", "required": [ "data" ], "title": "ContactEnvelope" }, "ContactIn": { "properties": { "external_id": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "External Id", "description": "Your own id for this person. Unique in the workspace." }, "name": { "type": "string", "maxLength": 400, "title": "Name", "default": "" }, "email": { "type": "string", "maxLength": 400, "title": "Email", "default": "" }, "phone": { "type": "string", "maxLength": 200, "title": "Phone", "default": "" }, "attributes": { "additionalProperties": true, "type": "object", "title": "Attributes", "description": "A flat object: up to 20 keys (lower-case names), values of text (200 characters), numbers or booleans." }, "consent_marketing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Consent Marketing", "description": "True only when the person explicitly agreed to campaign emails from you; false withdraws it. A person who unsubscribed, bounced or complained is not given consent again; the rest of the contact is still saved." }, "locale": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Locale", "description": "The language campaign emails reach them in: en or ar (an empty string clears it)." } }, "additionalProperties": false, "type": "object", "title": "ContactIn" }, "ContactList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Contact" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ContactList" }, "ContactPatch": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ], "title": "Name" }, "email": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ], "title": "Email", "description": "An empty string clears it." }, "phone": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Phone", "description": "An empty string clears it." }, "attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Attributes", "description": "Merged by key; a null value removes its key." }, "consent_marketing": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Consent Marketing", "description": "True only when the person explicitly agreed to campaign emails from you; false withdraws it. A person who unsubscribed, bounced or complained cannot be given consent again (409 `conflict`, `marketing_suppressed`)." }, "locale": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ], "title": "Locale", "description": "The language campaign emails reach them in: en or ar (an empty string clears it)." } }, "additionalProperties": false, "type": "object", "title": "ContactPatch" }, "Conversation": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_id": { "type": "string", "title": "Agent Id" }, "channel": { "type": "string", "title": "Channel", "description": "website, hosted (the hosted chat page), api, email, slack or voice_web (a browser voice session). The same words as the dashboard's conversation log and the webhooks." }, "state": { "type": "string", "title": "State", "description": "ai_active, handoff_requested, human_active or closed." }, "started_at": { "type": "string", "title": "Started At" }, "last_message_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Message At" }, "expires_at": { "type": "string", "title": "Expires At" }, "lead_captured": { "type": "boolean", "title": "Lead Captured" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "page_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Page Url" }, "utm": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Utm", "description": "The campaign that brought the visitor: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content, as the first page of the visit carried them. Empty when there was none." }, "referrer": { "type": "string", "title": "Referrer", "description": "The site that sent the visitor (scheme, host and path, never the query string). Empty when there was none.", "default": "" } }, "type": "object", "required": [ "id", "agent_id", "channel", "state", "started_at", "expires_at", "lead_captured" ], "title": "Conversation" }, "ConversationEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/Conversation" } }, "type": "object", "required": [ "data" ], "title": "ConversationEnvelope" }, "ConversationList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Conversation" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "ConversationList" }, "KeyInfo": { "properties": { "id": { "type": "string", "title": "Id" }, "label": { "type": "string", "title": "Label" }, "prefix": { "type": "string", "title": "Prefix" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "agent_ids": { "items": { "type": "string" }, "type": "array", "title": "Agent Ids" }, "kind": { "type": "string", "title": "Kind", "description": "secret (bidi_sk_) or publishable (bidi_pk_, chat only).", "default": "secret" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "maker": { "anyOf": [ { "$ref": "#/components/schemas/KeyMaker" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "label", "prefix", "scopes", "agent_ids" ], "title": "KeyInfo" }, "KeyMaker": { "properties": { "state": { "type": "string", "title": "State", "description": "`full`: the key does everything it says. `limited`: its maker's role or assistants hold part of it back." }, "scopes_held_back": { "items": { "type": "string" }, "type": "array", "title": "Scopes Held Back", "description": "The key's scopes (with those they include) its maker's role no longer allows: a call that needs one answers 403 maker_role_limit." }, "agent_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Agent Ids", "description": "When its maker is kept to some agents: the agents the key reaches now (empty: none of the ones it names). Null: the agents the key names." } }, "type": "object", "required": [ "state" ], "title": "KeyMaker", "description": "A key follows the role of the teammate who made it, as it is now." }, "Lead": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "contact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact" }, "interest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interest" }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel" }, "status": { "type": "string", "title": "Status", "description": "new, qualified or closed." }, "data": { "additionalProperties": true, "type": "object", "title": "Data", "description": "The agent's lead fields and job details, by key." }, "notes": { "type": "string", "title": "Notes", "description": "The team's own notes on the lead.", "default": "" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "When the lead was last edited; null until it is." }, "utm": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Utm", "description": "The campaign that brought the visitor: any of utm_source, utm_medium, utm_campaign, utm_term and utm_content, as the first page of the visit carried them. Empty when there was none. Read from the lead's conversation." }, "referrer": { "type": "string", "title": "Referrer", "description": "The site that sent the visitor (scheme, host and path, never the query string). Empty when there was none. Read from the lead's conversation.", "default": "" } }, "type": "object", "required": [ "id", "status", "created_at" ], "title": "Lead" }, "LeadChanges": { "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "new", "qualified", "closed" ] }, { "type": "null" } ], "title": "Status" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "contact": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact" }, "interest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interest" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "data": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Data" } }, "additionalProperties": false, "type": "object", "title": "LeadChanges", "description": "What an owner (or an API key) may change on a lead. Every field is\noptional; at least one must be sent. `data` merges into the lead's\ncustom fields: a null or empty value removes that key." }, "LeadEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/Lead" } }, "type": "object", "required": [ "data" ], "title": "LeadEnvelope" }, "LeadField": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_id": { "type": "string", "title": "Agent Id" }, "key": { "type": "string", "title": "Key", "description": "The name the value is stored under in a lead's data." }, "label_en": { "type": "string", "title": "Label En" }, "label_ar": { "type": "string", "title": "Label Ar", "description": "The Arabic label; empty when the owner gave none." }, "kind": { "type": "string", "title": "Kind", "description": "text, email, phone, number, date or select." }, "options": { "items": { "type": "string" }, "type": "array", "title": "Options", "description": "The choices of a select field." }, "required": { "type": "boolean", "title": "Required" }, "ask_when": { "type": "string", "title": "Ask When", "description": "always or if_missing." }, "position": { "type": "integer", "title": "Position" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "agent_id", "key", "label_en", "label_ar", "kind", "options", "required", "ask_when", "position" ], "title": "LeadField" }, "LeadFieldList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LeadField" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "LeadFieldList" }, "LeadList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Lead" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "LeadList" }, "Me": { "properties": { "api_version": { "type": "string", "title": "Api Version" }, "key": { "$ref": "#/components/schemas/KeyInfo" }, "workspace": { "$ref": "#/components/schemas/WorkspaceInfo" } }, "type": "object", "required": [ "api_version", "key", "workspace" ], "title": "Me" }, "Message": { "properties": { "id": { "type": "string", "title": "Id" }, "role": { "type": "string", "title": "Role", "description": "user or assistant." }, "content": { "type": "string", "title": "Content" }, "actor_type": { "type": "string", "title": "Actor Type", "description": "visitor, ai or owner (a person on the team replied)." }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome", "description": "What the turn came to, on AI answers." }, "refused": { "type": "boolean", "title": "Refused" }, "sources": { "items": {}, "type": "array", "title": "Sources", "description": "The knowledge behind an AI answer." }, "blocks": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Blocks", "description": "The widgets an answer carried (a form, open times, options, a status card, products, links), each as the widget draws it; null for a plain message." }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lang" }, "feedback": { "anyOf": [ {}, { "type": "null" } ], "title": "Feedback" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "role", "content", "actor_type", "refused", "sources", "created_at" ], "title": "Message" }, "MessageList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Message" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "MessageList" }, "QuestionIn": { "properties": { "question": { "type": "string", "maxLength": 2000, "title": "Question", "description": "The question as a customer asks it (3 to 300 characters)." }, "variations": { "items": { "type": "string" }, "type": "array", "maxItems": 50, "title": "Variations", "description": "Other ways of asking the same thing (up to 10)." }, "answer": { "type": "string", "maxLength": 20000, "title": "Answer", "description": "The answer a customer should get (3 to 2000 characters)." } }, "additionalProperties": false, "type": "object", "required": [ "question", "answer" ], "title": "QuestionIn" }, "QuestionsIn": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name", "description": "A label for this batch. Sending the same name again replaces the batch." }, "items": { "items": { "$ref": "#/components/schemas/QuestionIn" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "name", "items" ], "title": "QuestionsIn" }, "Source": { "properties": { "id": { "type": "string", "title": "Id" }, "type": { "type": "string", "title": "Type", "description": "text, file, website, sheet, qa_bulk, faq or research." }, "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status", "description": "uploaded, crawling, parsing, chunking, embedding, indexed or failed." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size Bytes" }, "pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pages" }, "chunk_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Chunk Count" }, "extracted_chars": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Extracted Chars", "description": "Characters of text read from the source at its last indexing: what it counts toward the plan's text per agent. 0 until it is indexed." }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version", "description": "1 when created; +1 each time the source is re-saved." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url" }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Sha256", "description": "For a text source: the SHA-256 (hex) of its stored text in UTF-8, so a client can tell whether its copy differs without downloading it. null for other kinds." }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "type", "name", "status", "created_at", "updated_at" ], "title": "Source" }, "SourceContent": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "type": { "type": "string", "title": "Type", "description": "Always text." }, "text": { "type": "string", "title": "Text", "description": "The stored text, as sent (trimmed). Data written for the agent to read." }, "content_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Sha256", "description": "The SHA-256 (hex) of `text` in UTF-8." }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version" } }, "type": "object", "required": [ "id", "name", "type", "text" ], "title": "SourceContent" }, "SourceContentEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/SourceContent" } }, "type": "object", "required": [ "data" ], "title": "SourceContentEnvelope" }, "SourceEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/Source" } }, "type": "object", "required": [ "data" ], "title": "SourceEnvelope" }, "SourceIn": { "properties": { "type": { "type": "string", "enum": [ "text", "sheet" ], "title": "Type", "description": "`text`: content you send in `text`. `sheet`: a Google Sheet published as CSV, by `url`. Files and websites come from the dashboard." }, "name": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "A label, such as 'Opening hours'. Required for `text`." }, "text": { "anyOf": [ { "type": "string", "maxLength": 400000, "minLength": 1 }, { "type": "null" } ], "title": "Text", "description": "For `text`: what the agent should know, in any language. Markdown headings are kept." }, "url": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 1 }, { "type": "null" } ], "title": "Url", "description": "For `sheet`: the Google Sheets link (File > Share > Publish to web)." } }, "additionalProperties": false, "type": "object", "required": [ "type" ], "title": "SourceIn" }, "SourceList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Source" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "SourceList" }, "SourcePatch": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "A new label; omit to keep it." }, "text": { "type": "string", "maxLength": 400000, "minLength": 1, "title": "Text", "description": "The whole new text of the source." } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "SourcePatch" }, "SubmissionAction": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "SubmissionAction" }, "SubmissionList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SubmissionOut" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "SubmissionList" }, "SubmissionOut": { "properties": { "id": { "type": "string", "title": "Id" }, "action": { "$ref": "#/components/schemas/SubmissionAction" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "data": { "additionalProperties": true, "type": "object", "title": "Data" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "action", "data", "created_at" ], "title": "SubmissionOut" }, "Ticket": { "properties": { "id": { "type": "string", "title": "Id" }, "agent_id": { "type": "string", "title": "Agent Id" }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Conversation Id" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Id" }, "status": { "type": "string", "title": "Status", "description": "new (nobody has replied), on_you (the customer wrote last), on_customer (the team wrote last), on_hold or closed." }, "priority": { "type": "string", "title": "Priority", "description": "low, normal or high." }, "assignee_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee User Id", "description": "The member who has it; null for nobody." }, "team_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Team Id" }, "subject": { "type": "string", "title": "Subject" }, "channel": { "type": "string", "title": "Channel", "description": "The conversation's channel when the ticket opened: website, hosted, api, email, slack or voice_web." }, "language": { "type": "string", "title": "Language", "description": "The visitor's language: en or ar." }, "source": { "type": "string", "title": "Source", "description": "What opened it: handoff, or conversation (the every-conversation option)." }, "custom": { "additionalProperties": true, "type": "object", "title": "Custom", "description": "The workspace's ticket fields, by key." }, "tags": { "items": { "type": "string" }, "type": "array", "title": "Tags", "description": "The tags the workspace's helpdesk rules set on it." }, "handoff_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Handoff At", "description": "When a person was last asked in." }, "first_response_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Response At" }, "first_response_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Response Seconds", "description": "From the handoff (or the ticket's start) to the first reply by a person." }, "last_customer_message_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Customer Message At" }, "last_agent_message_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Agent Message At" }, "closed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Closed At" }, "closed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Closed By", "description": "The member who closed it; null when a key did." }, "resolution_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Resolution Seconds", "description": "From the ticket's start to its close." }, "csat_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Csat Score", "description": "The visitor's rating after the ticket closed: 1 good, -1 bad." }, "csat_comment": { "type": "string", "title": "Csat Comment", "description": "What the visitor added to the rating, if anything.", "default": "" }, "csat_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Csat At", "description": "When the visitor rated." }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "agent_id", "status", "priority", "subject", "channel", "language", "source", "created_at", "updated_at" ], "title": "Ticket" }, "TicketEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "type": "object", "required": [ "data" ], "title": "TicketEnvelope" }, "TicketList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Ticket" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "TicketList" }, "TicketPatch": { "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "open", "on_hold", "closed" ] }, { "type": "null" } ], "title": "Status", "description": "on_hold holds it, closed closes it, open releases a hold or reopens." }, "priority": { "anyOf": [ { "type": "string", "enum": [ "low", "normal", "high" ] }, { "type": "null" } ], "title": "Priority" }, "assignee_user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assignee User Id", "description": "A member who can answer on the ticket's agent; null gives it to nobody." }, "custom": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Custom", "description": "Merged into the ticket's fields by key; a null removes a key." } }, "additionalProperties": false, "type": "object", "title": "TicketPatch" }, "Usage": { "properties": { "month": { "type": "string", "title": "Month", "description": "The first day of the month, UTC." }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan" }, "conversations_per_agent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Conversations Per Agent", "description": "Deprecated name: the plan's monthly conversations, one pool for the whole workspace (see pool), not an allowance per agent." }, "pool": { "anyOf": [ { "$ref": "#/components/schemas/UsagePool" }, { "type": "null" } ] }, "agents": { "items": { "$ref": "#/components/schemas/AgentUsage" }, "type": "array", "title": "Agents" } }, "type": "object", "required": [ "month", "agents" ], "title": "Usage" }, "UsageConversations": { "properties": { "used": { "type": "integer", "title": "Used", "description": "Conversations this agent counted this month." }, "included": { "type": "integer", "title": "Included", "description": "The workspace's allowance this month: the plan's number plus this month's top-ups. One pool shared by every agent of the workspace." }, "extra": { "type": "integer", "title": "Extra", "description": "Top-ups bought on this agent this month (they add to the whole pool)." } }, "type": "object", "required": [ "used", "included", "extra" ], "title": "UsageConversations" }, "UsageEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/Usage" } }, "type": "object", "required": [ "data" ], "title": "UsageEnvelope" }, "UsagePool": { "properties": { "used": { "type": "integer", "title": "Used", "description": "Conversations every agent of the workspace counted this month." }, "included": { "type": "integer", "title": "Included", "description": "The plan's number plus this month's top-ups." }, "extra": { "type": "integer", "title": "Extra" } }, "type": "object", "required": [ "used", "included", "extra" ], "title": "UsagePool" }, "WebhookEndpoint": { "properties": { "id": { "type": "string", "title": "Id" }, "url": { "type": "string", "title": "Url" }, "events": { "items": { "type": "string" }, "type": "array", "title": "Events" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "The one agent it listens to; null for all." }, "enabled": { "type": "boolean", "title": "Enabled" }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Disabled Reason", "description": "Why it is off: failures (deliveries kept failing), owner (switched off in the dashboard), maker_left (paused when the teammate who made it left the workspace). null while it is on." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "description": { "type": "string", "title": "Description", "description": "A label for people, such as the app that subscribed.", "default": "" } }, "type": "object", "required": [ "id", "url", "events", "enabled" ], "title": "WebhookEndpoint" }, "WebhookEndpointCreated": { "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Secret", "description": "The signing secret for X-Bidi-Signature. Shown once, here: an Idempotency-Key replay answers null (it is never stored)." } }, "type": "object", "required": [ "data", "secret" ], "title": "WebhookEndpointCreated" }, "WebhookEndpointList": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "WebhookEndpointList" }, "WebhookIn": { "properties": { "url": { "type": "string", "maxLength": 2000, "title": "Url", "description": "Where events are POSTed: https, a public host, port 443 or 8443." }, "events": { "items": { "type": "string" }, "type": "array", "maxItems": 18, "minItems": 1, "title": "Events", "description": "The event types to send, by their D-3 names (lead.created, ticket.created, form.submitted, ...)." }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "Only this agent's events; omit for every agent. A key limited to some agents must name one of them." }, "description": { "type": "string", "maxLength": 120, "title": "Description", "description": "A label for people, such as \"Zapier: New lead\". Settings > Developers shows it.", "default": "" } }, "additionalProperties": false, "type": "object", "required": [ "url", "events" ], "title": "WebhookIn" }, "WorkspaceInfo": { "properties": { "id": { "type": "string", "title": "Id", "description": "The workspace's id: the same one webhook events carry as workspace_id." }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan" }, "conversations_per_agent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Conversations Per Agent" } }, "type": "object", "required": [ "id" ], "title": "WorkspaceInfo" }, "Error": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "description": "A stable snake_case code to switch on.", "examples": [ "rate_limited" ] }, "message": { "type": "string", "description": "A sentence for a person. English by default, Arabic with Accept-Language: ar." }, "request_id": { "type": "string", "description": "Quote it when you write to support." }, "details": { "type": "array", "items": { "type": "object" }, "description": "On validation_error, each field's problem; on conflict, why. Each item names its `field` and a `code`." }, "required_scope": { "type": "string" }, "required_plan": { "type": "string" }, "upgrade_url": { "type": "string" }, "plan": { "type": "string", "description": "On plan_text_limit: the workspace's plan." }, "limit_chars": { "type": "integer", "description": "On plan_text_limit: the plan's text per agent." }, "used_chars": { "type": "integer", "description": "On plan_text_limit: what the agent holds now." } } } } }, "ChatStreamDelta": { "properties": { "text": { "description": "The next piece of the answer, to append.", "title": "Text", "type": "string" } }, "required": [ "text" ], "title": "ChatStreamDelta", "type": "object" }, "ChatStreamSources": { "properties": { "sources": { "description": "The knowledge behind the answer.", "items": {}, "title": "Sources", "type": "array" } }, "required": [ "sources" ], "title": "ChatStreamSources", "type": "object" }, "ChatStreamOutcome": { "properties": { "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Outcome" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "refused": { "title": "Refused", "type": "boolean" }, "limit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "`monthly` when the month's conversations are used up.", "title": "Limit" } }, "required": [ "refused" ], "title": "ChatStreamOutcome", "type": "object" }, "ChatStreamClientTool": { "properties": { "call_id": { "description": "Send it back with the result on POST /agents/{agent_id}/chat/tool-results.", "title": "Call Id", "type": "string" }, "name": { "description": "The client tool the agent wants run, one of the names in `client_tools`.", "title": "Name", "type": "string" }, "args": { "additionalProperties": true, "description": "Its inputs, as the owner declared them.", "title": "Args", "type": "object" }, "timeout_ms": { "description": "Answer within this many milliseconds, or the agent is told it failed.", "title": "Timeout Ms", "type": "integer" }, "conversation_id": { "description": "The conversation to name in the answer (a first message has no id until `done`, so the call carries it).", "title": "Conversation Id", "type": "string" }, "conversation_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "With a publishable key: the conversation's token, to continue it later.", "title": "Conversation Token" } }, "required": [ "call_id", "name", "args", "timeout_ms", "conversation_id" ], "title": "ChatStreamClientTool", "type": "object" }, "ChatStreamError": { "properties": { "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Request Id" } }, "required": [ "code", "message" ], "title": "ChatStreamError", "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bidi_sk_<40 url-safe characters>", "description": "A workspace API key from Settings > Developers. A publishable key (bidi_pk_, for apps) reaches the Chat operations only." } } }, "tags": [ { "name": "Agents", "description": "Your live assistants: list, read and update the websites they answer on." }, { "name": "Sources", "description": "What an agent has read, and giving it text to read." }, { "name": "Chat", "description": "One guarded turn with an agent, plain JSON or streamed as server-sent events." }, { "name": "Conversations", "description": "What visitors and the API said, with outcomes and sources." }, { "name": "Leads", "description": "People who left their details, and where they stand." }, { "name": "Tickets", "description": "The helpdesk's tickets: whose move it is, who has it, and closing it." }, { "name": "Contacts", "description": "The people the workspace knows: their details, attributes and whether a host site verified them." }, { "name": "Actions", "description": "What an agent can do beyond answering (HTTP calls on verified hosts, forms, tools on your page) and what its forms gathered." }, { "name": "Usage", "description": "This month's conversations against the allowance." }, { "name": "Webhooks", "description": "Where events are delivered (managed in Settings > Developers)." }, { "name": "Account", "description": "The key you are calling with." } ], "security": [ { "bearerAuth": [] } ] }