{ "openapi": "3.1.0", "info": { "title": "Asks Public API", "version": "1.0.0", "description": "REST API for the Asks omnichannel support + AI agent platform.\n\nAuthenticate with an API key: `Authorization: Bearer ask_live_…`. Every request is scoped to the key's workspace — the workspace is never part of the URL.\n\n**Pagination** — list endpoints return `{ object: \"list\", data, has_more, next_cursor }`; page forward with `limit` (1–100, default 20) + `starting_after` (the previous page's `next_cursor`).\n**Idempotency** — send an `Idempotency-Key` header on POST requests; the first response is cached 24h and replays return `Idempotent-Replayed: true`.\n**Rate limits** — per key, per 60s: read 120, write 60, chat 20. Responses carry `RateLimit-*`; 429s carry `Retry-After`." }, "servers": [ { "url": "https://api.asks.app/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Agent", "description": "Talk to and configure the AI agent (the API channel)." }, { "name": "Conversations", "description": "Conversations and their messages." }, { "name": "Customers", "description": "Customer records (deduplicated across channels)." }, { "name": "Channels", "description": "Connected messaging channels." }, { "name": "Tickets", "description": "Support tickets (read-only)." }, { "name": "Knowledge Base", "description": "Knowledge base articles (read-only)." }, { "name": "Tags", "description": "Conversation tags." }, { "name": "Canned Responses", "description": "Saved reply templates (read-only)." }, { "name": "Webhook Endpoints", "description": "Manage webhook endpoints and inspect the event log." }, { "name": "Meta", "description": "Service and token context." } ], "paths": { "/": { "get": { "tags": [ "Meta" ], "summary": "Service info", "description": "Returns basic information about the API. Requires only a valid API key.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiRoot" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/me": { "get": { "tags": [ "Meta" ], "summary": "Get workspace & token context", "description": "Returns the workspace, environment, and scopes for the current API key.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceContext" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/agent/messages": { "post": { "tags": [ "Agent" ], "summary": "Send a message to the AI agent", "description": "Synchronous turn against the AI agent over the API channel. Omit `conversation_id` to start a new conversation. Consumes AI credits (essential=1, pro=4, ultra=8) only when a reply is produced.\n\n**Required scope:** `agent:chat`. Subject to the `chat` rate-limit tier (20/60s).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "description": "The customer's message." }, "conversation_id": { "type": "string", "description": "Continue an existing API-channel conversation. Omit to start a new one." }, "customer": { "$ref": "#/components/schemas/CustomerInput" }, "attachments": { "type": "array", "items": {}, "description": "Optional attachments passed to the agent." } } } } } }, "responses": { "200": { "description": "The agent's reply.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The workspace has no active plan (code `PLAN_LIMIT_REACHED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (code `insufficient_scope`), or AI credit limit reached (code `PLAN_LIMIT_REACHED`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The AI agent is disabled, or the API channel is not enabled for this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/agent": { "get": { "tags": [ "Agent" ], "summary": "Get agent configuration", "description": "Returns the AI agent configuration. If none is configured, a disabled default is returned (never 404).\n\n**Required scope:** `agent:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "patch": { "tags": [ "Agent" ], "summary": "Update agent configuration", "description": "Updates (and upserts) the agent configuration. Only provided fields change; `deployed_channels` is shallow-merged.\n\n**Required scope:** `agent:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "is_enabled": { "type": "boolean" }, "tone": { "type": "string", "enum": [ "professional", "friendly", "casual" ] }, "response_length": { "type": "string", "enum": [ "concise", "balanced", "detailed" ] }, "custom_instructions": { "type": [ "string", "null" ], "maxLength": 2000 }, "model_tier": { "type": "string", "enum": [ "essential", "pro", "ultra" ] }, "escalation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "keywords": { "type": "array", "items": { "type": "string" } }, "after_replies": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } } }, "deployed_channels": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agent/search": { "post": { "tags": [ "Agent" ], "summary": "Search the knowledge base", "description": "Semantic search over AI-enabled, published knowledge base content only. Returns an unpaginated list.\n\n**Required scope:** `agent:read`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1 }, "top_k": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } } } } } }, "responses": { "200": { "description": "Search results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeResult" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "description": "Cursor-paginated conversations, newest first.\n\n**Required scope:** `conversations:read`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "api", "widget", "whatsapp", "facebook", "instagram", "telegram" ] } }, { "name": "channel_id", "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Conversations" ], "summary": "Create a conversation", "description": "Creates a conversation. If `customer` info is provided, the customer is created or matched (cross-channel dedup).\n\n**Required scope:** `conversations:write`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "api", "widget", "whatsapp", "facebook", "instagram", "telegram" ], "default": "api" }, "customer": { "$ref": "#/components/schemas/CustomerInput" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/conversations/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Conversations" ], "summary": "Retrieve a conversation", "description": "**Required scope:** `conversations:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Conversations" ], "summary": "Update a conversation", "description": "Update status, priority, tags, or assignment. `assignee` accepts `\"ai\"`, a user id, or `null`.\n\n**Required scope:** `conversations:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "closed" ], "description": "`resolved` is accepted as a legacy alias for `closed`." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "assignee": { "type": [ "string", "null" ], "description": "`\"ai\"`, a user id, or `null` to unassign." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/conversations/{id}/messages": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Conversations" ], "summary": "List messages", "description": "Cursor-paginated messages, newest first.\n\n**Required scope:** `conversations:read`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Conversations" ], "summary": "Send a message", "description": "Posts an agent message into the conversation. Emits a `message.created` webhook.\n\n**Required scope:** `messages:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "minLength": 1 }, "attachments": { "type": "array", "items": {} }, "channel_metadata": { "type": "object", "additionalProperties": true }, "client_message_id": { "type": "string", "maxLength": 128, "description": "Your own id for client-side dedup." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Cursor-paginated customers, newest first.\n\n**Required scope:** `customers:read`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive match over name, email, and phone." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Customers" ], "summary": "Create or find a customer", "description": "Creates a customer, or returns the existing match. At least one of `email`, `phone`, or `external_id` is required.\n\n**Required scope:** `customers:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" } } } }, "responses": { "201": { "description": "Created or matched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/customers/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer", "description": "**Required scope:** `customers:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "**Required scope:** `customers:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/channels": { "get": { "tags": [ "Channels" ], "summary": "List channels", "description": "Lists connected channels (unpaginated). Sensitive config is never returned.\n\n**Required scope:** `channels:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/tickets": { "get": { "tags": [ "Tickets" ], "summary": "List tickets", "description": "Cursor-paginated tickets, newest first.\n\n**Required scope:** `tickets:read`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string" } }, { "name": "assignee_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/tickets/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Tickets" ], "summary": "Retrieve a ticket", "description": "**Required scope:** `tickets:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/knowledge_base/articles": { "get": { "tags": [ "Knowledge Base" ], "summary": "List knowledge base articles", "description": "Cursor-paginated articles, newest first.\n\n**Required scope:** `knowledge_base:read`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "public_article", "internal_article" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBaseArticle" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/knowledge_base/articles/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Knowledge Base" ], "summary": "Retrieve a knowledge base article", "description": "**Required scope:** `knowledge_base:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseArticle" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tags": { "get": { "tags": [ "Tags" ], "summary": "List tags", "description": "Lists all workspace tags (unpaginated), ordered by name.\n\n**Required scope:** `conversations:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Tags" ], "summary": "Create a tag", "description": "**Required scope:** `conversations:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A tag with that name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tags/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "patch": { "tags": [ "Tags" ], "summary": "Update a tag", "description": "**Required scope:** `conversations:write`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Tags" ], "summary": "Delete a tag", "description": "**Required scope:** `conversations:write`.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedTag" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/canned_responses": { "get": { "tags": [ "Canned Responses" ], "summary": "List canned responses", "description": "Cursor-paginated canned responses, newest first.\n\n**Required scope:** `conversations:read`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CannedResponse" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/canned_responses/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Canned Responses" ], "summary": "Retrieve a canned response", "description": "**Required scope:** `conversations:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CannedResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhook_endpoints": { "get": { "tags": [ "Webhook Endpoints" ], "summary": "List webhook endpoints", "description": "Lists all webhook endpoints (unpaginated). The signing secret is never returned.\n\n**Required scope:** `webhooks:manage`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Webhook Endpoints" ], "summary": "Create a webhook endpoint", "description": "Creates a webhook endpoint. The response includes the signing `secret` exactly once. The URL must be HTTPS and pass SSRF validation.\n\n**Required scope:** `webhooks:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "enabled_events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS URL to deliver events to." }, "description": { "type": "string", "maxLength": 500 }, "enabled_events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Event types to subscribe to, or `[\"*\"]` for all." } } } } } }, "responses": { "201": { "description": "Created (includes one-time `secret`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/webhook_endpoints/{id}": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Webhook Endpoints" ], "summary": "Retrieve a webhook endpoint", "description": "**Required scope:** `webhooks:manage`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Webhook Endpoints" ], "summary": "Update a webhook endpoint", "description": "Update URL, description, events, or status. Setting `status` to `enabled` clears the failure counter.\n\n**Required scope:** `webhooks:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "enabled_events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhook Endpoints" ], "summary": "Delete a webhook endpoint", "description": "**Required scope:** `webhooks:manage`.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedWebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhook_endpoints/{id}/roll_secret": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "Webhook Endpoints" ], "summary": "Roll the signing secret", "description": "Generates a new signing secret, returned once. The old secret stops working immediately.\n\n**Required scope:** `webhooks:manage`.", "responses": { "200": { "description": "OK (includes new one-time `secret`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhook_endpoints/{id}/test": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "post": { "tags": [ "Webhook Endpoints" ], "summary": "Send a test event", "description": "Enqueues a synthetic `ping` event to this endpoint.\n\n**Required scope:** `webhooks:manage`.", "responses": { "200": { "description": "Test event enqueued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string" }, "test_event_enqueued": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhook_endpoints/{id}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "get": { "tags": [ "Webhook Endpoints" ], "summary": "List deliveries", "description": "Cursor-paginated delivery attempts for this endpoint, newest first.\n\n**Required scope:** `webhooks:manage`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhook_endpoints/{id}/deliveries/{deliveryId}/retry": { "parameters": [ { "$ref": "#/components/parameters/IdPath" }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhook Endpoints" ], "summary": "Retry a delivery", "description": "Re-enqueues a previous delivery attempt.\n\n**Required scope:** `webhooks:manage`.", "responses": { "200": { "description": "Retry enqueued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "id": { "type": "string" }, "retry_enqueued": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/events": { "get": { "tags": [ "Webhook Endpoints" ], "summary": "List events", "description": "Cursor-paginated log of webhook events generated in the workspace, newest first.\n\n**Required scope:** `webhooks:manage`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Workspace API key. Format: `ask_live_…` (live) or `ask_test_…` (test). Pass as `Authorization: Bearer `. Scopes: *, read, write, conversations:read, conversations:write, messages:write, customers:read, customers:write, channels:read, tickets:read, tickets:write, knowledge_base:read, knowledge_base:write, agent:read, agent:write, agent:chat, webhooks:manage." } }, "parameters": { "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Page size (1–100)." }, "StartingAfter": { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor: the `id` of the last item from the previous page." } }, "responses": { "Unauthorized": { "description": "Missing, invalid, expired, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key lacks the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Invalid request body or parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded. See `Retry-After` and `RateLimit-*` headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ListEnvelope": { "type": "object", "description": "Cursor-paginated list wrapper.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ] }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "statusCode": { "type": "integer" }, "code": { "type": "string", "enum": [ "unauthorized", "insufficient_scope", "forbidden", "not_found", "validation_error", "rate_limited", "conflict", "PLAN_LIMIT_REACHED" ], "description": "Stable machine-readable code. Absent on schema-validation 400s. `PLAN_LIMIT_REACHED` = billing: 402 when the workspace has no active plan, 403 when a plan limit (e.g. AI credits) is reached." }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "message", "statusCode" ] } }, "required": [ "success", "error" ] }, "WebhookEventType": { "type": "string", "enum": [ "*", "conversation.created", "conversation.updated", "conversation.closed", "message.created", "customer.created", "customer.updated", "lead.captured", "ticket.created", "ticket.updated", "ticket.resolved", "sla.at_risk", "sla.breached", "agent.escalated" ] }, "CustomerInput": { "type": "object", "description": "Identifying info used to create or match a customer.", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": "string" } } }, "CustomerCreate": { "type": "object", "description": "At least one of `email`, `phone`, or `external_id` is required.", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "name": { "type": "string" }, "external_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "Conversation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation" ] }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "channel": { "type": "string", "enum": [ "api", "widget", "whatsapp", "facebook", "instagram", "telegram" ] }, "channel_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] }, "customer_name": { "type": [ "string", "null" ] }, "customer_email": { "type": [ "string", "null" ] }, "assignee": { "type": [ "string", "null" ], "description": "`\"ai\"`, `\"escalated\"`, a user id, or `null`." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "external_id": { "type": [ "string", "null" ] }, "is_pinned": { "type": "boolean" }, "resolution_type": { "type": [ "string", "null" ], "enum": [ "confirmed", "assumed", "unresolved", null ] }, "message_count": { "type": "integer" }, "custom_action_memory": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Values saved by Custom Actions during this conversation, keyed by memory name. `null` when nothing is saved." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Message": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "message" ] }, "id": { "type": "string" }, "conversation_id": { "type": "string" }, "ticket_id": { "type": [ "string", "null" ] }, "sender_type": { "type": "string", "enum": [ "customer", "agent", "ai" ] }, "sender_id": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "channel": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "attachments": { "type": [ "array", "null" ], "items": {} }, "is_read": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Channel": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "channel" ] }, "id": { "type": "string" }, "type": { "type": "string", "enum": [ "widget", "whatsapp", "facebook", "instagram", "telegram" ] }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "pending", "connected", "error", "disconnected" ] }, "last_connected_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error_message": { "type": [ "string", "null" ] }, "conversation_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Customer": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "customer" ] }, "id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "external_id": { "type": [ "string", "null" ] }, "conversation_count": { "type": "integer" }, "first_contact_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_contact_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Ticket": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "ticket" ] }, "id": { "type": "string" }, "number": { "type": "integer" }, "type": { "type": "string" }, "subject": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "priority": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "assignee_id": { "type": [ "string", "null" ] }, "team_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] }, "category_id": { "type": [ "string", "null" ] }, "source_conversation_id": { "type": [ "string", "null" ] }, "sla_status": { "type": [ "string", "null" ] }, "sla_policy_id": { "type": [ "string", "null" ] }, "first_response_at": { "type": [ "string", "null" ], "format": "date-time" }, "sla_first_response_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "sla_next_response_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "sla_resolution_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "summary": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Agent": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent" ] }, "name": { "type": "string" }, "avatar_url": { "type": [ "string", "null" ] }, "is_enabled": { "type": "boolean" }, "tone": { "type": "string", "enum": [ "professional", "friendly", "casual" ] }, "response_length": { "type": "string", "enum": [ "concise", "balanced", "detailed" ] }, "custom_instructions": { "type": [ "string", "null" ] }, "model_tier": { "type": "string", "enum": [ "essential", "pro", "ultra" ] }, "escalation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "keywords": { "type": "array", "items": { "type": "string" } }, "after_replies": { "type": [ "integer", "null" ] } } }, "deployed_channels": { "type": "object", "additionalProperties": { "type": "boolean" } } } }, "AgentResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent_response" ] }, "conversation_id": { "type": "string" }, "messages": { "type": "array", "items": { "type": "string" } }, "quick_replies": { "type": "array", "items": { "type": "string" } }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "url": { "type": "string" } } } }, "images": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Titles of the knowledge base content the reply cited." }, "escalated": { "type": "boolean" }, "credits_used": { "type": "integer" }, "model_tier": { "type": "string", "enum": [ "essential", "pro", "ultra" ] } } }, "KnowledgeResult": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_result" ] }, "knowledge_base_id": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] } } }, "KnowledgeBaseArticle": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_base_article" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "category": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "type": { "type": "string", "enum": [ "public_article", "internal_article" ] }, "is_public": { "type": "boolean" }, "ai_agent_enabled": { "type": "boolean" }, "indexed": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Tag": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "tag" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "DeletedTag": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "tag" ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } } }, "CannedResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "canned_response" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "content": { "type": "string" }, "shortcut": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "personal", "team", "workspace" ] }, "set_status": { "type": [ "string", "null" ] }, "set_priority": { "type": [ "string", "null" ] }, "add_tags": { "type": "array", "items": { "type": "string" } }, "usage_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabled_events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "consecutive_failures": { "type": "integer" }, "last_error_at": { "type": [ "string", "null" ], "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEndpointWithSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Signing secret (`whsec_…`). Shown once — store it now." } } } ] }, "DeletedWebhookEndpoint": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } } }, "WebhookDelivery": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "attempt_count": { "type": "integer" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Event": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "data": { "type": "object", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WorkspaceContext": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "workspace_context" ] }, "workspace": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "workspace" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "ApiRoot": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "api" ] }, "name": { "type": "string" }, "version": { "type": "string" }, "documentation_url": { "type": "string" } } } } } }