{ "openapi": "3.1.0", "info": { "title": "Vosy Voice AI Partner API", "version": "2.0.0", "description": "REST API (v2) for the Vosy Voice AI platform \u2014 manage agents, knowledge bases, campaigns, calls, telephony, schedules, webhooks, DNC, SMS, usage and API keys with scoped Bearer keys.\n\n**Auth:** send `Authorization: Bearer vosy_sk_...`. Each operation lists the scope(s) that authorize it (`x-required-scopes`).\n\n**Hosts:** `https://api.vosy.ai/v2` (primary; the vhost rewrites `/v2/*` to `/api/v2/*`) and `https://dashboard.vosy.ai/api/v2`.\n\n**Envelopes:** success responses are `{ \"success\": true, \"data\": ... }` (list endpoints add a `meta` pagination block). Router errors are `{ \"success\": false, \"error\": { \"message\", \"code\", \"details?\" } }`. Auth and rate-limit errors use `{ \"success\": false, \"error\": { \"code\", \"message\", \"retry_after?\" } }` (note the field order differs).\n\n**Correlation & rate limits:** every authed response carries `X-Request-ID` and `X-RateLimit-Limit/Remaining/Reset`; 429s add `Retry-After`. When a key is within 7 days of expiry, `X-API-Key-Expires-At` and `X-API-Key-Expires-In-Days` are returned.\n\n**Idempotency:** `POST /calls`, `POST /campaigns/{id}/start`, and `POST /campaigns/{id}/dial` honour an `Idempotency-Key` header (replayed ~24h with `Idempotency-Replayed: true`; a concurrent duplicate gets 409).", "contact": { "name": "Vosy", "url": "https://vosy.ai/contact" } }, "servers": [ { "url": "https://api.vosy.ai/v2", "description": "Primary API host" }, { "url": "https://dashboard.vosy.ai/api/v2", "description": "Dashboard-hosted API" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Meta", "description": "Health, discovery, and docs." }, { "name": "Agents", "description": "Voice agent lifecycle and configuration." }, { "name": "Knowledge Bases", "description": "Agent knowledge bases, documents, and ingestion. Read and write scopes are independent: `kb:write` does not imply `kb:read` \u2014 a key that both reads and writes must hold both scopes." }, { "name": "Calls", "description": "Public-API outbound call lifecycle (UUID-keyed)." }, { "name": "Call Logs", "description": "Read-only internal call logs (int-keyed)." }, { "name": "Campaigns", "description": "Outbound campaigns, contacts, and dialing." }, { "name": "Telephony", "description": "Providers, phone numbers, and telephony stats." }, { "name": "Schedules", "description": "Business hours schedules and exceptions." }, { "name": "Scheduling", "description": "In-house calendar: bookable calendars, availability rules & blackouts, open slots, and the full appointment lifecycle (book / reschedule / cancel / approve / decline / outcome) plus the read-only ICS feed." }, { "name": "Webhooks", "description": "Webhook subscriptions and delivery logs." }, { "name": "DNC", "description": "Do-Not-Call lists and screening." }, { "name": "SMS", "description": "Outbound SMS and message history." }, { "name": "Usage", "description": "Usage, quotas, and billing-period metrics." }, { "name": "API Keys", "description": "Manage the organization's API keys (enterprise plan)." }, { "name": "Leads", "description": "Inbound lead webhook ingestion for external automations (Zapier/Make/n8n) that queues an outbound AI call." }, { "name": "Triggers", "description": "Event-driven automation rules and their actions (webhook/email/SMS/Slack/flow/...)." }, { "name": "Organizations", "description": "Partner/reseller sub-organization management (only available to org_type=partner keys)." }, { "name": "Billing", "description": "Subscription, payment methods, and invoices (accept.blue). Dual auth: Bearer or dashboard session." }, { "name": "AWS", "description": "AWS service connectivity and credential status. Dual auth: Bearer or dashboard session." }, { "name": "Widget", "description": "Embeddable widget: mint short-lived widget tokens (Bearer) and drive campaigns with them (Widget token)." } ], "paths": { "/health": { "get": { "tags": [ "Meta" ], "operationId": "getHealth", "summary": "Health check", "description": "Liveness probe. No authentication required.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" }, "version": { "type": "string", "example": "2.0.0" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "security": [] } }, "/openapi.json": { "get": { "tags": [ "Meta" ], "operationId": "getOpenApiSpec", "summary": "This OpenAPI document", "description": "Returns this machine-readable OpenAPI 3.1 specification. In production the file is served statically by the web server; the API front controller serves it as a fallback. No authentication required.", "responses": { "200": { "description": "The OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [] } }, "/docs": { "get": { "tags": [ "Meta" ], "operationId": "getDocs", "summary": "Documentation redirect", "description": "302 redirect to the OpenAPI document (`/v2/openapi.json` on api.vosy.ai, `/api/v2/openapi.json` on dashboard.vosy.ai). No authentication required.", "responses": { "302": { "description": "Redirect to the OpenAPI document", "headers": { "Location": { "schema": { "type": "string" }, "description": "URL of the OpenAPI document" } } } }, "security": [] } }, "/agents": { "get": { "tags": [ "Agents" ], "operationId": "listAgents", "summary": "List agents", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "X-Sub-Org-Id", "in": "header", "required": false, "schema": { "type": "integer" }, "description": "Partner/reseller context switch: run the request against a sub-organization the authenticated partner account is the parent of. Requires an org_type=partner key." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] } }, { "name": "agent_mode", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:read", "agents:*", "*" ], "description": "Requires one of the following scopes: `agents:read`, `agents:*`, `*`. Holding any one authorizes." }, "post": { "tags": [ "Agents" ], "operationId": "createAgent", "summary": "Create an agent", "parameters": [ { "name": "X-Sub-Org-Id", "in": "header", "required": false, "schema": { "type": "integer" }, "description": "Partner/reseller context switch: run the request against a sub-organization the authenticated partner account is the parent of. Requires an org_type=partner key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreate" } } } }, "responses": { "201": { "description": "Agent created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Agent" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:write", "agents:*", "*" ], "description": "Requires one of the following scopes: `agents:write`, `agents:*`, `*`." } }, "/agents/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" } ], "get": { "tags": [ "Agents" ], "operationId": "getAgent", "summary": "Get an agent", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Agent" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:read", "agents:*", "*" ], "description": "Requires one of the following scopes: `agents:read`, `agents:*`, `*`." }, "patch": { "tags": [ "Agents" ], "operationId": "updateAgent", "summary": "Update an agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Agent" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:write", "agents:*", "*" ], "description": "Requires one of the following scopes: `agents:write`, `agents:*`, `*`." }, "delete": { "tags": [ "Agents" ], "operationId": "deleteAgent", "summary": "Delete an agent", "responses": { "204": { "description": "Agent deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:delete", "agents:*", "*" ], "description": "Requires one of the following scopes: `agents:delete`, `agents:*`, `*`." } }, "/agents/{id}/publish": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" } ], "post": { "tags": [ "Agents" ], "operationId": "publishAgent", "summary": "Publish (activate) an agent", "description": "Activates the agent (status -> active). Attempts a best-effort version snapshot; `version` is null until the agent_versions DDL lands on prod.\n\nRequires one of the following scopes: `agents:write`, `agents:*`, `*`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "agent_id": { "type": "integer" }, "version": { "type": [ "integer", "null" ], "description": "null until versioning DDL is deployed" }, "status": { "type": "string", "enum": [ "active" ] }, "published_at": { "type": "string", "format": "date-time" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:write", "agents:*", "*" ] } }, "/agents/{id}/duplicate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" } ], "post": { "tags": [ "Agents" ], "operationId": "duplicateAgent", "summary": "Duplicate an agent", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the copy (defaults to ' (Copy)')" } } } } } }, "responses": { "201": { "description": "Agent duplicated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Agent" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:write", "agents:*", "*" ], "description": "Requires one of the following scopes: `agents:write`, `agents:*`, `*`." } }, "/agents/{id}/versions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" } ], "get": { "tags": [ "Agents" ], "operationId": "listAgentVersions", "summary": "List agent versions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": [ "integer", "null" ] } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:read", "agents:*", "*" ], "description": "Requires one of the following scopes: `agents:read`, `agents:*`, `*`." } }, "/agents/{id}/knowledge-bases": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" } ], "get": { "tags": [ "Agents", "Knowledge Bases" ], "operationId": "listAgentKnowledgeBases", "summary": "List knowledge bases attached to an agent", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "knowledge_bases": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } }, "count": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:read", "kb:*", "*" ], "description": "Requires one of the following scopes: `kb:read`, `kb:*`, `*`." }, "post": { "tags": [ "Agents", "Knowledge Bases" ], "operationId": "attachKnowledgeBaseToAgent", "summary": "Attach a knowledge base to an agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "knowledge_base_id" ], "properties": { "knowledge_base_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "agent_id": { "type": "integer" }, "knowledge_bases": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write", "kb:*", "*" ], "description": "Requires one of the following scopes: `kb:write`, `kb:*`, `*`." } }, "/agents/{id}/knowledge-bases/{kbId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" }, { "name": "kbId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" } ], "delete": { "tags": [ "Agents", "Knowledge Bases" ], "operationId": "detachKnowledgeBaseFromAgent", "summary": "Detach a knowledge base from an agent", "responses": { "204": { "description": "Detached" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write", "kb:*", "*" ], "description": "Requires one of the following scopes: `kb:write`, `kb:*`, `*`." } }, "/knowledge-bases": { "get": { "tags": [ "Knowledge Bases" ], "operationId": "listKnowledgeBases", "summary": "List knowledge bases for an agent", "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Owning agent id (required)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "knowledge_bases": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } }, "count": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:read" ], "description": "Requires one of the following scopes: `kb:read`." }, "post": { "tags": [ "Knowledge Bases" ], "operationId": "createKnowledgeBase", "summary": "Create a knowledge base", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseCreate" } } } }, "responses": { "201": { "description": "Knowledge base created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/KnowledgeBaseWithAgents" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ], "description": "Requires one of the following scopes: `kb:write`. A 403 is returned when the plan's max_knowledge_bases limit is reached." } }, "/knowledge-bases/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" } ], "get": { "tags": [ "Knowledge Bases" ], "operationId": "getKnowledgeBase", "summary": "Get a knowledge base", "parameters": [ { "name": "with_documents", "in": "query", "schema": { "type": "string", "enum": [ "true" ] }, "description": "Set to `true` to include the documents array." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/KnowledgeBaseWithAgents" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:read" ], "description": "Requires one of the following scopes: `kb:read`." }, "patch": { "tags": [ "Knowledge Bases" ], "operationId": "updateKnowledgeBase", "summary": "Update a knowledge base", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/KnowledgeBaseWithAgents" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ], "description": "Requires one of the following scopes: `kb:write`." }, "delete": { "tags": [ "Knowledge Bases" ], "operationId": "deleteKnowledgeBase", "summary": "Delete a knowledge base", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ], "description": "Requires one of the following scopes: `kb:write`." } }, "/knowledge-bases/{id}/documents": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" } ], "get": { "tags": [ "Knowledge Bases" ], "operationId": "listKnowledgeBaseDocuments", "summary": "List documents", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "file_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBaseDocument" } }, "count": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:read" ], "description": "Requires one of the following scopes: `kb:read`." }, "post": { "tags": [ "Knowledge Bases" ], "operationId": "uploadKnowledgeBaseDocuments", "summary": "Upload document file(s)", "description": "Multipart upload. Send one or more files under the `files` field (array) or a single `file` field. Max 10 MB per request (API_MAX_UPLOAD_SIZE).\n\nRequires one of the following scopes: `kb:write`.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" } }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "At least one file ingested (per-file detail in body)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "success": { "type": "integer" }, "failed": { "type": "integer" } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string" }, "success": { "type": "boolean" }, "document_id": { "type": [ "integer", "null" ] }, "error": { "type": "string" } } } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "description": "All uploads failed (per-file reasons in error.details) or no files provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ] } }, "/knowledge-bases/{id}/documents/{docId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Document id" } ], "delete": { "tags": [ "Knowledge Bases" ], "operationId": "deleteKnowledgeBaseDocument", "summary": "Delete a document", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ], "description": "Requires one of the following scopes: `kb:write`." } }, "/knowledge-bases/{id}/scrape": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" } ], "post": { "tags": [ "Knowledge Bases" ], "operationId": "scrapeKnowledgeBaseUrl", "summary": "Scrape a URL into the KB", "description": "Fetches and ingests a public web page. SSRF-guarded (private/reserved IPs rejected).\n\nRequires one of the following scopes: `kb:write`. 400 = bad URL / SSRF-blocked, 409 = duplicate document, 502 = fetch failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "Page ingested", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "document_id": { "type": "integer" }, "page_title": { "type": "string" }, "text_length": { "type": "integer" }, "url": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/BadGateway" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ] } }, "/knowledge-bases/{id}/sync": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" } ], "post": { "tags": [ "Knowledge Bases" ], "operationId": "syncKnowledgeBase", "summary": "Trigger a KB sync", "responses": { "202": { "description": "Sync accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "knowledge_base_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "syncing" ] }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ], "description": "Requires one of the following scopes: `kb:write`." } }, "/knowledge-bases/{id}/agents": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" } ], "post": { "tags": [ "Knowledge Bases" ], "operationId": "attachAgentToKnowledgeBase", "summary": "Attach an agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "knowledge_base_id": { "type": "integer" }, "assigned_agents": { "type": "array", "items": { "$ref": "#/components/schemas/AssignedAgent" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ], "description": "Requires one of the following scopes: `kb:write`." } }, "/knowledge-bases/{id}/agents/{agentId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Knowledge base id" }, { "name": "agentId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" } ], "delete": { "tags": [ "Knowledge Bases" ], "operationId": "detachAgentFromKnowledgeBase", "summary": "Detach an agent", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "knowledge_base_id": { "type": "integer" }, "assigned_agents": { "type": "array", "items": { "$ref": "#/components/schemas/AssignedAgent" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "kb:write" ], "description": "Requires one of the following scopes: `kb:write`." } }, "/calls": { "post": { "tags": [ "Calls" ], "operationId": "scheduleCall", "summary": "Schedule an outbound call", "description": "Queues an outbound voice call for a configured bot. Returns 202 with the call UUID. `callback_url` is required only when the API key has webhooks enabled; polling-mode keys may omit it and poll `GET /calls/{id}`.\n\nRequires one of the following scopes: `calls:schedule`. DNC-listed destinations return 403.\n\n**Questions.** Pass the call's question set as `custom_data.questions` (see `CallQuestion`). It is validated here rather than silently dropped at call time, so a malformed set returns 400 with one of `invalid_questions_format`, `invalid_question_entry`, or `duplicate_question_key`.\n\nAn agent whose Questions tab is set to `API` treats the call request as the only source of questions — it never falls back to a saved or packaged set. Scheduling one of its calls without questions therefore returns 400 `questions_required` rather than running a default script. A per-call `custom_data.question_source` (`console` | `api`) overrides the agent's setting for that call.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Replays the original response for a repeated logical operation (remembered ~24h)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallSchedule" } } } }, "responses": { "202": { "description": "Call accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CallJob" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:schedule" ] }, "get": { "tags": [ "Calls" ], "operationId": "listCalls", "summary": "List scheduled/completed calls", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "queued", "dialing", "connected", "completed", "failed", "cancelled" ] } }, { "name": "bot_id", "in": "query", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "schema": { "type": "string" } }, { "name": "to_date", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "scheduled_at", "completed_at", "status" ], "default": "created_at" } }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/CallJobSummary" } }, "pagination": { "$ref": "#/components/schemas/OffsetPagination" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:read" ], "description": "Requires one of the following scopes: `calls:read`." } }, "/calls/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call UUID" } ], "get": { "tags": [ "Calls" ], "operationId": "getCall", "summary": "Get call status + result", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CallJobDetail" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:read" ], "description": "Requires one of the following scopes: `calls:read`." }, "delete": { "tags": [ "Calls" ], "operationId": "cancelCall", "summary": "Cancel a pending/queued call", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "description": "Call is not cancellable (already dialing/completed) or bad UUID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:cancel" ], "description": "Requires one of the following scopes: `calls:cancel`." } }, "/call-logs": { "get": { "tags": [ "Call Logs" ], "operationId": "listCallLogs", "summary": "List call logs", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } }, { "name": "direction", "in": "query", "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "schema": { "type": "string" } }, { "name": "to_date", "in": "query", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "schema": { "type": "string" } }, { "name": "has_recording", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CallLog" } }, "pagination": { "$ref": "#/components/schemas/PagePagination" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:read" ], "description": "Requires one of the following scopes: `calls:read`." } }, "/call-logs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Call log id" } ], "get": { "tags": [ "Call Logs" ], "operationId": "getCallLog", "summary": "Get a call log", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CallLog" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:read" ], "description": "Requires one of the following scopes: `calls:read`." } }, "/call-logs/{id}/recording": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Call log id" } ], "get": { "tags": [ "Call Logs" ], "operationId": "getCallLogRecording", "summary": "Get recording URL", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "call_id": { "type": "integer" }, "available": { "type": "boolean" }, "recording_status": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "file_size_bytes": { "type": [ "integer", "null" ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:recordings" ], "description": "Requires one of the following scopes: `calls:recordings`." } }, "/call-logs/{id}/transcript": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Call log id" } ], "get": { "tags": [ "Call Logs" ], "operationId": "getCallLogTranscript", "summary": "Get transcript", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "call_id": { "type": "integer" }, "has_transcript": { "type": "boolean" }, "transcript": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "sentiment_score": { "type": [ "number", "null" ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "calls:read" ], "description": "Requires one of the following scopes: `calls:read`." } }, "/campaigns": { "get": { "tags": [ "Campaigns" ], "operationId": "listCampaigns", "summary": "List campaigns", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:read" ], "description": "Requires one of the following scopes: `campaigns:read`." }, "post": { "tags": [ "Campaigns" ], "operationId": "createCampaign", "summary": "Create a campaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCreate" } } } }, "responses": { "201": { "description": "Campaign created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Campaign" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:write" ], "description": "Requires one of the following scopes: `campaigns:write`." } }, "/campaigns/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "get": { "tags": [ "Campaigns" ], "operationId": "getCampaign", "summary": "Get a campaign", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Campaign" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:read" ], "description": "Requires one of the following scopes: `campaigns:read`." }, "patch": { "tags": [ "Campaigns" ], "operationId": "updateCampaign", "summary": "Update a campaign", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Campaign" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:write" ], "description": "Requires one of the following scopes: `campaigns:write`." }, "delete": { "tags": [ "Campaigns" ], "operationId": "deleteCampaign", "summary": "Delete a campaign", "description": "Soft-deletes a campaign. Running or paused campaigns must be stopped first (400).\n\nRequires one of the following scopes: `campaigns:delete`.", "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:delete" ] } }, "/campaigns/{id}/start": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "post": { "tags": [ "Campaigns" ], "operationId": "startCampaign", "summary": "Start a campaign", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "description": "A request with this Idempotency-Key is still being processed (code IDEMPOTENCY_CONFLICT). Retry after the original completes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:execute" ], "description": "Requires one of the following scopes: `campaigns:execute`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Replays the original response for a repeated logical operation (remembered ~24h)." } ] } }, "/campaigns/{id}/pause": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "post": { "tags": [ "Campaigns" ], "operationId": "pauseCampaign", "summary": "Pause a campaign", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:execute" ], "description": "Requires one of the following scopes: `campaigns:execute`." } }, "/campaigns/{id}/stop": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "post": { "tags": [ "Campaigns" ], "operationId": "stopCampaign", "summary": "Stop a campaign", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:execute" ], "description": "Requires one of the following scopes: `campaigns:execute`." } }, "/campaigns/{id}/stats": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "get": { "tags": [ "Campaigns" ], "operationId": "getCampaignStats", "summary": "Campaign statistics", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CampaignStats" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:read" ], "description": "Requires one of the following scopes: `campaigns:read`." } }, "/campaigns/{id}/dial": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "post": { "tags": [ "Campaigns" ], "operationId": "dialCampaign", "summary": "Add contacts and start dialing (one action)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DialRequest" } } } }, "responses": { "201": { "description": "Contacts added (200 if none added)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/Campaign" }, "contacts_added": { "type": "integer" }, "contacts_failed": { "type": "integer" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactResult" } }, "campaign_started": { "type": "boolean" }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "description": "A request with this Idempotency-Key is still being processed (code IDEMPOTENCY_CONFLICT). Retry after the original completes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:execute" ], "description": "Requires one of the following scopes: `campaigns:execute`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Replays the original response for a repeated logical operation (remembered ~24h)." } ] } }, "/campaigns/{id}/contacts": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "get": { "tags": [ "Campaigns" ], "operationId": "listCampaignContacts", "summary": "List contacts", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:read" ], "description": "Requires one of the following scopes: `campaigns:read`." }, "post": { "tags": [ "Campaigns" ], "operationId": "addCampaignContacts", "summary": "Add contacts (single or batch)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddContactsRequest" } } } }, "responses": { "201": { "description": "Contacts added (200 if some failed)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "added": { "type": "integer" }, "failed": { "type": "integer" }, "total": { "type": "integer" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactResult" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:write" ], "description": "Requires one of the following scopes: `campaigns:write`." } }, "/campaigns/{id}/contacts/{contactId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Contact id" } ], "get": { "tags": [ "Campaigns" ], "operationId": "getCampaignContact", "summary": "Get a contact", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Contact" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:read" ], "description": "Requires one of the following scopes: `campaigns:read`." }, "delete": { "tags": [ "Campaigns" ], "operationId": "deleteCampaignContact", "summary": "Remove a contact", "responses": { "204": { "description": "Removed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "campaigns:write" ], "description": "Requires one of the following scopes: `campaigns:write`." } }, "/telephony/providers": { "get": { "tags": [ "Telephony" ], "operationId": "listProviders", "summary": "List telephony providers", "parameters": [ { "name": "active_only", "in": "query", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TelephonyProvider" } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:read`, `telephony:manage`. These routes also accept an authenticated browser session." }, "post": { "tags": [ "Telephony" ], "operationId": "createProvider", "summary": "Create a provider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider_type", "display_name", "credentials" ], "properties": { "provider_type": { "type": "string" }, "display_name": { "type": "string" }, "credentials": { "type": "object", "additionalProperties": true }, "is_byoc": { "type": "boolean" }, "is_default": { "type": "boolean" }, "settings": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Provider created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TelephonyProvider" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. These routes also accept an authenticated browser session." } }, "/telephony/providers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Provider id" } ], "get": { "tags": [ "Telephony" ], "operationId": "getProvider", "summary": "Get a provider", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TelephonyProvider" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:read`, `telephony:manage`. These routes also accept an authenticated browser session." }, "patch": { "tags": [ "Telephony" ], "operationId": "updateProvider", "summary": "Update a provider", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string" }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" }, "credentials": { "type": "object", "additionalProperties": true }, "settings": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TelephonyProvider" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. These routes also accept an authenticated browser session." }, "delete": { "tags": [ "Telephony" ], "operationId": "deleteProvider", "summary": "Delete a provider", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:delete", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:delete`, `telephony:manage`. These routes also accept an authenticated browser session." } }, "/telephony/providers/{id}/test": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Provider id" } ], "post": { "tags": [ "Telephony" ], "operationId": "testProvider", "summary": "Test provider credentials", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "account_info": { "type": [ "object", "null" ] }, "validated_at": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "error_code": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. These routes also accept an authenticated browser session." } }, "/telephony/numbers": { "get": { "tags": [ "Telephony" ], "operationId": "listNumbers", "summary": "List phone numbers", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:read`, `telephony:manage`. These routes also accept an authenticated browser session." }, "post": { "tags": [ "Telephony" ], "operationId": "provisionNumber", "summary": "Provision a phone number", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string" }, "provider_id": { "type": "integer" }, "type": { "type": "string", "default": "local" }, "options": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Number provisioned", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumber" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. These routes also accept an authenticated browser session. 403 when the plan phone-number limit is reached." } }, "/telephony/numbers/search": { "post": { "tags": [ "Telephony" ], "operationId": "searchNumbers", "summary": "Search available numbers", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "country_code": { "type": "string", "default": "US" }, "area_code": { "type": "string" }, "contains": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "type": { "type": "string" }, "limit": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total_count": { "type": "integer" }, "providers": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. These routes also accept an authenticated browser session." } }, "/telephony/numbers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Phone number id" } ], "get": { "tags": [ "Telephony" ], "operationId": "getNumber", "summary": "Get a phone number", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumber" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:read`, `telephony:manage`. These routes also accept an authenticated browser session." }, "patch": { "tags": [ "Telephony" ], "operationId": "configureNumber", "summary": "Configure a phone number", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "caller_id_name": { "type": "string" }, "is_default": { "type": "boolean" }, "assigned_to_id": { "type": [ "integer", "null" ] }, "assigned_to_type": { "type": "string" }, "webhook_url": { "type": "string" }, "voice_enabled": { "type": "boolean" }, "sms_enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PhoneNumber" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. These routes also accept an authenticated browser session." }, "delete": { "tags": [ "Telephony" ], "operationId": "releaseNumber", "summary": "Release a phone number", "responses": { "204": { "description": "Released" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:delete", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:delete`, `telephony:manage`. These routes also accept an authenticated browser session." } }, "/telephony/stats": { "get": { "tags": [ "Telephony" ], "operationId": "getTelephonyStats", "summary": "Telephony stats", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "active_calls": { "type": "integer" }, "today": { "type": "object", "additionalProperties": true }, "phone_numbers": { "type": "integer" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "validated": { "type": "boolean" }, "active": { "type": "boolean" } } } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ], "description": "Requires one of the following scopes: `telephony:read`, `telephony:manage`. These routes also accept an authenticated browser session." } }, "/schedules": { "get": { "tags": [ "Schedules" ], "operationId": "listSchedules", "summary": "List business schedules", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:read" ], "description": "Requires one of the following scopes: `schedules:read`." }, "post": { "tags": [ "Schedules" ], "operationId": "createSchedule", "summary": "Create a schedule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleCreate" } } } }, "responses": { "201": { "description": "Schedule created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:write" ], "description": "Requires one of the following scopes: `schedules:write`." } }, "/schedules/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Schedule id" } ], "get": { "tags": [ "Schedules" ], "operationId": "getSchedule", "summary": "Get a schedule", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Schedule" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:read" ], "description": "Requires one of the following scopes: `schedules:read`." }, "patch": { "tags": [ "Schedules" ], "operationId": "updateSchedule", "summary": "Update a schedule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:write" ], "description": "Requires one of the following scopes: `schedules:write`." }, "delete": { "tags": [ "Schedules" ], "operationId": "deleteSchedule", "summary": "Delete a schedule", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:delete" ], "description": "Requires one of the following scopes: `schedules:delete`." } }, "/schedules/{id}/status": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Schedule id" } ], "get": { "tags": [ "Schedules" ], "operationId": "getScheduleStatus", "summary": "Get open/closed status", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true, "properties": { "schedule_id": { "type": "integer" }, "schedule_name": { "type": "string" }, "timezone": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:read" ], "description": "Requires one of the following scopes: `schedules:read`." } }, "/schedules/{id}/exceptions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Schedule id" } ], "get": { "tags": [ "Schedules" ], "operationId": "listScheduleExceptions", "summary": "List exceptions", "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "exceptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:read" ], "description": "Requires one of the following scopes: `schedules:read`." }, "post": { "tags": [ "Schedules" ], "operationId": "addScheduleException", "summary": "Add an exception", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "201": { "description": "Exception added", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:write" ], "description": "Requires one of the following scopes: `schedules:write`." } }, "/schedules/{id}/exceptions/{eid}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Schedule id" }, { "name": "eid", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Exception id" } ], "delete": { "tags": [ "Schedules" ], "operationId": "removeScheduleException", "summary": "Remove an exception", "responses": { "204": { "description": "Removed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:delete" ], "description": "Requires one of the following scopes: `schedules:delete`." } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhook subscriptions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "disabled" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:read", "webhooks:manage" ], "description": "Requires one of the following scopes: `webhooks:read`, `webhooks:manage`." }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create a subscription", "description": "Registers a webhook endpoint. The signing `secret` is returned once, only on creation. URL is SSRF-validated.\n\nRequires one of the following scopes: `webhooks:write`, `webhooks:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "Subscription created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/WebhookWithSecret" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write", "webhooks:manage" ] } }, "/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id" } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhook", "summary": "Get a subscription", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Webhook" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:read", "webhooks:manage" ], "description": "Requires one of the following scopes: `webhooks:read`, `webhooks:manage`." }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "summary": "Update a subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Webhook" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write", "webhooks:manage" ], "description": "Requires one of the following scopes: `webhooks:write`, `webhooks:manage`." }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a subscription", "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:delete", "webhooks:manage" ], "description": "Requires one of the following scopes: `webhooks:delete`, `webhooks:manage`." } }, "/webhooks/{id}/test": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id" } ], "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Send a test event", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "status_code": { "type": [ "integer", "null" ] }, "response_time_ms": { "type": "integer" }, "error": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:write", "webhooks:manage" ], "description": "Requires one of the following scopes: `webhooks:write`, `webhooks:manage`." } }, "/webhooks/{id}/logs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id" } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookLogs", "summary": "Get delivery logs", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookLog" } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "webhooks:read", "webhooks:manage" ], "description": "Requires one of the following scopes: `webhooks:read`, `webhooks:manage`." } }, "/dnc": { "get": { "tags": [ "DNC" ], "operationId": "listDncEntries", "summary": "List DNC entries", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "list_id", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DncEntry" } }, "pagination": { "$ref": "#/components/schemas/PagePagination" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:read" ], "description": "Requires one of the following scopes: `dnc:read`." }, "post": { "tags": [ "DNC" ], "operationId": "addDncEntry", "summary": "Add a DNC entry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DncAdd" } } } }, "responses": { "201": { "description": "Entry added", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "409": { "$ref": "#/components/responses/Conflict" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:write" ], "description": "Requires one of the following scopes: `dnc:write`." } }, "/dnc/check": { "post": { "tags": [ "DNC" ], "operationId": "checkDnc", "summary": "Check a phone against DNC", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:read" ], "description": "Requires one of the following scopes: `dnc:read`. Fails closed: 503 when the external registry is unavailable." } }, "/dnc/bulk-add": { "post": { "tags": [ "DNC" ], "operationId": "bulkAddDnc", "summary": "Bulk add DNC entries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_numbers" ], "properties": { "phone_numbers": { "type": "array", "items": { "type": "string" }, "maxItems": 10000 }, "list_id": { "type": "integer" }, "reason": { "type": "string" }, "source_reference": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:write" ], "description": "Requires one of the following scopes: `dnc:write`." } }, "/dnc/lists": { "get": { "tags": [ "DNC" ], "operationId": "listDncLists", "summary": "List DNC lists", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:read" ], "description": "Requires one of the following scopes: `dnc:read`." }, "post": { "tags": [ "DNC" ], "operationId": "createDncList", "summary": "Create a DNC list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "default": "custom" } } } } } }, "responses": { "201": { "description": "List created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:write" ], "description": "Requires one of the following scopes: `dnc:write`." } }, "/dnc/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "DNC entry id" } ], "patch": { "tags": [ "DNC" ], "operationId": "updateDncEntry", "summary": "Update a DNC entry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "notes": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:write" ], "description": "Requires one of the following scopes: `dnc:write`." }, "delete": { "tags": [ "DNC" ], "operationId": "deleteDncEntry", "summary": "Remove a DNC entry", "responses": { "204": { "description": "Removed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:write" ], "description": "Requires one of the following scopes: `dnc:write`." } }, "/sms": { "get": { "tags": [ "SMS" ], "operationId": "listSms", "summary": "List SMS messages", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "outbound", "inbound" ] }, "description": "Filter by message direction. Omit to return both \u2014 the log is a two-way conversation history, not a send log. An unrecognised value is ignored rather than rejected." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "SMS is not included in this organization\u2019s plan, or the caller is not authorized for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "SMS is switched off platform-wide (`SMS_DISABLED`). The platform kill switch stays closed until A2P 10DLC brand registration completes; no SMS route responds while it is off, regardless of plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:read" ], "description": "Requires one of the following scopes: `sms:read`.\n\nReturns outbound and inbound messages together. Each item carries a `direction` field (`outbound` | `inbound`); inbound messages are stored `delivered` on receipt. Outbound messages suppressed by the opt-out register are stored with status `blocked` and never reach a carrier." } }, "/sms/send": { "post": { "tags": [ "SMS" ], "operationId": "sendSms", "summary": "Send an SMS", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "message" ], "properties": { "to": { "type": "string" }, "message": { "type": "string" }, "sender_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Message queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "to": { "type": "string" }, "status": { "type": "string" }, "provider": { "type": [ "string", "null" ], "enum": [ "telnyx", "sns", "none", null ], "description": "Carrier route the message actually took. `none` means the message was recorded but not transmitted." }, "provider_message_id": { "type": [ "string", "null" ], "description": "Provider-side message id, whichever provider handled the send. Prefer this over `sns_message_id`." }, "sns_message_id": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated \u2014 retained for callers written against the SNS-only era. It is `null` on every Telnyx send, which is now the only route. Read `provider_message_id` instead." }, "segments": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "SMS is not included in this organization\u2019s plan, or the caller is not authorized for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Recipient has opted out of messages from this organization. The message is recorded with status `blocked` and not transmitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "SMS is switched off platform-wide (`SMS_DISABLED`). The platform kill switch stays closed until A2P 10DLC brand registration completes; no SMS route responds while it is off, regardless of plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:write" ], "description": "Requires one of the following scopes: `sms:write`.\n\nSends are checked against the organization\u2019s opt-out register first. A recipient who has replied STOP is refused with `409 Conflict` and the message is recorded with status `blocked`; it is never handed to a carrier. Clearing that suppression is not possible over the API \u2014 see `POST /sms/opt-outs`." } }, "/sms/stats": { "get": { "tags": [ "SMS" ], "operationId": "getSmsStats", "summary": "SMS stats", "parameters": [ { "name": "date_from", "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "total_sent": { "type": "integer", "description": "Outbound messages handed to a carrier, regardless of delivery outcome. Excludes `blocked` messages and all inbound traffic." }, "total_delivered": { "type": "integer", "description": "Outbound messages confirmed delivered by the carrier." }, "total_failed": { "type": "integer", "description": "Outbound messages the carrier rejected or failed to deliver." }, "total_blocked": { "type": "integer", "description": "Outbound messages the platform refused to transmit because the recipient had opted out. Not a delivery failure." }, "total_received": { "type": "integer", "description": "Inbound messages received from contacts, including STOP, START and HELP replies." }, "total_segments": { "type": "integer", "description": "Billable segments. Outbound only \u2014 inbound messages are not billed." } }, "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "SMS is not included in this organization\u2019s plan, or the caller is not authorized for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "SMS is switched off platform-wide (`SMS_DISABLED`). The platform kill switch stays closed until A2P 10DLC brand registration completes; no SMS route responds while it is off, regardless of plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:read" ], "description": "Requires one of the following scopes: `sms:read`.\n\nAll counters are direction-scoped: sent/delivered/failed/blocked cover outbound traffic only, and inbound traffic is reported separately as `total_received`." } }, "/sms/opt-outs": { "get": { "tags": [ "SMS" ], "operationId": "listSmsOptOuts", "summary": "List SMS opt-outs", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "opted_out", "opted_in" ], "default": "opted_out" }, "description": "Defaults to `opted_out` \u2014 the suppressions, i.e. the records that change what the platform will do. Pass the parameter empty (`?status=`) to return opt-ins alongside them for a full audit trail." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "opt_outs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "phone_last_four": { "type": [ "string", "null" ], "description": "Last four digits only. The full number is stored encrypted and is never returned." }, "status": { "type": "string", "enum": [ "opted_out", "opted_in" ] }, "keyword": { "type": [ "string", "null" ], "description": "Keyword that triggered the record, e.g. `STOP`, `START`." }, "source": { "type": "string", "enum": [ "inbound_keyword", "api", "ui", "import", "carrier" ], "description": "How the record was created. `inbound_keyword` means the contact texted the keyword from their own handset." }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "opted_in_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "SMS is not included in this organization\u2019s plan, or the caller is not authorized for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "SMS is switched off platform-wide (`SMS_DISABLED`). The platform kill switch stays closed until A2P 10DLC brand registration completes; no SMS route responds while it is off, regardless of plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:read" ], "description": "Requires one of the following scopes: `sms:read`.\n\nThe organization\u2019s suppression register. Full phone numbers are stored encrypted and are never returned \u2014 entries expose the last four digits only." }, "post": { "tags": [ "SMS" ], "operationId": "createSmsOptOut", "summary": "Suppress a number", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "Recipient number in E.164 form, e.g. `+14155551234`. Anything that does not normalise to a plausible E.164 number is rejected with `400`, because a malformed entry would suppress nothing.", "example": "+14155551234" }, "keyword": { "type": "string", "maxLength": 32, "default": "STOP", "description": "Recorded for audit. Upper-cased and truncated to 32 characters." } } } } } }, "responses": { "201": { "description": "Number suppressed. Idempotent \u2014 re-suppressing an already-suppressed number succeeds.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "phone_last_four": { "type": "string" }, "status": { "type": "string", "enum": [ "opted_out" ] }, "keyword": { "type": "string" }, "source": { "type": "string", "enum": [ "api", "ui" ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "SMS is not included in this organization\u2019s plan, or the caller is not authorized for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "The suppression was not recorded (`OPT_OUT_NOT_RECORDED`). Treat as a failure and retry \u2014 the register does not hold the opt-out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "SMS is switched off platform-wide (`SMS_DISABLED`). The platform kill switch stays closed until A2P 10DLC brand registration completes; no SMS route responds while it is off, regardless of plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:write" ], "description": "Requires one of the following scopes: `sms:write`.\n\nHonours an opt-out that arrived somewhere other than an inbound STOP \u2014 a phone call, an email, a web form, an imported list. Idempotent.\n\nThere is deliberately no delete or opt-in operation. Clearing a suppression is the one direction that can put the platform back in touch with someone who said STOP, and an API caller cannot evidence the fresh consent that would make that lawful. Re-subscription happens only when the contact texts START from their own handset." } }, "/sms/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Message id" } ], "get": { "tags": [ "SMS" ], "operationId": "getSms", "summary": "Get a message", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "SMS is not included in this organization\u2019s plan, or the caller is not authorized for this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "SMS is switched off platform-wide (`SMS_DISABLED`). The platform kill switch stays closed until A2P 10DLC brand registration completes; no SMS route responds while it is off, regardless of plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:read" ], "description": "Requires one of the following scopes: `sms:read`." } }, "/usage": { "get": { "tags": [ "Usage" ], "operationId": "getUsage", "summary": "Current billing-period usage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/UsageSummary" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "usage:read" ], "description": "Requires one of the following scopes: `usage:read`." } }, "/usage/agents": { "get": { "tags": [ "Usage" ], "operationId": "getUsageByAgent", "summary": "Per-agent usage metrics", "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD (default 30 days ago)." }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD (default today)." }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } }, "agents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "summary": { "type": "object", "properties": { "total_agents": { "type": "integer" }, "total_calls": { "type": "integer" }, "total_minutes": { "type": "number" }, "avg_success_rate": { "type": "number" } } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "usage:read" ], "description": "Requires one of the following scopes: `usage:read`." } }, "/usage/history": { "get": { "tags": [ "Usage" ], "operationId": "getUsageHistory", "summary": "Historical usage", "parameters": [ { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD (default 30 days ago)." }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD (default today)." }, { "name": "group_by", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "day" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "group_by": { "type": "string" } } }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "totals": { "type": "object", "additionalProperties": true } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "usage:read" ], "description": "Requires one of the following scopes: `usage:read`. Date range capped at 365 days." } }, "/api-keys": { "get": { "tags": [ "API Keys" ], "operationId": "listApiKeys", "summary": "List API keys", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "include_inactive", "in": "query", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:read", "api-keys:manage" ], "description": "Requires one of the following scopes: `api-keys:read`, `api-keys:manage`. Enterprise plan only (403 otherwise)." }, "post": { "tags": [ "API Keys" ], "operationId": "createApiKey", "summary": "Create an API key", "description": "Creates a key. The full secret is returned once, only on creation. Requested scopes must be a subset of the caller key's scopes.\n\nRequires one of the following scopes: `api-keys:write`, `api-keys:manage`. Enterprise plan only (403 otherwise).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" } } } }, "responses": { "201": { "description": "Key created (secret shown once)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "key_id": { "type": "string" }, "key": { "type": "string" }, "key_prefix": { "type": "string" }, "name": { "type": "string" }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:write", "api-keys:manage" ] } }, "/api-keys/scopes": { "get": { "tags": [ "API Keys" ], "operationId": "listApiKeyScopes", "summary": "List available scopes and presets", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string" }, "description": { "type": "string" } } } }, "presets": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:read", "api-keys:manage" ], "description": "Requires one of the following scopes: `api-keys:read`, `api-keys:manage`. Enterprise plan only (403 otherwise)." } }, "/api-keys/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "API key id" } ], "get": { "tags": [ "API Keys" ], "operationId": "getApiKey", "summary": "Get an API key", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ApiKey" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:read", "api-keys:manage" ], "description": "Requires one of the following scopes: `api-keys:read`, `api-keys:manage`. Enterprise plan only (403 otherwise)." }, "patch": { "tags": [ "API Keys" ], "operationId": "updateApiKey", "summary": "Update key metadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/ApiKey" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:write", "api-keys:manage" ], "description": "Requires one of the following scopes: `api-keys:write`, `api-keys:manage`. Enterprise plan only (403 otherwise). Revoked keys cannot be modified (403)." }, "delete": { "tags": [ "API Keys" ], "operationId": "deleteApiKey", "summary": "Permanently delete a key", "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:delete", "api-keys:manage" ], "description": "Requires one of the following scopes: `api-keys:delete`, `api-keys:manage`. Enterprise plan only (403 otherwise)." } }, "/api-keys/{id}/revoke": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "API key id" } ], "post": { "tags": [ "API Keys" ], "operationId": "revokeApiKey", "summary": "Revoke (deactivate) a key", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:write", "api-keys:manage" ], "description": "Requires one of the following scopes: `api-keys:write`, `api-keys:manage`. Enterprise plan only (403 otherwise)." } }, "/api-keys/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "API key id" } ], "post": { "tags": [ "API Keys" ], "operationId": "rotateApiKey", "summary": "Rotate a key with grace period", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "grace_period_hours": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 } } } } } }, "responses": { "201": { "description": "Key rotated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "api-keys:write", "api-keys:manage" ], "description": "Requires one of the following scopes: `api-keys:write`, `api-keys:manage`. Enterprise plan only (403 otherwise)." } }, "/scheduling/calendars": { "get": { "tags": [ "Scheduling" ], "operationId": "listCalendars", "summary": "List bookable calendars", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "calendars" ], "properties": { "calendars": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:read" ], "description": "Requires one of the following scopes: `scheduling:read`." }, "post": { "tags": [ "Scheduling" ], "operationId": "createCalendar", "summary": "Create a calendar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarCreate" } } } }, "responses": { "201": { "description": "Calendar created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/calendars/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Calendar id" } ], "patch": { "tags": [ "Scheduling" ], "operationId": "updateCalendar", "summary": "Update a calendar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/rules": { "get": { "tags": [ "Scheduling" ], "operationId": "listAvailabilityRules", "summary": "List availability rules", "parameters": [ { "name": "calendar_id", "in": "query", "schema": { "type": "integer" } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "rules" ], "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityRule" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:read" ], "description": "Requires one of the following scopes: `scheduling:read`." }, "post": { "tags": [ "Scheduling" ], "operationId": "createAvailabilityRule", "summary": "Create an availability rule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityRuleCreate" } } } }, "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/rules/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Rule id" } ], "delete": { "tags": [ "Scheduling" ], "operationId": "deleteAvailabilityRule", "summary": "Delete an availability rule", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/exceptions": { "get": { "tags": [ "Scheduling" ], "operationId": "listAvailabilityExceptions", "summary": "List blackout exceptions", "parameters": [ { "name": "calendar_id", "in": "query", "schema": { "type": "integer" } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "exceptions" ], "properties": { "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityException" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:read" ], "description": "Requires one of the following scopes: `scheduling:read`." }, "post": { "tags": [ "Scheduling" ], "operationId": "createAvailabilityException", "summary": "Create a blackout exception", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityExceptionCreate" } } } }, "responses": { "201": { "description": "Blackout created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/exceptions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Exception id" } ], "delete": { "tags": [ "Scheduling" ], "operationId": "deleteAvailabilityException", "summary": "Delete a blackout exception", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/availability": { "get": { "tags": [ "Scheduling" ], "operationId": "getAvailability", "summary": "List open bookable slots", "parameters": [ { "name": "calendar_id", "in": "query", "schema": { "type": "integer" } }, { "name": "appointment_type_id", "in": "query", "schema": { "type": "integer" } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } }, { "name": "preferred_date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Limit to one local day (YYYY-MM-DD)." }, { "name": "time_of_day", "in": "query", "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "horizon_days", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AvailabilityResult" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:read" ], "description": "Requires one of the following scopes: `scheduling:read`." } }, "/scheduling/appointments": { "get": { "tags": [ "Scheduling" ], "operationId": "listAppointments", "summary": "List appointments", "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "upcoming", "past", "all" ], "default": "upcoming" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "confirmed", "cancelled", "completed", "no_show", "pending" ] } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive local-day lower bound (org tz)." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Inclusive local-day upper bound (org tz)." }, { "name": "contact_id", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "appointments": { "type": "array", "items": { "$ref": "#/components/schemas/Appointment" } }, "total": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:read" ], "description": "Requires one of the following scopes: `scheduling:read`." }, "post": { "tags": [ "Scheduling" ], "operationId": "createAppointment", "summary": "Book an appointment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCreate" } } } }, "responses": { "201": { "description": "Appointment booked (or held pending approval)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppointmentBooked" } } } } }, "headers": { "Location": { "description": "URL of the created appointment.", "schema": { "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict", "description": "The requested slot is unavailable (taken or outside availability), or the day has reached its bookings cap (day_full)." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/appointments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Appointment id" } ], "get": { "tags": [ "Scheduling" ], "operationId": "getAppointment", "summary": "Get one appointment", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Appointment" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:read" ], "description": "Requires one of the following scopes: `scheduling:read`." }, "patch": { "tags": [ "Scheduling" ], "operationId": "rescheduleAppointment", "summary": "Reschedule an appointment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentReschedule" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppointmentRescheduled" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict", "description": "The new slot is unavailable or the day has reached its bookings cap (day_full). Also returned when the target appointment is pending \u2014 pending requests are approved or declined, not rescheduled (use POST .../{id}/approve or /decline)." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." }, "delete": { "tags": [ "Scheduling" ], "operationId": "cancelAppointment", "summary": "Cancel an appointment", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppointmentCancelled" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "description": "The target appointment is pending \u2014 pending requests are approved or declined (use POST .../{id}/approve or /decline).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Requires one of the following scopes: `scheduling:write`." } }, "/scheduling/appointments/{id}/approve": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Appointment id" } ], "post": { "tags": [ "Scheduling" ], "operationId": "approveAppointment", "summary": "Approve a pending appointment", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppointmentApprovalResult" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Confirm a `pending` request. 409 if it is already handled / no longer pending. Requires the `scheduling:write` scope." } }, "/scheduling/appointments/{id}/decline": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Appointment id" } ], "post": { "tags": [ "Scheduling" ], "operationId": "declineAppointment", "summary": "Decline a pending appointment", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppointmentApprovalResult" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Reject a `pending` request and free the slot. 409 if it is already handled. Requires the `scheduling:write` scope." } }, "/scheduling/appointments/{id}/outcome": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Appointment id" } ], "post": { "tags": [ "Scheduling" ], "operationId": "markAppointmentOutcome", "summary": "Mark a past appointment outcome", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentOutcomeRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/AppointmentOutcomeResult" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:write" ], "description": "Record `completed` or `no_show` for a PAST confirmed appointment (feeds the show-rate). 409 if it is not a past confirmed appointment. Requires the `scheduling:write` scope." } }, "/scheduling/appointments/{id}/purge": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Appointment id" } ], "post": { "tags": [ "Scheduling" ], "operationId": "purgeAppointment", "summary": "Permanently erase an appointment record", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "appointment_id" ], "properties": { "appointment_id": { "type": "integer", "description": "Id of the row that was erased." } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:delete" ], "description": "Erase the appointment row itself. Irreversible, and deliberately narrow: only an appointment that is already finished with - `cancelled`, `completed` or `no_show` - can be erased. A live booking is refused with `not_deletable`, because deleting the row would hide the appointment without freeing the slot or telling the customer - cancel it first via `DELETE /scheduling/appointments/{id}`, which is `scheduling:write`.\n\nNo notification and no webhook are sent. Cancelling already fired `appointment.cancelled`; re-announcing the row's disappearance would only prompt integrations to undo work they have already done.\n\nEvery failure on this route answers **400**, not 404 - including an id that does not exist or belongs to another organization, which are deliberately indistinguishable (`not_found`). The reason travels in `error.message`, which carries the literal `not_found`, `not_deletable`, `invalid_request`, `delete_failed` or `unsupported_provider`; `error.code` is the constant `bad_request` on all five, so branching on it will not distinguish them. This is a deliberate exception to the platform rule under [Getting started](https://vosy.ai/developers/getting-started) - *branch on status and `code`, never on the message*. That rule holds everywhere else; here the five reasons share one code, so the message is the only discriminator. Treat those five literals as part of this route's contract rather than as human-facing prose: they will not be reworded without a version note.\n\nRequires the `scheduling:delete` scope, which `scheduling:write` does not grant. This is the only irreversible operation on the scheduling surface, so it carries its own scope: a key that books, reschedules and cancels still cannot erase the history of what it did." } }, "/scheduling/feed": { "get": { "tags": [ "Scheduling" ], "operationId": "getCalendarFeedStatus", "summary": "Get the calendar subscribe-feed status", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/CalendarFeedStatus" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "scheduling:read" ], "description": "Read-only status ({enabled,url}) of the org outbound ICS subscribe feed. Minting/rotating the secret stays panel-only. Requires the `scheduling:read` scope." } }, "/leads/inbound": { "post": { "tags": [ "Leads" ], "operationId": "ingestInboundLead", "summary": "Ingest an inbound lead", "description": "Receives a lead from an external automation, E.164- and DNC-screens the destination, inserts a queued call job, and dispatches a `lead.received` trigger. DNC-listed destinations are rejected up front (403). If DNC verification is unavailable the request fails closed (no job queued). Supports the `Idempotency-Key` (or `X-Idempotency-Key`) header \u2014 replays within 24h return the original job with `idempotent: true` (HTTP 200).\n\nRequires the `leads:inbound` scope.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Idempotency key (also accepted as X-Idempotency-Key); replays within 24h return the original result." }, { "name": "X-Sub-Org-Id", "in": "header", "required": false, "schema": { "type": "integer" }, "description": "Partner/reseller context switch: run the request against a sub-organization the authenticated partner account is the parent of. Requires an org_type=partner key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "agent_id" ], "properties": { "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "Destination in E.164 format." }, "agent_id": { "type": "integer", "description": "Active, deployed agent with a configured bot." }, "name": { "type": "string" }, "source": { "type": "string" }, "issue": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "default": "normal" }, "custom_fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Arbitrary key/values forwarded as call attributes (keys sanitized, max 50 chars each)." }, "scheduled_time": { "type": "string", "description": "When to place the call; parsed in time_zone. Defaults to immediate." }, "time_zone": { "type": "string", "default": "UTC" }, "callback_url": { "type": "string", "format": "uri", "description": "Optional result callback; SSRF-validated." }, "callback_secret": { "type": "string", "maxLength": 256, "description": "Shared secret used to HMAC-sign the result callback. Supplied PER REQUEST — it is not stored on your account, so it must be sent on every call. If `callback_url` is set and this is omitted, the callback is delivered UNSIGNED and the response carries a `meta.warnings` entry; an endpoint that verifies signatures will reject it and the result is lost once retries are exhausted." }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 } } } } } }, "responses": { "202": { "description": "Lead queued (new). A call job was created and a lead.received trigger dispatched.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending" ] }, "agent_id": { "type": "integer" }, "agent_name": { "type": "string" }, "destination_phone": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "200": { "description": "Idempotent replay \u2014 a prior request with the same Idempotency-Key already created this job.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "status": { "type": "string" }, "idempotent": { "type": "boolean", "enum": [ true ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "leads:inbound" ] } }, "/triggers": { "get": { "tags": [ "Triggers" ], "operationId": "listTriggers", "summary": "List triggers", "description": "Lists the organization's triggers, each with an `action_count`. Filter with `event_type` and/or `is_enabled`.\n\nRequires one of the following scopes: `triggers:read`, `triggers:manage`.", "parameters": [ { "name": "event_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "is_enabled", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "X-Sub-Org-Id", "in": "header", "required": false, "schema": { "type": "integer" }, "description": "Partner/reseller context switch: run the request against a sub-organization the authenticated partner account is the parent of. Requires an org_type=partner key." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/Trigger" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:read", "triggers:manage" ] }, "post": { "tags": [ "Triggers" ], "operationId": "createTrigger", "summary": "Create a trigger", "description": "Requires one of the following scopes: `triggers:write`, `triggers:manage`.", "parameters": [ { "name": "X-Sub-Org-Id", "in": "header", "required": false, "schema": { "type": "integer" }, "description": "Partner/reseller context switch: run the request against a sub-organization the authenticated partner account is the parent of. Requires an org_type=partner key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCreate" } } } }, "responses": { "201": { "description": "Trigger created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Trigger" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:write", "triggers:manage" ] } }, "/triggers/events": { "get": { "tags": [ "Triggers" ], "operationId": "listTriggerEventTypes", "summary": "List available event types", "description": "Requires one of the following scopes: `triggers:read`, `triggers:manage`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" } } } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:read", "triggers:manage" ] } }, "/triggers/action-types": { "get": { "tags": [ "Triggers" ], "operationId": "listTriggerActionTypes", "summary": "List available action types", "description": "Requires one of the following scopes: `triggers:read`, `triggers:manage`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "action_types": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" } } } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:read", "triggers:manage" ] } }, "/triggers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trigger id" } ], "get": { "tags": [ "Triggers" ], "operationId": "getTrigger", "summary": "Get a trigger", "description": "Returns the trigger with its embedded actions array.\n\nRequires one of the following scopes: `triggers:read`, `triggers:manage`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Trigger" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:read", "triggers:manage" ] }, "patch": { "tags": [ "Triggers" ], "operationId": "updateTrigger", "summary": "Update a trigger", "description": "Requires one of the following scopes: `triggers:write`, `triggers:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Trigger" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:write", "triggers:manage" ] }, "delete": { "tags": [ "Triggers" ], "operationId": "deleteTrigger", "summary": "Delete a trigger", "description": "Deletes the trigger; its actions are cascade-deleted. Returns `{ deleted: true }` (HTTP 200), not 204.\n\nRequires one of the following scopes: `triggers:delete`, `triggers:manage`.", "responses": { "200": { "description": "Deleted (actions cascade).", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:delete", "triggers:manage" ] } }, "/triggers/{id}/actions": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trigger id" } ], "post": { "tags": [ "Triggers" ], "operationId": "addTriggerAction", "summary": "Add an action to a trigger", "description": "Requires one of the following scopes: `triggers:write`, `triggers:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerActionCreate" } } } }, "responses": { "201": { "description": "Action created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TriggerAction" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:write", "triggers:manage" ] } }, "/triggers/{id}/actions/{actionId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trigger id" }, { "name": "actionId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Action id" } ], "patch": { "tags": [ "Triggers" ], "operationId": "updateTriggerAction", "summary": "Update an action", "description": "Requires one of the following scopes: `triggers:write`, `triggers:manage`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerActionUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TriggerAction" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:write", "triggers:manage" ] }, "delete": { "tags": [ "Triggers" ], "operationId": "deleteTriggerAction", "summary": "Delete an action", "description": "Removes the action. Returns `{ deleted: true }` (HTTP 200), not 204.\n\nRequires one of the following scopes: `triggers:delete`, `triggers:manage`.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:delete", "triggers:manage" ] } }, "/triggers/{id}/test": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trigger id" } ], "post": { "tags": [ "Triggers" ], "operationId": "testTrigger", "summary": "Test-fire a trigger", "description": "Synchronously executes the trigger against sample (or supplied) event data. WARNING: this fires the trigger's REAL actions \u2014 sending SMS/email/Slack messages, calling webhooks, running flows \u2014 it is NOT a dry run. Gated on `triggers:manage` so a write-only key cannot incur real actions/costs.\n\nRequires the `triggers:manage` scope.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_data": { "type": "object", "additionalProperties": true, "description": "Optional sample event payload; a default is generated if omitted." } } } } } }, "responses": { "200": { "description": "Executed", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "test_result": { "type": "object", "additionalProperties": true }, "event_data": { "type": "object", "additionalProperties": true } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:manage" ] } }, "/triggers/{id}/logs": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trigger id" } ], "get": { "tags": [ "Triggers" ], "operationId": "getTriggerLogs", "summary": "Get execution logs", "description": "Paginated execution log for the trigger. Pagination is returned inside `data.pagination` (not the top-level meta).\n\nRequires one of the following scopes: `triggers:read`, `triggers:manage`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "triggers:read", "triggers:manage" ] } }, "/organizations": { "get": { "tags": [ "Organizations" ], "operationId": "listOrganizations", "summary": "List sub-organizations", "description": "Lists the sub-organizations under the calling partner account. Returns 403 unless the calling org is `org_type='partner'`. Offset-paginated; filter with `status` and `search`.\n\nRequires one of the following scopes: `organizations:read`, `organizations:*`, `*`.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubOrganization" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "organizations:read", "organizations:*", "*" ] }, "post": { "tags": [ "Organizations" ], "operationId": "createOrganization", "summary": "Create a sub-organization", "description": "Creates a sub-org under the calling partner account (403 unless `org_type='partner'`). plan_type and billing_account are inherited from the parent; limits are clamped to the parent plan.\n\nRequires one of the following scopes: `organizations:write`, `organizations:*`, `*`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrganizationCreate" } } } }, "responses": { "201": { "description": "Sub-organization created", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SubOrganization" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "organizations:write", "organizations:*", "*" ] } }, "/organizations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Sub-organization id" } ], "get": { "tags": [ "Organizations" ], "operationId": "getOrganization", "summary": "Get a sub-organization", "description": "Returns a sub-org owned by the calling partner (403 unless `org_type='partner'`).\n\nRequires one of the following scopes: `organizations:read`, `organizations:*`, `*`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SubOrganization" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "organizations:read", "organizations:*", "*" ] }, "patch": { "tags": [ "Organizations" ], "operationId": "updateOrganization", "summary": "Update a sub-organization", "description": "Updates a sub-org (403 unless `org_type='partner'`). A missing/foreign sub-org id fails as 400.\n\nRequires one of the following scopes: `organizations:write`, `organizations:*`, `*`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrganizationUpdate" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/SubOrganization" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "organizations:write", "organizations:*", "*" ] }, "delete": { "tags": [ "Organizations" ], "operationId": "deleteOrganization", "summary": "Delete a sub-organization", "description": "Soft-deletes a sub-org (403 unless `org_type='partner'`). A missing/foreign sub-org id fails as 400.\n\nRequires one of the following scopes: `organizations:delete`, `organizations:*`, `*`.", "responses": { "204": { "description": "Soft-deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "organizations:delete", "organizations:*", "*" ] } }, "/billing/subscription": { "get": { "tags": [ "Billing" ], "operationId": "getBillingSubscription", "summary": "Get current subscription", "description": "Returns the org's current subscription and plan snapshot.\n\nRequires one of the following scopes: `billing:read`, `billing:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Subscription" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:read", "billing:manage" ] } }, "/billing/subscription/upgrade": { "post": { "tags": [ "Billing" ], "operationId": "upgradeBillingSubscription", "summary": "Upgrade plan", "description": "Upgrades the plan. Only monthly billing is available (annual was removed).\n\nRequires the `billing:manage` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string" }, "interval": { "type": "string", "enum": [ "monthly" ], "default": "monthly" }, "expected_charge_cents": { "type": [ "integer", "null" ], "description": "What the caller states it disclosed to the customer, in cents \u2014 the `disclosed_charge_cents` returned by `POST /billing/subscription/upgrade-preview`.\n\n**Optional for Bearer callers.** An API client has no page and nothing to bind to, so omitting the field skips the comparison and the upgrade proceeds.\n\n**Required in practice of a browser.** A session-authenticated request that omits it is answered `409 disclosure_required`: every dashboard path previews first, so a session request carrying no figure is a page cached from before that shipped, and charging it would charge a card an amount nobody was shown.\n\nThe value is never charged. It is only compared against the server's own recomputed proration; if they differ the upgrade is refused with `409 amount_changed` and nothing is charged \u2014 so a wrong value can only refuse its own upgrade. `0` is a disclosure (\"no charge today\"), not an absence." } } } } } }, "responses": { "200": { "description": "Upgraded", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Refused before the gateway; nothing was charged and no subscription row was touched.\n\n- `disclosure_required` \u2014 a session-authenticated (browser) request omitted `expected_charge_cents`. The page is stale: reload it, re-read the price, and retry. Bearer callers never receive this.\n- `amount_changed` \u2014 the disclosed figure no longer matches the server's recomputed proration. `error.details.charge_amount_cents` carries the current figure; re-disclose it before retrying.\n\nThe code is in `error.code`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "disclosure_required", "amount_changed" ], "description": "Which refusal fired. Both are refused before the gateway." } } } } } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:manage" ] } }, "/billing/subscription/upgrade-preview": { "post": { "tags": [ "Billing" ], "operationId": "previewBillingSubscriptionUpgrade", "summary": "Preview an upgrade", "description": "Answers \"what happens if I upgrade to this plan, and what does it cost me today\" without charging or writing anything.\n\nThe sentence and the figure come back together, from one server-side decision, so a caller cannot show one number and send another: echo `disclosed_charge_cents` back as `expected_charge_cents` on `POST /billing/subscription/upgrade` and the server refuses to charge anything else.\n\n**Always 200, including for a refusal.** `disclose: false` is a successful answer to the question \u2014 render `message` and keep the confirm control disabled.\n\nPOST rather than GET because it reads an org's billing state and so is CSRF-protected for the browser path. Requires the `billing:manage` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string", "description": "Target plan key." }, "interval": { "type": "string", "enum": [ "monthly" ], "default": "monthly" } } } } } }, "responses": { "200": { "description": "The disclosure to show before offering the upgrade.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "disclose", "message", "disclosed_charge_cents" ], "properties": { "disclose": { "type": "boolean", "description": "`false` means do not offer the upgrade at all: show `message` and keep the confirm control off." }, "reason": { "type": [ "string", "null" ], "description": "Why the upgrade was refused, or `null` when `disclose` is true. An operator/log code whose vocabulary is not part of this contract \u2014 render `message`, never the code, and do not switch on it." }, "message": { "type": "string", "description": "The complete sentence to show the customer. True whether or not the upgrade can proceed." }, "disclosed_charge_cents": { "type": [ "integer", "null" ], "description": "Exactly what `message` states will be charged today. `0` is a real answer (\"no charge today\"). `null` only when `disclose` is false, i.e. there is nothing to echo back. Send this as `expected_charge_cents`." }, "charge_label": { "type": [ "string", "null" ], "description": "`disclosed_charge_cents` formatted for display." }, "monthly_label": { "type": [ "string", "null" ], "description": "The plan's recurring monthly price, formatted." }, "plan_name": { "type": [ "string", "null" ], "description": "Display name for the target plan. `null` for a key we do not sell \u2014 never the raw key, so a modal cannot ask a customer to confirm a plan name we invented." } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:manage" ] } }, "/billing/subscription/downgrade": { "post": { "tags": [ "Billing" ], "operationId": "downgradeBillingSubscription", "summary": "Downgrade plan", "description": "Requires the `billing:manage` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string" } } } } } }, "responses": { "200": { "description": "Downgrade scheduled/applied", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:manage" ] } }, "/billing/subscription/cancel": { "post": { "tags": [ "Billing" ], "operationId": "cancelBillingSubscription", "summary": "Cancel subscription", "description": "Requires the `billing:manage` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:manage" ] } }, "/billing/payment-methods": { "get": { "tags": [ "Billing" ], "operationId": "listBillingPaymentMethods", "summary": "List payment methods", "description": "Payment methods belong to the org's billing account (shared across member orgs).\n\nRequires one of the following scopes: `billing:read`, `billing:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:read", "billing:manage" ] }, "post": { "tags": [ "Billing" ], "operationId": "addBillingPaymentMethod", "summary": "Add a payment method", "description": "Requires the `billing:manage` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodCreate" } } } }, "responses": { "201": { "description": "Payment method added", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PaymentMethod" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:manage" ] } }, "/billing/payment-methods/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Payment method id" } ], "delete": { "tags": [ "Billing" ], "operationId": "removeBillingPaymentMethod", "summary": "Remove a payment method", "description": "Requires the `billing:manage` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "204": { "description": "Removed" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:manage" ] } }, "/billing/payment-methods/{id}/default": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Payment method id" } ], "patch": { "tags": [ "Billing" ], "operationId": "setDefaultBillingPaymentMethod", "summary": "Set default payment method", "description": "Requires the `billing:manage` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Default set", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "id": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:manage" ] } }, "/billing/invoices": { "get": { "tags": [ "Billing" ], "operationId": "listBillingInvoices", "summary": "List invoices", "description": "Invoices for the org's billing account. Pagination is returned inside `data` (items/total/limit/offset), not the top-level meta.\n\nRequires one of the following scopes: `billing:read`, `billing:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "account_id": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:read", "billing:manage" ] } }, "/billing/invoices/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "get": { "tags": [ "Billing" ], "operationId": "getBillingInvoice", "summary": "Get an invoice", "description": "Returns the full invoice with its decoded line_items.\n\nRequires one of the following scopes: `billing:read`, `billing:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/Invoice" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:read", "billing:manage" ] } }, "/billing/tokenization-config": { "get": { "tags": [ "Billing" ], "operationId": "getBillingTokenizationConfig", "summary": "Get hosted-tokenization config", "description": "Frontend config for accept.blue hosted card tokenization (script URL + public tokenization key). Use this to collect a `payment_token` for POST /billing/payment-methods.\n\nRequires one of the following scopes: `billing:read`, `billing:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "provider": { "type": "string" }, "tokenization_key": { "type": "string" }, "public_key": { "type": "string" }, "script_url": { "type": "string" }, "mode": { "type": "string" }, "configured": { "type": "boolean" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "billing:read", "billing:manage" ] } }, "/aws/status": { "get": { "tags": [ "AWS" ], "operationId": "getAwsStatus", "summary": "Get AWS service status", "description": "Overall AWS connectivity/configuration status. The AWS account id is intentionally omitted.\n\nRequires the `aws:read` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "configured": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" }, "services": { "type": "object", "properties": { "credentials": { "type": "object", "additionalProperties": true } } }, "aws_region": { "type": "string" }, "overall_status": { "type": "string", "enum": [ "healthy", "degraded" ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "aws:read" ] } }, "/aws/credentials/status": { "get": { "tags": [ "AWS" ], "operationId": "getAwsCredentialsStatus", "summary": "Get AWS credential status", "description": "STS credential validation status (getCallerIdentity).\n\nRequires the `aws:read` scope. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "connected", "error", "not_configured" ] }, "region": { "type": "string" }, "message": { "type": "string" }, "config_mode": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "aws:read" ] } }, "/widget/token": { "post": { "tags": [ "Widget" ], "operationId": "createWidgetToken", "summary": "Mint a widget token", "description": "Mints a short-lived HMAC widget token scoped to specific campaigns (and optionally origins), for embedding in a browser widget. Each campaign id must exist and belong to the calling org (404 otherwise). The returned token authenticates the `/widget/campaigns/*` operations.\n\nRequires the `widget:create` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "campaign_ids" ], "properties": { "campaign_ids": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "description": "Non-empty list of campaign ids the token may drive." }, "ttl": { "type": "integer", "minimum": 1, "maximum": 86400, "default": 3600, "description": "Token lifetime in seconds." }, "allowed_origins": { "type": "array", "items": { "type": "string" }, "description": "Optional http(s) origins (scheme://host[:port], no path) the token is bound to." } } } } } }, "responses": { "200": { "description": "Token minted", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/WidgetTokenResponse" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "widget:create" ] } }, "/widget/token/revoke": { "post": { "tags": [ "Widget" ], "operationId": "revokeWidgetToken", "summary": "Revoke a widget token", "description": "Best-effort revocation of a widget token by its jti (via the shared token cache). For guaranteed revocation of all of the org's widget tokens, rotate the organization API key. A token belonging to another org returns the same generic error (no cross-org oracle).\n\nRequires the `widget:create` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Revoked (best-effort)", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "jti": { "type": [ "string", "null" ] }, "revoked_until": { "type": [ "string", "null" ] }, "note": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "widget:create" ] } }, "/widget/campaigns/{id}/status": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "get": { "tags": [ "Widget" ], "operationId": "getWidgetCampaignStatus", "summary": "Get campaign status (widget token)", "description": "Campaign status and progress. Authenticated with a Widget token (`Authorization: Widget `) that grants access to this campaign.\n\nRequires the `widget:campaign:status` scope.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "object", "properties": { "total_contacts": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "in_progress": { "type": "integer" } } }, "outcomes": { "type": "object", "additionalProperties": true } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "widgetToken": [] } ], "x-required-scopes": [ "widget:campaign:status" ] } }, "/widget/campaigns/{id}/start": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "post": { "tags": [ "Widget" ], "operationId": "startWidgetCampaign", "summary": "Start a campaign (widget token)", "description": "Starts a campaign (allowed from ready/scheduled/paused). Authenticated with a Widget token that grants access to this campaign.\n\nRequires the `widget:campaign:start` scope.", "responses": { "200": { "description": "Started", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "running" ] }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "widgetToken": [] } ], "x-required-scopes": [ "widget:campaign:start" ] } }, "/widget/campaigns/{id}/stop": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign id" } ], "post": { "tags": [ "Widget" ], "operationId": "stopWidgetCampaign", "summary": "Stop a campaign (widget token)", "description": "Stops a running campaign. Authenticated with a Widget token that grants access to this campaign.\n\nRequires the `widget:campaign:stop` scope.", "responses": { "200": { "description": "Stopped", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "completed" ] }, "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "widgetToken": [] } ], "x-required-scopes": [ "widget:campaign:stop" ] } }, "/telephony/providers/{id}/set-default": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Provider id" } ], "post": { "tags": [ "Telephony" ], "operationId": "setDefaultTelephonyProvider", "summary": "Set the default provider", "description": "Marks a provider as the org default. Rejects shared/platform providers or any provider not owned by the org (404).\n\nRequires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Default updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "provider_id": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] } }, "/telephony/calls": { "get": { "tags": [ "Telephony" ], "operationId": "listTelephonyCalls", "summary": "List calls", "description": "Offset-paginated call list with optional filters.\n\nRequires one of the following scopes: `telephony:read`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Max items to return (1-100)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of items to skip." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "phone_number", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TelephonyCall" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ] }, "post": { "tags": [ "Telephony" ], "operationId": "initiateTelephonyCall", "summary": "Initiate a call", "description": "Places an outbound call. COMPLIANCE-GATED and fails closed: the destination is screened against the DNC list (federal + internal), the `from` number must be an active org-owned number (Truth-in-Caller-ID Act), and the call must fall within the TCPA calling window evaluated in the recipient's local time. Any gate failure returns 403; if DNC verification is unavailable the call is refused.\n\nRequires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelephonyCallInitiate" } } } }, "responses": { "201": { "description": "Call initiated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "provider_call_id": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] } }, "/telephony/calls/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id (UUID)" } ], "get": { "tags": [ "Telephony" ], "operationId": "getTelephonyCall", "summary": "Get call status", "description": "Requires one of the following scopes: `telephony:read`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/TelephonyCall" } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ] } }, "/telephony/calls/{id}/hangup": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id (UUID)" } ], "post": { "tags": [ "Telephony" ], "operationId": "hangupTelephonyCall", "summary": "Hang up a call", "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Terminated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] } }, "/telephony/calls/{id}/transfer": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id (UUID)" } ], "post": { "tags": [ "Telephony" ], "operationId": "transferTelephonyCall", "summary": "Transfer a call", "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination" ], "properties": { "destination": { "type": "string" }, "type": { "type": "string", "description": "Transfer type. Only blind transfer is supported by the underlying carriers; any other value is rejected with 422 TRANSFER_TYPE_UNSUPPORTED.", "enum": [ "blind" ], "default": "blind" } } } } } }, "responses": { "200": { "description": "Transfer initiated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] } }, "/telephony/calls/{id}/hold": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id (UUID)" } ], "post": { "tags": [ "Telephony" ], "operationId": "holdTelephonyCall", "summary": "Hold a call", "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "hold_music_url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "On hold", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] } }, "/telephony/calls/{id}/resume": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id (UUID)" } ], "post": { "tags": [ "Telephony" ], "operationId": "resumeTelephonyCall", "summary": "Resume a call", "description": "Requires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Resumed", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] } }, "/telephony/calls/{id}/events": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id (UUID)" } ], "get": { "tags": [ "Telephony" ], "operationId": "getTelephonyCallEvents", "summary": "Get call event timeline", "description": "Requires one of the following scopes: `telephony:read`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string" }, "event_data": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ] } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ] } }, "/telephony/calls/{id}/recording": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call id (UUID)" } ], "get": { "tags": [ "Telephony" ], "operationId": "getTelephonyCallRecording", "summary": "Get call recording", "description": "Recording URL/metadata. Returns 404 when no recording exists for the call.\n\nRequires one of the following scopes: `telephony:read`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "recording_url": { "type": "string" }, "duration_seconds": { "type": [ "integer", "null" ] }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ] } }, "/telephony/config": { "get": { "tags": [ "Telephony" ], "operationId": "getTelephonyConfig", "summary": "Get telephony config", "description": "Supported provider types and their credential/config schemas.\n\nRequires one of the following scopes: `telephony:read`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "supported_providers": { "type": "array", "items": { "type": "string" } }, "provider_schemas": { "type": "object", "additionalProperties": true } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ] } }, "/telephony/sip-trunk": { "get": { "tags": [ "Telephony" ], "operationId": "getTelephonySipTrunk", "summary": "Get the BYOC SIP trunk", "description": "Returns the org's single BYOC SIP trunk (or `configured: false`).\n\nRequires one of the following scopes: `telephony:read`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "configured": { "type": "boolean" }, "sip_trunk": { "oneOf": [ { "$ref": "#/components/schemas/SipTrunk" }, { "type": "null" } ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:read", "telephony:manage" ] }, "post": { "tags": [ "Telephony" ], "operationId": "saveTelephonySipTrunk", "summary": "Create or update the SIP trunk", "description": "Creates the SIP trunk if none exists, otherwise updates it. Returns the saved trunk (HTTP 200).\n\nRequires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SipTrunkSave" } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "configured": { "type": "boolean" }, "sip_trunk": { "$ref": "#/components/schemas/SipTrunk" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] }, "delete": { "tags": [ "Telephony" ], "operationId": "deleteTelephonySipTrunk", "summary": "Delete the SIP trunk", "description": "Soft-deletes the org's SIP trunk (404 if none configured).\n\nRequires one of the following scopes: `telephony:delete`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "responses": { "204": { "description": "Soft-deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:delete", "telephony:manage" ] } }, "/telephony/sip-trunk/test": { "post": { "tags": [ "Telephony" ], "operationId": "testTelephonySipTrunk", "summary": "Test SIP reachability", "description": "Tests SIP endpoint reachability. Tests the supplied sip_uri, or the saved trunk when the body is empty. SSRF-guarded: private/reserved/loopback/IMDS hosts are rejected. When testing the saved trunk, updates its validation status.\n\nRequires one of the following scopes: `telephony:write`, `telephony:manage`. Session authentication also works for browser (dashboard) contexts; this operation documents the Bearer path.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "sip_uri": { "type": "string", "description": "Omit to test the saved trunk." }, "sip_transport": { "type": "string", "enum": [ "udp", "tcp", "tls" ], "default": "udp" } } } } } }, "responses": { "200": { "description": "Reachable", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "response_time_ms": { "type": [ "number", "null" ] } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "telephony:write", "telephony:manage" ] } }, "/agents/{id}/shares": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" } ], "get": { "tags": [ "Agents" ], "operationId": "listAgentShares", "summary": "List agent shares", "description": "Partner feature: lists the sub-organizations this agent is shared with.\n\nRequires one of the following scopes: `agents:read`, `agents:*`, `*`.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "target_organization_id": { "type": "integer" }, "organization_name": { "type": [ "string", "null" ] }, "organization_slug": { "type": [ "string", "null" ] }, "permissions": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:read", "agents:*", "*" ] }, "post": { "tags": [ "Agents" ], "operationId": "shareAgent", "summary": "Share an agent with a sub-organization", "description": "Partner feature: shares this agent with a sub-organization.\n\nRequires one of the following scopes: `agents:write`, `agents:*`, `*`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_organization_id" ], "properties": { "target_organization_id": { "type": "integer" }, "permissions": { "type": "string", "default": "use" } } } } } }, "responses": { "201": { "description": "Shared", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:write", "agents:*", "*" ] } }, "/agents/{id}/shares/{orgId}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Agent id" }, { "name": "orgId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Target organization id" } ], "delete": { "tags": [ "Agents" ], "operationId": "revokeAgentShare", "summary": "Revoke an agent share", "description": "Partner feature: revokes an agent share from a sub-organization.\n\nRequires one of the following scopes: `agents:write`, `agents:*`, `*`.", "responses": { "204": { "description": "Revoked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "agents:write", "agents:*", "*" ] } }, "/dnc/stats": { "get": { "tags": [ "DNC" ], "operationId": "getDncStats", "summary": "Get DNC statistics", "description": "Aggregate DNC statistics for the organization.\n\nRequires the `dnc:read` scope.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "total_entries": { "type": "integer" }, "active_lists": { "type": "integer" }, "entries_by_reason": { "type": "object", "additionalProperties": { "type": "integer" } }, "checks_today": { "type": "integer" }, "blocked_today": { "type": "integer" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "dnc:read" ] } }, "/schedules/{id}/hours": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Schedule id" } ], "get": { "tags": [ "Schedules" ], "operationId": "getScheduleHours", "summary": "Get weekly business hours", "description": "Weekly business hours for the schedule (one row per configured day).\n\nRequires the `schedules:read` scope.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "schedule_id": { "type": "integer" }, "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0=Sunday .. 6=Saturday." }, "is_open": { "type": [ "integer", "boolean" ] }, "open_time": { "type": [ "string", "null" ], "description": "HH:MM:SS." }, "close_time": { "type": [ "string", "null" ], "description": "HH:MM:SS." }, "day_name": { "type": "string" } } } } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:read" ] }, "put": { "tags": [ "Schedules" ], "operationId": "replaceScheduleHours", "summary": "Replace weekly business hours", "description": "FULL REPLACE (PUT): the supplied `hours` array replaces all existing weekly hours for the schedule.\n\nRequires the `schedules:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hours" ], "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "is_open": { "type": [ "integer", "boolean" ] }, "open_time": { "type": [ "string", "null" ] }, "close_time": { "type": [ "string", "null" ] } } } } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Key-Expires-At": { "$ref": "#/components/headers/XApiKeyExpiresAt" }, "X-API-Key-Expires-In-Days": { "$ref": "#/components/headers/XApiKeyExpiresInDays" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "schedules:write" ] } }, "/numbers": { "get": { "tags": [ "Telephony" ], "operationId": "partnerListNumbers", "summary": "List numbers (partner fa\u00e7ade, includes webhook wiring)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerNumber" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Telephony" ], "operationId": "partnerBuyNumber", "summary": "Buy a number and wire it to a bot + operator webhooks in one call", "description": "Requires scope telephony:write or telephony:manage. Send an Idempotency-Key header per buy \u2014 a retried request with the same key will not order a second number (a stored outcome, including a stored error, is replayed; use a fresh key for a genuinely new attempt).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Unique key per purchase attempt; retries with the same key replay the stored outcome." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bot_id" ], "properties": { "bot_id": { "type": "integer", "description": "Active inbound agent (agent_direction=inbound) that answers this number" }, "number": { "type": "string", "description": "Explicit E.164 number to buy (alternative to area_code)" }, "area_code": { "type": "string", "description": "3-digit NANP area code; first available number is bought" }, "inbound_context_url": { "type": "string", "nullable": true, "description": "Operator CRM endpoint POSTed {caller_phone, dialed_number} at answer time (HMAC-signed). Keep p99 well under 2s." }, "call_result_url": { "type": "string", "nullable": true, "description": "Operator CRM endpoint POSTed the call result at call end (HMAC-signed)." }, "webhook_secret_ref": { "type": "string", "nullable": true, "description": "Named secret (stored via PUT /numbers/secrets/{ref}) used to sign both webhooks. Required while any webhook URL is set." } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PartnerNumber" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/numbers/{provider_number_id}": { "parameters": [ { "name": "provider_number_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Telephony" ], "operationId": "partnerUpdateNumberWebhooks", "summary": "Wire/unwire operator webhooks on an existing number", "description": "Only webhook wiring is updatable; a field present in the body is applied, explicit null clears it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inbound_context_url": { "type": "string", "nullable": true, "description": "Operator CRM endpoint POSTed {caller_phone, dialed_number} at answer time (HMAC-signed). Keep p99 well under 2s." }, "call_result_url": { "type": "string", "nullable": true, "description": "Operator CRM endpoint POSTed the call result at call end (HMAC-signed)." }, "webhook_secret_ref": { "type": "string", "nullable": true, "description": "Named secret (stored via PUT /numbers/secrets/{ref}) used to sign both webhooks. Required while any webhook URL is set." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "$ref": "#/components/schemas/PartnerNumber" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Telephony" ], "operationId": "partnerReleaseNumber", "summary": "Release a number (carrier-side release + soft delete)", "responses": { "204": { "description": "Released" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/numbers/secrets/{ref}": { "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,99}$" } } ], "put": { "tags": [ "Telephony" ], "operationId": "partnerPutWebhookSecret", "summary": "Store/rotate a named webhook-signing secret (write-only)", "description": "The secret value (16-512 chars) is envelope-encrypted at rest and never returned by any API.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "minLength": 16, "maxLength": 512 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "ref": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "vosy_sk_...", "description": "Scoped API key. Send as `Authorization: Bearer vosy_sk_...`." }, "widgetToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Short-lived HMAC widget token, sent as `Authorization: Widget `. Tokens are minted via `POST /widget/token` (which itself requires a Bearer key with the `widget:create` scope), are self-validating (no DB lookup), default to a 1h TTL (24h max), and are scoped to specific campaign ids and, optionally, allowed origins." } }, "parameters": {}, "headers": { "XRequestID": { "description": "Correlation id (echoes the request's X-Request-ID or a fresh UUIDv4). Present on every authed response including failures.", "schema": { "type": "string" } }, "XRateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "XRateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "XRateLimitReset": { "description": "Unix epoch seconds when the window resets.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying (on 429).", "schema": { "type": "integer" } }, "XApiKeyExpiresAt": { "description": "Present when the key expires within 7 days: ISO-8601 UTC expiry.", "schema": { "type": "string" } }, "XApiKeyExpiresInDays": { "description": "Present when the key expires within 7 days: whole days remaining.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Invalid request (validation errors under error.details.validation_errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "Missing or invalid API key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorEnvelope" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "Forbidden": { "description": "Authenticated but not permitted (insufficient scope uses the auth envelope with code INSUFFICIENT_SCOPE; policy/plan denials use the router envelope).", "headers": { "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorEnvelope" }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "NotFound": { "description": "Resource not found (also returned for cross-tenant ids to avoid existence leaks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "MethodNotAllowed": { "description": "HTTP method not allowed for this route.", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Conflict": { "description": "Conflict (e.g. duplicate entry).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-Request-ID": { "$ref": "#/components/headers/XRequestID" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorEnvelope" } } } }, "BadGateway": { "description": "Upstream fetch failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServiceUnavailable": { "description": "Dependent service unavailable (fail-closed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "description": "Router error envelope (ApiResponse::error).", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable error code, e.g. bad_request, not_found." }, "details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional; validation failures put field errors under details.validation_errors." } } } } }, "AuthErrorEnvelope": { "type": "object", "description": "Auth/rate-limit error envelope (ApiAuthMiddleware::sendError). Note the code/message order differs from the router envelope, and retry_after appears only on 429.", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "e.g. MISSING_AUTH, INVALID_API_KEY, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED." }, "message": { "type": "string" }, "retry_after": { "type": "integer", "description": "Seconds; present on 429 only." } } } } }, "PaginationMeta": { "type": "object", "description": "Offset pagination metadata (in the top-level meta object).", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "OffsetPagination": { "type": "object", "description": "Offset pagination block embedded in the data object (v1-style list).", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "PagePagination": { "type": "object", "description": "Page-based pagination (ApiResponse::paginatedByPage).", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next": { "type": "boolean" }, "has_prev": { "type": "boolean" } } }, "Voice": { "type": "object", "description": "TTS voice. Null provider/id means the platform default is used.", "properties": { "provider": { "type": [ "string", "null" ], "description": "TTS provider (e.g. cartesia); null = platform default." }, "id": { "type": [ "string", "null" ], "description": "Provider voice id; null = platform default." }, "speed": { "type": "number" }, "emotion": { "type": [ "string", "null" ] } } }, "Llm": { "type": "object", "properties": { "provider": { "type": [ "string", "null" ], "description": "LLM provider (e.g. openai, anthropic); null = platform default." }, "model": { "type": [ "string", "null" ] }, "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "Voicemail": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "message": { "type": [ "string", "null" ] } } }, "Agent": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "agent_mode": { "type": "string" }, "agent_direction": { "type": "string", "enum": [ "inbound", "outbound", "both" ], "description": "Whether the agent places calls (outbound), answers them (inbound), or does both (both)." }, "agent_role": { "type": [ "string", "null" ], "enum": [ "leasing_agent", "staffing_agent", "mhp_sales_agent", "plumbing_receptionist", null ] }, "language_code": { "type": "string", "description": "Mapped from stt_language." }, "system_prompt": { "type": "string" }, "first_message": { "type": [ "string", "null" ] }, "voice": { "$ref": "#/components/schemas/Voice" }, "llm": { "$ref": "#/components/schemas/Llm" }, "voicemail": { "$ref": "#/components/schemas/Voicemail" }, "screening_detection_enabled": { "type": "boolean", "description": "When true, the worker detects Google/Apple call-screening bots and speaks screening_response before the opener. Defaults true." }, "screening_response": { "type": [ "string", "null" ], "description": "Line spoken to a detected call-screening bot. null = the worker uses its built-in default at call time." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AgentCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "agent_mode": { "type": "string", "default": "streaming" }, "agent_direction": { "type": "string", "enum": [ "inbound", "outbound", "both" ], "default": "outbound", "description": "Whether the agent places calls (outbound), answers them (inbound), or does both (both). A 'both' agent can be assigned a phone number for inbound AND used in outbound campaigns. Both 'inbound' and 'both' require the inbound-calling entitlement on your organization; without it the request is rejected with 400." }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "default": "draft" }, "system_prompt": { "type": "string" }, "first_message": { "type": "string" }, "language_code": { "type": "string", "description": "Persisted to stt_language." }, "voice": { "type": "object", "properties": { "provider": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "speed": { "type": "number" }, "emotion": { "type": "string" } } }, "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "agent_role": { "type": [ "string", "null" ], "enum": [ "leasing_agent", "staffing_agent", "mhp_sales_agent", "plumbing_receptionist", null ], "description": "Persona. null clears the role." }, "voicemail_enabled": { "type": "boolean" }, "voicemail_message": { "type": "string" }, "screening_detection_enabled": { "type": "boolean" }, "screening_response": { "type": [ "string", "null" ] } } }, "AgentUpdate": { "type": "object", "description": "All fields optional; only supplied fields change.", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "agent_mode": { "type": "string", "default": "streaming" }, "agent_direction": { "type": "string", "enum": [ "inbound", "outbound", "both" ], "default": "outbound", "description": "Whether the agent places calls (outbound) or answers them (inbound). Switching an agent to 'inbound' requires the inbound-calling entitlement on your organization; without it the request is rejected with 400." }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ], "default": "draft" }, "system_prompt": { "type": "string" }, "first_message": { "type": "string" }, "language_code": { "type": "string", "description": "Persisted to stt_language." }, "voice": { "type": "object", "properties": { "provider": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "speed": { "type": "number" }, "emotion": { "type": "string" } } }, "llm": { "type": "object", "properties": { "provider": { "type": "string" }, "model": { "type": "string" }, "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "agent_role": { "type": [ "string", "null" ], "enum": [ "leasing_agent", "staffing_agent", "mhp_sales_agent", "plumbing_receptionist", null ], "description": "Persona. null clears the role." }, "voicemail_enabled": { "type": "boolean" }, "voicemail_message": { "type": "string" }, "screening_detection_enabled": { "type": "boolean" }, "screening_response": { "type": [ "string", "null" ] } } }, "KnowledgeBase": { "type": "object", "properties": { "id": { "type": "integer" }, "agent_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "kb_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "priority": { "type": "integer" }, "is_enabled": { "type": "boolean" }, "chunk_size": { "type": "integer" }, "chunk_overlap": { "type": "integer" }, "total_documents": { "type": "integer" }, "total_chunks": { "type": "integer" }, "total_size_bytes": { "type": "integer" }, "bedrock_kb_id": { "type": [ "string", "null" ] }, "kendra_index_id": { "type": [ "string", "null" ] }, "s3_bucket": { "type": [ "string", "null" ] }, "s3_prefix": { "type": [ "string", "null" ] }, "custom_api_endpoint": { "type": [ "string", "null" ] }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": {}, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "AssignedAgent": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } }, "KnowledgeBaseDocument": { "type": "object", "properties": { "id": { "type": "integer" }, "file_name": { "type": [ "string", "null" ] }, "file_type": { "type": [ "string", "null" ] }, "file_size_bytes": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "source_type": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "chunk_count": { "type": "integer" }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "indexed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "KnowledgeBaseWithAgents": { "allOf": [ { "$ref": "#/components/schemas/KnowledgeBase" }, { "type": "object", "properties": { "assigned_agents": { "type": "array", "items": { "$ref": "#/components/schemas/AssignedAgent" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBaseDocument" }, "description": "Only when with_documents=true." } } } ] }, "KnowledgeBaseCreate": { "type": "object", "required": [ "name" ], "additionalProperties": true, "description": "Extra fields (kb_type, priority, chunk_size, chunk_overlap, etc.) pass through to the service.", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "agent_ids": { "type": "array", "items": { "type": "integer" }, "description": "Owning agent set (preferred)." }, "agent_id": { "type": "integer", "description": "Legacy single-agent alias." } } }, "KnowledgeBaseUpdate": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "agent_ids": { "type": "array", "items": { "type": "integer" }, "description": "Optional full-replace reassignment." } } }, "CallSchedule": { "type": "object", "description": "Every call scheduled through this endpoint is stamped server-side with a TCPA attestation (`acknowledged`, `acknowledged_via: api_terms_of_service`, `acknowledged_at`). The consent basis and DNC SAN on that attestation are read from your organization's compliance settings (Settings -> Compliance: `default_consent_basis`, `dnc_san`) -- they cannot be supplied per call here. If those settings are unset, calls still dial but the attestation carries no consent basis, which weakens your position in a TCPA traceback. To declare a consent basis per call, use `POST /telephony/calls` instead. The destination is screened against your DNC list and the TCPA calling window before dialing; both gates fail closed.", "required": [ "bot_id", "destination_phone" ], "properties": { "bot_id": { "type": "string" }, "destination_phone": { "type": "string", "description": "E.164, e.g. +14155551234." }, "callback_url": { "type": "string", "format": "uri", "description": "Required only for webhook-enabled keys; forced null for polling-mode keys." }, "callback_secret": { "type": "string", "maxLength": 256, "description": "Shared secret used to HMAC-sign the result callback. Supplied PER REQUEST — it is not stored on your account, so it must be sent on every call. If `callback_url` is set and this is omitted, the callback is delivered UNSIGNED and the response carries a `meta.warnings` entry; an endpoint that verifies signatures will reject it and the result is lost once retries are exhausted." }, "campaign_id": { "type": "integer", "description": "Optional; binds the call to a specific campaign." }, "contact_name": { "type": "string" }, "custom_data": { "type": "object", "additionalProperties": true, "description": "<=16KB serialized; becomes {{placeholders}}. Four keys are reserved and interpreted rather than substituted: `questions` supplies the call's question set (see `CallQuestion`) and is validated when the call is scheduled; `question_source` (`console` | `api`) overrides the agent's Questions-tab setting for this call; `call_guidance` is free-text operator direction for this call only; and `screening_greeting` is the one sentence the agent says if it reaches a call-screening service instead of a person (screening only -- voicemail uses the agent's configured voicemail message). Keys beginning with an underscore are reserved by the platform, are stripped from your payload before it is stored, and are never echoed back on `GET /calls/{call_id}`.", "properties": { "questions": { "type": "array", "description": "The questions this call should ask, in order. Validated at schedule time.", "items": { "$ref": "#/components/schemas/CallQuestion" } }, "question_source": { "type": "string", "enum": [ "console", "api" ], "description": "Per-call override of the agent's Questions tab. `api` means this request is the only source of questions -- no saved or packaged set is used, and omitting `questions` returns 400 `questions_required`. Only these two values are meaningful; anything else is accepted rather than rejected and falls back to `console`." }, "call_guidance": { "type": "string", "description": "Free-text operator direction handed to the agent for this call only, on top of its configured prompt. Use it for call-specific framing (\"this is a verification call, not a sales call\"). It cannot change when the agent starts speaking: the opening line is delivered by the platform before the model runs, so instructions like \"do not speak until they say hello\" have no effect -- use `screening_greeting` and answering-machine detection for that. Truncated at 2000 characters.", "maxLength": 2000, "example": "This is a landlord-reference verification call, not a sales call. Keep it brief and professional." }, "screening_greeting": { "type": "string", "description": "The single sentence the agent says when it reaches a **call-screening service** instead of a person. It then stops and waits silently for a human rather than delivering the full opener, so the real opener is not burned on a screener. Overrides the agent's configured screening response for this call. Truncated at 320 characters. This is the screening path only -- it is NOT used for voicemail: when carrier answering-machine detection reports a machine, the agent leaves the agent's configured voicemail message and hangs up, and screening detection is suppressed for the rest of that call. Because AMD wins when it fires, a call answered by a screener that AMD classifies as a machine will get the voicemail message, not this line.", "maxLength": 320, "example": "Hello, this is Jordan with Bloomfield Mobile Village calling for a landlord reference check on Angelique Marshall." } } }, "scheduled_time": { "type": "string" }, "time_zone": { "type": "string", "default": "UTC" }, "answering_machine_detection": { "type": [ "boolean", "null" ], "description": "Ask the carrier to classify who answered (human vs answering machine) before the agent speaks. The verdict drives the voicemail path at call time and populates `answered_by` on `GET /calls/{id}`. Detection is billed by the carrier and delays the greeting by roughly a second, so it is opt-in per call. OMITTING this field is NOT the same as sending `false`: omission (or an explicit `null`) leaves the platform default for the dial path in place, while `false` explicitly disables detection for this call. Echoed back in the 202 response only when you set it. `true`/`false` are the contract; the strings \"true\"/\"false\"/\"1\"/\"0\" and the integers 1/0 are also accepted. Anything else returns 400 `invalid_amd_flag`." } } }, "CallQuestion": { "type": "object", "description": "One question in a call's question set, sent as an entry of `custom_data.questions`. Extra fields are ignored, so a row round-tripped from your own store (`id`, `original_type`, ...) is harmless.", "required": [ "key", "text" ], "properties": { "key": { "type": "string", "description": "Stable identifier for the answer, unique within the set (case-insensitive). Answers are reported back under this key. The alias `question_key` is accepted by most personas, but the leasing and staffing personas require the literal `key` -- always send `key`, which every persona accepts.", "example": "still_interested" }, "text": { "type": "string", "description": "The question as the agent should ask it. The alias `prompt_text` is accepted by most personas, but the leasing and staffing personas require the literal `text` -- always send `text`, which every persona accepts.", "example": "Are you still interested in the home?" }, "type": { "type": "string", "enum": [ "yes_no", "free_text", "numeric", "scale_1_5" ], "default": "free_text", "description": "Expected answer shape. Unrecognized values degrade to `free_text` rather than failing the call." }, "required": { "type": "boolean", "default": true, "description": "Whether the agent should press for an answer before moving on." }, "sort_order": { "type": "integer", "description": "Explicit ordering. Omit to use the array order." } } }, "CallJob": { "type": "object", "properties": { "call_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending" }, "scheduled_time": { "type": "string" }, "destination_phone": { "type": "string" }, "bot_id": { "type": "string" } } }, "CallJobSummary": { "type": "object", "properties": { "call_id": { "type": "string", "format": "uuid" }, "bot_id": { "type": "string" }, "destination_phone": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "scheduled_time": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "call_duration_seconds": { "type": "integer" }, "disposition": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } } }, "CallJobDetail": { "type": "object", "additionalProperties": true, "description": "Result fields (disposition, outcome, answered_by, transcript_summary, transcript, extracted_data, recording_url, error) appear as the call progresses. All timestamps are UTC ISO-8601 (Z suffix). A field that has no value yet is OMITTED rather than sent as null, so branch on presence.", "properties": { "hold": { "type": "object", "description": "Present only while status is pending/queued AND dispatch is deferred by a compliance gate. Explains why the call has not gone out yet. A hold is informational, not an error: the platform retries on its own and the call dials once the hold clears. That is bounded, though. A safety-net reaper fails a still-queued call outright under either of two rules: one hour past its scheduled time if the calling window for that number is currently OPEN (a row that could be dialing and is not is treated as stuck rather than waiting), or 24 hours past its creation regardless of the window. The one-hour rule bites precisely when nothing window-related is holding the call, which is the case for most of the silent gates listed below. KNOWN GAP: neither reap is reflected here - the reaper updates internal queue state only, so this endpoint keeps reporting queued for a call that has in fact been abandoned; bound your polling by wall-clock age rather than waiting indefinitely for a terminal status. The converse does NOT hold either: absence of `hold` does not by itself mean nothing is gating the call, only that no gate reporting through this field is holding it. `hold` is written by just the two gates whose codes are documented under `code`; every other gate that defers or refuses a call returns before that write is reached, leaving the job queued and silent. Notable examples, deliberately NOT an exhaustive list - new gates join this class by default: a consent-basis deferral; a suppression-list MATCH, which holds indefinitely since a suppressed number will never dial; the suppression check being UNAVAILABLE, a distinct case from a match - if the external screening provider cannot be reached the platform fails closed and does not dial even though the number is not suppressed; the organization-status gate; the PLAN concurrency ceiling; the plan MINUTE limit (blocks on Free once exhausted, overage permitted on paid plans); the CAMPAIGN concurrency ceiling (`max_concurrent_calls`), a distinct ceiling from the plan one that records nothing anywhere when it fires - a call scheduled without a campaign_id runs on an internal per-organization campaign with a ceiling of 10, while a campaign you create yourself defaults to 5 unless you set it explicitly; the agent pinned to the campaign no longer resolving, which stalls every queued call on that campaign rather than one; the campaign no longer being in `running` state, which leaves its queued calls unselected rather than rejected; no caller ID configured for the organization; and a generic dial-initiation failure, retried through the contact rather than the call row and bounded at three initiation failures per rolling 24 hours, after which the contact stops being retried while the call still reads queued. Treat `hold` as an explanation when present, never as an inventory.", "properties": { "code": { "type": "string", "description": "Machine-readable deferral reason, e.g. CALLING_HOURS or FREQUENCY_CAPPED. Branch on this, not on `message`. Deliberately NOT a closed enum - treat an unrecognised code as a generic deferral rather than rejecting it." }, "message": { "type": "string", "description": "Human-readable explanation. Wording is not stable; do not parse it." }, "next_attempt_at": { "type": "string", "format": "date-time", "description": "CALLING_HOURS only, and only when an opening falls within the next 8 days: the next moment the calling window is open, UTC ISO-8601. STRICTLY ADVISORY - do not schedule against it, and do not treat it as a guaranteed lower bound. It is a snapshot computed at read time from the window as it stands at that moment, so re-read it rather than caching it. The call will not usually dial before it, but it can, in two known ways: an operator widening the org window while the call is parked moves the real opening earlier than the value you were handed, and the value is rounded UP to the whole minute, so a window opening at 09:00:30 is reported as 09:01:00 while the dialer may place the call at 09:00:30. Beyond that sub-minute rounding it is never pushed out: the search either finds the first true opening or omits the field, never a later one. OMITTED when no opening is found within the horizon - including the pathological case of a calling window narrower than five minutes, which the coarse search pass can step over entirely - and always omitted for other hold codes, whose clearing time is not a schedule and cannot be predicted." } } }, "call_id": { "type": "string", "format": "uuid" }, "bot_id": { "type": "string" }, "destination_phone": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "scheduled_time": { "type": "string" }, "time_zone": { "type": "string" }, "attempts": { "type": "integer" }, "max_attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "custom_data": { "type": "object", "additionalProperties": true, "description": "The `custom_data` you supplied at schedule time, echoed back." }, "started_at": { "type": "string", "format": "date-time", "description": "Present once the call has started." }, "call_duration_seconds": { "type": "integer" }, "disposition": { "type": "string" }, "outcome": { "type": "string", "description": "Connection-level result. NOTE: `connected` means the line was answered, not that the conversation succeeded -- a call answered by voicemail or a screening service can report `connected` with no answers. Check `answered_by` and `extracted_data` before treating a call as a completed interview." }, "final_intent": { "type": "string" }, "answered_by": { "type": "string", "enum": [ "human", "machine", "screening", "unknown" ], "description": "Who answered. Present once the call has started. `unknown` is a real and expected value, not an error: it means the platform holds no positive evidence either way, most often because answering-machine detection was not requested for the call (see `answering_machine_detection` on POST /calls). This is never inferred from the mere existence of a transcript." }, "answered_by_source": { "type": "string", "enum": [ "amd", "call_status", "voicemail_flow", "screening_detection", "none" ], "description": "What evidence produced `answered_by`, so you can weigh it: `amd` = carrier answering-machine detection, `call_status` = carrier call state, `voicemail_flow` = the agent took its voicemail path, `screening_detection` = the agent recognised a call-screening service, `none` = no evidence (always paired with `unknown`)." }, "completed_at": { "type": "string", "format": "date-time", "description": "Present once the call is completed, failed, or cancelled." }, "transcript_summary": { "type": "string", "deprecated": true, "description": "Model-written precis of the conversation, gated on `calls:read`. NOT CURRENTLY PRODUCED: no pipeline writes this field today (0 of 115 jobs on 2026-08-12), so it is omitted from every response. Do not build on it -- use `transcript` (verbatim, requires `calls:recordings`) or `extracted_data` (structured answers)." }, "transcript": { "type": "string", "description": "Verbatim turn-by-turn transcript. Requires the `calls:recordings` scope, NOT `calls:read` -- it is call content of the same sensitivity class as the audio, so a status-polling key cannot read conversations. Omitted (not an error) for keys without that scope, and until the call completes." }, "extracted_data": { "type": "object", "additionalProperties": true, "description": "Structured answers extracted from the conversation, keyed by question `key`." }, "recording_url": { "type": "string", "format": "uri", "description": "Requires the `calls:recordings` scope." }, "error": { "type": "object", "description": "Present only when `status` is `failed`.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "CallLog": { "type": "object", "properties": { "id": { "type": "integer" }, "campaign_id": { "type": [ "integer", "null" ] }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] } } }, "status": { "type": "string", "enum": [ "queued", "ringing", "in_progress", "completed" ] }, "outcome": { "type": [ "string", "null" ] }, "direction": { "type": "string" }, "duration_seconds": { "type": [ "integer", "null" ] }, "queue_time_seconds": { "type": [ "integer", "null" ] }, "has_recording": { "type": "boolean" }, "has_transcript": { "type": "boolean" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "connected_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Campaign": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "agent_id": { "type": "integer" }, "agent": { "type": [ "object", "null" ], "additionalProperties": true }, "schedule": { "type": "object", "additionalProperties": true }, "dialing": { "type": "object", "additionalProperties": true }, "contacts": { "type": "object", "additionalProperties": true }, "calls": { "type": "object", "additionalProperties": true }, "metadata": {}, "tags": {}, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CampaignCreate": { "type": "object", "required": [ "name", "agent_id" ], "additionalProperties": true, "properties": { "name": { "type": "string" }, "agent_id": { "type": "integer" }, "description": { "type": "string" }, "calling_days": { "type": "integer", "minimum": 0, "maximum": 127, "default": 0, "description": "Day-of-week bitmask (Sun=1, Mon=2 ... Sat=64) that NARROWS the organization's outbound calling window — it can exclude days the org window allows but never add days it forbids. 0 = no campaign-level restriction (the org window governs)." }, "daily_start_time": { "type": [ "string", "null" ], "description": "Earliest dial time of day (HH:MM or HH:MM:SS), evaluated on the same clock as the org window (called-party local time when resolvable, else org timezone). Narrows the org window only — cannot start earlier than the org allows. null = no campaign-level restriction." }, "daily_end_time": { "type": [ "string", "null" ], "description": "Latest dial time of day (HH:MM or HH:MM:SS); must be later than daily_start_time. Narrows the org window only. null = no campaign-level restriction." }, "time_zone": { "type": "string", "default": "UTC", "description": "Stored for reference only — NOT used to evaluate the calling window. The campaign daily window runs on the same clock as the org window: the called party's local time when resolvable, else the organization timezone. Must be a valid timezone identifier (IANA ids and PHP-accepted aliases)." } } }, "CampaignUpdate": { "type": "object", "description": "Whitelisted fields only (name, description, agent_id, schedule_*, dialing/retry settings, caller_id, limits, goals, respect_dnc_list, voicemail_*, metadata, tags).", "additionalProperties": true, "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "agent_id": { "type": "integer" }, "calling_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 127, "description": "Day-of-week bitmask (Sun=1 ... Sat=64) narrowing the organization's outbound calling window. 0 or explicit null = remove the campaign-level day restriction." }, "daily_start_time": { "type": [ "string", "null" ], "description": "Earliest dial time of day (HH:MM or HH:MM:SS), narrowing the org window. Explicit null clears the restriction." }, "daily_end_time": { "type": [ "string", "null" ], "description": "Latest dial time of day (HH:MM or HH:MM:SS); must be later than daily_start_time. Explicit null clears the restriction." }, "time_zone": { "type": "string", "description": "Stored for reference only — NOT used to evaluate the calling window (see CampaignCreate.time_zone). Must be a valid timezone identifier." } } }, "CampaignStats": { "type": "object", "additionalProperties": true, "properties": { "campaign_id": { "type": "integer" }, "status": { "type": "string" }, "contacts": { "type": "object", "additionalProperties": true }, "calls": { "type": "object", "additionalProperties": true }, "outcomes": { "type": "object", "additionalProperties": true }, "estimated_cost_usd": { "type": "number" }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } } }, "Contact": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "phone": { "type": [ "string", "null" ] }, "phone_e164": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "max_attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "ContactResult": { "type": "object", "properties": { "id": { "type": "integer" }, "phone": { "type": "string" }, "status": { "type": "string", "enum": [ "added", "failed" ] }, "dnc": { "type": "boolean" }, "error": { "type": "string" } } }, "DialRequest": { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "description": "Array of phone strings OR objects with a phone field.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "phone": { "type": "string" }, "first_name": { "type": "string" } }, "additionalProperties": true } ] } } } }, "AddContactsRequest": { "type": "object", "description": "Either {contacts:[...]} or a single contact object at the top level.", "properties": { "contacts": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "phone": { "type": "string" }, "phone_number": { "type": "string" } } } } }, "additionalProperties": true }, "TelephonyProvider": { "type": "object", "properties": { "id": { "type": "integer" }, "provider_type": { "type": "string" }, "display_name": { "type": "string" }, "is_byoc": { "type": "boolean" }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" }, "is_validated": { "type": "boolean" }, "last_validated_at": { "type": [ "string", "null" ] }, "validation_error": { "type": [ "string", "null" ] }, "config_schema": { "type": "object", "additionalProperties": true, "description": "Included on single-provider GET." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PhoneNumber": { "type": "object", "properties": { "id": { "type": "integer" }, "phone_number": { "type": "string" }, "provider_id": { "type": "integer" }, "number_type": { "type": "string" }, "country_code": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true }, "caller_id_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "is_default": { "type": "boolean" }, "monthly_cost": { "type": [ "number", "null" ] }, "assigned_to_id": { "type": [ "integer", "null" ] }, "assigned_to_type": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Schedule": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "timezone": { "type": "string" }, "status": { "type": "object", "additionalProperties": true, "description": "Computed open/closed status." } } }, "ScheduleCreate": { "type": "object", "additionalProperties": true, "description": "Fields pass through to BusinessScheduleService::create().", "properties": { "name": { "type": "string" }, "timezone": { "type": "string" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ], "description": "Label for the subscription; defaults to the target host when omitted at creation." }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ], "description": "active = delivering; paused and disabled both stop delivery." }, "description": { "type": [ "string", "null" ] }, "headers": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "HMAC signing secret; returned only on creation." } } } ] }, "WebhookCreate": { "type": "object", "required": [ "url", "events" ], "properties": { "name": { "type": "string", "maxLength": 100, "description": "Optional label; defaults to the target host." }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "call.started", "call.answered", "call.ended", "call.completed", "call.failed", "call.transferred", "campaign.started", "campaign.paused", "campaign.completed", "campaign.failed", "contact.completed", "contact.failed", "transcript.update", "transcript.final", "agent.response", "function.called", "function.result", "sentiment.update", "appointment.booked", "appointment.cancelled", "appointment.rescheduled" ] }, "description": "Webhook event catalog. Scheduling emits `appointment.booked` (on a confirmed booking or an approved pending request), `appointment.cancelled` (cancel or decline), and `appointment.rescheduled`." }, "description": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } } }, "WebhookUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ], "description": "active = delivering; paused and disabled both stop delivery." }, "description": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } } }, "WebhookLog": { "type": "object", "properties": { "id": { "type": "integer" }, "event_type": { "type": "string" }, "status_code": { "type": [ "integer", "null" ] }, "success": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "response_time_ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "DncEntry": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "phone_number": { "type": "string" } } }, "DncAdd": { "type": "object", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string" }, "list_id": { "type": "integer" }, "reason": { "type": "string" }, "notes": { "type": "string" }, "source_reference": { "type": "string" }, "expires_at": { "type": "string", "description": "Parseable date/time." } } }, "UsageSummary": { "type": "object", "properties": { "billing_period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "days_remaining": { "type": "integer" } } }, "usage": { "type": "object", "additionalProperties": true, "properties": { "total_calls": { "type": "integer" }, "total_minutes": { "type": "number" }, "inbound_calls": { "type": "integer" }, "outbound_calls": { "type": "integer" }, "llm_calls": { "type": "integer" }, "nlu_calls": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "tokens_by_source": { "type": "object", "additionalProperties": true }, "estimated_cost_usd": { "type": "number" }, "active_agents": { "type": "integer" }, "knowledge_bases": { "type": "integer" }, "concurrent_calls": { "type": "integer" } } }, "limits": { "type": "object", "properties": { "max_monthly_minutes": { "type": "integer" }, "max_agents": { "type": "integer" }, "max_knowledge_bases": { "type": "integer" }, "max_users": { "type": "integer" } } }, "percentages": { "type": "object", "additionalProperties": { "type": "number" } }, "plan": { "type": "object", "properties": { "type": { "type": "string" }, "status": { "type": "string" } } }, "alerts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "integer" }, "key_id": { "type": "string" }, "key_prefix": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limits": { "type": "object", "properties": { "per_minute": { "type": "integer" }, "per_hour": { "type": "integer" }, "per_day": { "type": "integer" } } }, "is_active": { "type": "boolean" }, "usage_count": { "type": "integer" }, "last_used_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApiKeyCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Subset of the caller key's scopes; validated against PARTNER_SCOPES." }, "rate_limit_per_minute": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 60 }, "rate_limit_per_hour": { "type": "integer", "minimum": 1, "maximum": 50000, "default": 1000 }, "rate_limit_per_day": { "type": "integer", "minimum": 1, "maximum": 500000, "default": 10000 }, "expires_at": { "type": "string", "description": "Must be a future date." } } }, "ApiKeyUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit_per_minute": { "type": "integer", "minimum": 1, "maximum": 1000 }, "rate_limit_per_hour": { "type": "integer", "minimum": 1, "maximum": 50000 }, "rate_limit_per_day": { "type": "integer", "minimum": 1, "maximum": 500000 } } }, "Calendar": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "team_member_name": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "is_default": { "type": "integer", "enum": [ 0, 1 ] }, "is_active": { "type": "integer", "enum": [ 0, 1 ] }, "max_per_day": { "type": "integer", "description": "0 = unlimited." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CalendarCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "team_member_name": { "type": "string" }, "timezone": { "type": "string", "description": "IANA tz; overrides org tz for this calendar." }, "max_per_day": { "type": "integer", "minimum": 0, "maximum": 100, "description": "0 = unlimited." }, "is_default": { "type": "boolean" } } }, "CalendarUpdate": { "type": "object", "description": "Any subset of the mutable calendar fields.", "properties": { "name": { "type": "string", "maxLength": 120 }, "team_member_name": { "type": "string" }, "timezone": { "type": "string" }, "max_per_day": { "type": "integer", "minimum": 0, "maximum": 100 }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" } } }, "AvailabilityRule": { "type": "object", "properties": { "id": { "type": "integer" }, "agent_id": { "type": [ "integer", "null" ] }, "calendar_id": { "type": [ "integer", "null" ] }, "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 = Sunday .. 6 = Saturday (org-local)." }, "start_time": { "type": "string", "example": "09:00" }, "end_time": { "type": "string", "example": "17:00" }, "slot_minutes": { "type": "integer" }, "is_active": { "type": "integer", "enum": [ 0, 1 ] } } }, "AvailabilityRuleCreate": { "type": "object", "required": [ "day_of_week", "start_time", "end_time" ], "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "start_time": { "type": "string", "description": "HH:MM (24h), org-local.", "example": "09:00" }, "end_time": { "type": "string", "description": "HH:MM (24h); must be after start_time.", "example": "17:00" }, "slot_minutes": { "type": "integer", "minimum": 5, "maximum": 240, "default": 30 }, "agent_id": { "type": "integer", "description": "NULL/0 = org-wide." }, "calendar_id": { "type": "integer", "description": "NULL/0 = all calendars." } } }, "AvailabilityException": { "type": "object", "properties": { "id": { "type": "integer" }, "agent_id": { "type": [ "integer", "null" ] }, "calendar_id": { "type": [ "integer", "null" ] }, "exception_date": { "type": "string", "format": "date" }, "start_time": { "type": [ "string", "null" ] }, "end_time": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] } } }, "AvailabilityExceptionCreate": { "type": "object", "required": [ "exception_date" ], "description": "Whole-day blackout (omit both times) or a timed window (both times).", "properties": { "exception_date": { "type": "string", "format": "date" }, "start_time": { "type": "string", "description": "HH:MM (24h); provide with end_time or omit both." }, "end_time": { "type": "string" }, "reason": { "type": "string", "maxLength": 200 }, "agent_id": { "type": "integer" }, "calendar_id": { "type": "integer" } } }, "AvailabilitySlot": { "type": "object", "additionalProperties": true, "properties": { "start": { "type": "string", "format": "date-time", "description": "RFC-3339 with the org-tz offset \u2014 pass this verbatim as an appointment slot_start." }, "end": { "type": "string", "format": "date-time" } } }, "AvailabilityResult": { "type": "object", "properties": { "spoken": { "type": "string", "description": "Voice-agent phrasing of the open times (present for parity with the internal caller)." }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilitySlot" } }, "timezone": { "type": "string" } } }, "Appointment": { "type": "object", "properties": { "id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "attendee_name": { "type": [ "string", "null" ] }, "phone_last_four": { "type": [ "string", "null" ], "description": "Display only \u2014 the full phone is never returned." }, "status": { "type": "string", "enum": [ "confirmed", "cancelled", "completed", "no_show", "pending" ] }, "source": { "type": "string" }, "agent_id": { "type": [ "integer", "null" ] }, "calendar_id": { "type": [ "integer", "null" ] }, "appointment_type_id": { "type": [ "integer", "null" ] }, "location_id": { "type": [ "integer", "null" ] }, "meeting_mode": { "oneOf": [ { "type": "string", "enum": [ "in_person", "virtual" ] }, { "type": "null" } ] }, "contact_id": { "type": [ "integer", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "AppointmentCreate": { "type": "object", "required": [ "slot_start" ], "properties": { "slot_start": { "type": "string", "format": "date-time", "description": "RFC-3339 WITH an explicit offset or Z \u2014 a `start` value from GET /scheduling/availability. Naive strings are rejected (400)." }, "attendee_name": { "type": "string" }, "attendee_email": { "type": "string", "format": "email" }, "attendee_phone": { "type": "string" }, "notes": { "type": "string", "maxLength": 2000 }, "source": { "type": "string", "default": "api", "description": "Booking origin; integrator slugs are normalized server-side." }, "agent_id": { "type": "integer" }, "calendar_id": { "type": "integer" }, "appointment_type_id": { "type": "integer" }, "location_id": { "type": "integer" }, "min_notice_minutes": { "type": "integer", "description": "Override the org minimum-notice for this booking." }, "meeting_mode": { "type": "string", "enum": [ "in_person", "virtual" ] }, "require_approval": { "type": "boolean", "default": false, "description": "When true the slot is HELD as `pending` (no confirmation webhook) until approved." } } }, "AppointmentBooked": { "type": "object", "properties": { "appointment_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "calendar_id": { "type": [ "integer", "null" ] }, "appointment_type_id": { "type": [ "integer", "null" ] }, "location_id": { "type": [ "integer", "null" ] }, "meeting_mode": { "oneOf": [ { "type": "string", "enum": [ "in_person", "virtual" ] }, { "type": "null" } ] }, "source": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed", "pending" ] } } }, "AppointmentReschedule": { "type": "object", "required": [ "slot_start" ], "properties": { "slot_start": { "type": "string", "format": "date-time", "description": "RFC-3339 WITH an explicit offset or Z \u2014 a `start` from GET /scheduling/availability." }, "min_notice_minutes": { "type": "integer" } } }, "AppointmentRescheduled": { "type": "object", "properties": { "appointment_id": { "type": "integer", "description": "The id of the NEW row (a reschedule cancels the old row and creates a replacement)." }, "old_start": { "type": "string", "format": "date-time" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" } } }, "AppointmentCancelled": { "type": "object", "properties": { "appointment_id": { "type": "integer" }, "cancelled": { "type": "object", "properties": { "id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" } } } } }, "AppointmentApprovalResult": { "type": "object", "properties": { "appointment_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed", "cancelled" ] } } }, "AppointmentOutcomeRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "completed", "no_show" ] } } }, "AppointmentOutcomeResult": { "type": "object", "properties": { "appointment_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "completed", "no_show" ] } } }, "CalendarFeedStatus": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The subscribe (ICS) URL when enabled; null otherwise." } } }, "Trigger": { "type": "object", "additionalProperties": true, "description": "Event trigger rule. Fields mirror the event_triggers row; list responses add action_count, single-GET embeds the actions array.", "properties": { "id": { "type": "integer" }, "organization_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_type": { "type": "string" }, "event_source": { "type": [ "string", "null" ] }, "conditions": { "type": [ "object", "array", "null" ], "additionalProperties": true }, "scope_agent_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "scope_campaign_ids": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "rate_limit_count": { "type": [ "integer", "null" ] }, "rate_limit_window": { "type": [ "integer", "null" ] }, "cooldown_seconds": { "type": [ "integer", "null" ] }, "is_enabled": { "type": [ "boolean", "integer" ] }, "priority": { "type": [ "integer", "null" ] }, "run_async": { "type": [ "boolean", "integer" ] }, "stop_on_error": { "type": [ "boolean", "integer" ] }, "action_count": { "type": "integer", "description": "Present on list responses." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TriggerCreate": { "type": "object", "required": [ "name", "event_type" ], "description": "event_type must be one of the values from GET /triggers/events.", "properties": { "name": { "type": "string" }, "event_type": { "type": "string" }, "description": { "type": "string" }, "event_source": { "type": "string" }, "conditions": { "type": [ "object", "array" ], "additionalProperties": true }, "scope_agent_ids": { "type": "array", "items": { "type": "integer" } }, "scope_campaign_ids": { "type": "array", "items": { "type": "integer" } }, "rate_limit_count": { "type": "integer" }, "rate_limit_window": { "type": "integer" }, "cooldown_seconds": { "type": "integer" }, "is_enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "run_async": { "type": "boolean" }, "stop_on_error": { "type": "boolean" } } }, "TriggerUpdate": { "type": "object", "description": "All fields optional; only supplied fields are updated.", "properties": { "name": { "type": "string" }, "event_type": { "type": "string" }, "description": { "type": "string" }, "event_source": { "type": "string" }, "conditions": { "type": [ "object", "array" ], "additionalProperties": true }, "scope_agent_ids": { "type": "array", "items": { "type": "integer" } }, "scope_campaign_ids": { "type": "array", "items": { "type": "integer" } }, "rate_limit_count": { "type": "integer" }, "rate_limit_window": { "type": "integer" }, "cooldown_seconds": { "type": "integer" }, "is_enabled": { "type": "boolean" }, "priority": { "type": "integer" }, "run_async": { "type": "boolean" }, "stop_on_error": { "type": "boolean" } } }, "TriggerAction": { "type": "object", "additionalProperties": true, "description": "A single action attached to a trigger (trigger_actions row).", "properties": { "id": { "type": "integer" }, "trigger_id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "action_type": { "type": "string", "enum": [ "webhook", "flow", "notification", "email", "slack", "sms", "database", "queue", "log" ] }, "config": { "type": "object", "additionalProperties": true }, "input_mapping": { "type": [ "object", "null" ], "additionalProperties": true }, "action_condition": { "type": [ "object", "null" ], "additionalProperties": true }, "execution_order": { "type": [ "integer", "null" ] }, "retry_enabled": { "type": [ "boolean", "integer", "null" ] }, "retry_max_attempts": { "type": [ "integer", "null" ] }, "timeout_ms": { "type": [ "integer", "null" ] }, "is_enabled": { "type": [ "boolean", "integer" ] } } }, "TriggerActionCreate": { "type": "object", "required": [ "action_type", "config" ], "properties": { "action_type": { "type": "string", "enum": [ "webhook", "flow", "notification", "email", "slack", "sms", "database", "queue", "log" ] }, "config": { "type": "object", "additionalProperties": true, "description": "Action-type-specific configuration." }, "name": { "type": "string" }, "input_mapping": { "type": "object", "additionalProperties": true }, "action_condition": { "type": "object", "additionalProperties": true }, "execution_order": { "type": "integer" }, "retry_enabled": { "type": "boolean" }, "retry_max_attempts": { "type": "integer" }, "retry_base_delay_ms": { "type": "integer" }, "retry_backoff_multiplier": { "type": "number" }, "retry_max_delay_ms": { "type": "integer" }, "timeout_ms": { "type": "integer" }, "is_enabled": { "type": "boolean" } } }, "TriggerActionUpdate": { "type": "object", "description": "All fields optional; only supplied fields are updated.", "properties": { "action_type": { "type": "string", "enum": [ "webhook", "flow", "notification", "email", "slack", "sms", "database", "queue", "log" ] }, "config": { "type": "object", "additionalProperties": true }, "name": { "type": "string" }, "input_mapping": { "type": "object", "additionalProperties": true }, "action_condition": { "type": "object", "additionalProperties": true }, "execution_order": { "type": "integer" }, "retry_enabled": { "type": "boolean" }, "retry_max_attempts": { "type": "integer" }, "retry_base_delay_ms": { "type": "integer" }, "retry_backoff_multiplier": { "type": "number" }, "retry_max_delay_ms": { "type": "integer" }, "timeout_ms": { "type": "integer" }, "is_enabled": { "type": "boolean" } } }, "SubOrganization": { "type": "object", "description": "A partner-owned sub-organization (transformed view).", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "plan_type": { "type": [ "string", "null" ] }, "limits": { "type": "object", "properties": { "max_users": { "type": "integer" }, "max_agents": { "type": "integer" }, "max_monthly_minutes": { "type": "integer" }, "max_concurrent_calls": { "type": "integer" } } }, "usage": { "type": "object", "properties": { "current_month_minutes": { "type": "integer" } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "SubOrganizationCreate": { "type": "object", "required": [ "name" ], "description": "plan_type and billing_account are inherited from the parent partner org. Each limit is clamped to the parent plan's ceiling.", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "max_users": { "type": "integer" }, "max_agents": { "type": "integer" }, "max_monthly_minutes": { "type": "integer" }, "max_concurrent_calls": { "type": "integer" }, "max_phone_numbers": { "type": "integer" } } }, "SubOrganizationUpdate": { "type": "object", "description": "All fields optional. Limits are clamped to documented bounds.", "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended", "cancelled" ] }, "max_users": { "type": "integer", "minimum": 1, "maximum": 1000 }, "max_agents": { "type": "integer", "minimum": 1, "maximum": 500 }, "max_monthly_minutes": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "max_concurrent_calls": { "type": "integer", "minimum": 1, "maximum": 500 }, "max_phone_numbers": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "Subscription": { "type": "object", "description": "Current subscription + plan snapshot.", "properties": { "plan_type": { "type": "string" }, "plan_name": { "type": "string" }, "billing_interval": { "type": "string", "example": "monthly" }, "price_monthly": { "type": "number" }, "status": { "type": "string", "example": "active" }, "current_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "pending_plan_change": { "type": [ "string", "null" ] }, "pending_plan_change_at": { "type": [ "string", "null" ], "format": "date-time" }, "payment_provider": { "type": [ "string", "null" ] }, "has_payment_method": { "type": "boolean" } } }, "PaymentMethod": { "type": "object", "description": "A stored payment method on the org's billing account.", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "enum": [ "card", "ach" ] }, "is_default": { "type": [ "boolean", "integer" ] }, "card_brand": { "type": [ "string", "null" ] }, "card_last_four": { "type": [ "string", "null" ] }, "card_exp_month": { "type": [ "integer", "string", "null" ] }, "card_exp_year": { "type": [ "integer", "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "bank_last_four": { "type": [ "string", "null" ] }, "billing_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "PaymentMethodCreate": { "type": "object", "required": [ "payment_token" ], "description": "payment_token is the single-use token from accept.blue hosted tokenization (prefixed `nonce-`, `tkn-`, `pm-`, or `ref-`). Card/bank display fields are optional hints stored for display when the gateway does not return them.", "properties": { "payment_token": { "type": "string" }, "method": { "type": "string", "enum": [ "card", "bank" ], "default": "card" }, "billing_name": { "type": "string" }, "card_brand": { "type": "string" }, "card_last_four": { "type": "string" }, "card_exp_month": { "type": "integer" }, "card_exp_year": { "type": "integer" }, "bank_name": { "type": "string" }, "bank_last_four": { "type": "string" } } }, "Invoice": { "type": "object", "additionalProperties": true, "description": "A billing invoice. List responses return the summary columns below; the single-invoice GET returns the full row plus a decoded line_items array.", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "pending", "paid", "failed", "void", "refunded" ] }, "source": { "type": [ "string", "null" ] }, "created_by_admin": { "type": [ "integer", "null" ] }, "period_start": { "type": [ "string", "null" ], "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "subtotal_cents": { "type": [ "integer", "null" ] }, "tax_cents": { "type": [ "integer", "null" ] }, "total_cents": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "line_items": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Only on the single-invoice GET." } } }, "WidgetTokenResponse": { "type": "object", "description": "A minted widget token and its grants.", "properties": { "token": { "type": "string" }, "expires_in": { "type": "integer", "description": "TTL in seconds." }, "campaign_ids": { "type": "array", "items": { "type": "integer" } }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "SipTrunk": { "type": "object", "description": "A BYOC SIP trunk (telephony_providers row, provider_type=sip).", "properties": { "id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "sip_uri": { "type": "string" }, "sip_auth_type": { "type": [ "string", "null" ] }, "sip_username": { "type": [ "string", "null" ] }, "sip_codecs": { "type": "array", "items": { "type": "string" } }, "sip_transport": { "type": "string", "enum": [ "udp", "tcp", "tls" ] }, "sip_outbound_proxy": { "type": [ "string", "null" ] }, "sip_ip_whitelist": { "type": "array", "items": { "type": "string" } }, "sip_from_domain": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "is_validated": { "type": "boolean" }, "last_validated_at": { "type": [ "string", "null" ] }, "validation_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SipTrunkSave": { "type": "object", "required": [ "sip_uri" ], "description": "Creates the org's SIP trunk if absent, otherwise updates it. sip_password is write-only (never returned).", "properties": { "sip_uri": { "type": "string", "description": "sip:host or sip:host:port." }, "display_name": { "type": "string", "default": "SIP Trunk" }, "sip_auth_type": { "type": "string", "default": "credentials" }, "sip_username": { "type": "string" }, "sip_password": { "type": "string", "writeOnly": true }, "sip_codecs": { "type": "array", "items": { "type": "string" }, "default": [ "PCMU", "PCMA" ] }, "sip_transport": { "type": "string", "enum": [ "udp", "tcp", "tls" ], "default": "udp" }, "sip_outbound_proxy": { "type": "string" }, "sip_ip_whitelist": { "type": "array", "items": { "type": "string" } }, "sip_from_domain": { "type": "string" }, "is_active": { "type": "boolean", "default": true } } }, "TelephonyCall": { "type": "object", "description": "A telephony call (transformed view).", "properties": { "id": { "type": "string", "description": "Call id (UUID)." }, "direction": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "status": { "type": "string" }, "duration_seconds": { "type": [ "integer", "null" ] }, "initiated_at": { "type": [ "string", "null" ], "format": "date-time" }, "answered_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "has_recording": { "type": "boolean" }, "agent_id": { "type": [ "integer", "null" ] }, "campaign_id": { "type": [ "integer", "null" ] }, "hangup_cause": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "TelephonyCallInitiate": { "type": "object", "required": [ "to", "from" ], "description": "`from` must be an active phone number your organization owns through the platform (Truth-in-Caller-ID). `to` is screened against the DNC list and the TCPA calling window before dialing.", "properties": { "to": { "type": "string", "description": "Destination number (E.164)." }, "from": { "type": "string", "description": "Caller-ID number (must be org-owned)." }, "provider_id": { "type": "integer" }, "caller_id_name": { "type": "string" }, "timeout": { "type": "integer", "default": 30 }, "record": { "type": "boolean", "default": false }, "answering_machine_detection": { "type": "boolean", "default": false }, "metadata": { "type": "object", "additionalProperties": true, "description": "Free-form metadata stored on the call record. The `tcpa` key is reserved: the platform overwrites it with the attestation of record for this dial. Only `consent_basis` and `dnc_san` are read from your input, and only if they pass validation; every other key you place under `tcpa` is discarded. A non-object `metadata` value is preserved as `caller_metadata`.", "properties": { "tcpa": { "type": "object", "description": "Per-call TCPA declaration. `acknowledged`, `acknowledged_via` (always `api_terms_of_service`), `acknowledged_at` and `acknowledged_by` (always null on a Bearer path) are set by the platform and ignored if supplied. Omitted fields fall back to nothing -- unlike POST /calls, this endpoint does not read your org's compliance defaults.", "properties": { "consent_basis": { "type": "string", "description": "Legal basis for calling this recipient. Case-insensitive; an unrecognised value is silently dropped rather than rejected, leaving the attestation without a consent basis.", "enum": [ "prior_express_written_consent", "existing_business_relationship", "informational", "b2b", "other" ] }, "dnc_san": { "type": "string", "description": "Your National DNC Registry Subscription Account Number. Must match ^[A-Za-z0-9-]{2,50}$; an invalid value is silently dropped.", "pattern": "^[A-Za-z0-9-]{2,50}$" } } } } } } }, "PartnerNumber": { "type": "object", "properties": { "number": { "type": "string", "description": "E.164 phone number", "example": "+14155551234" }, "provider_number_id": { "type": "string", "description": "Carrier-side number ID; key for DELETE" }, "id": { "type": "integer" }, "status": { "type": "string" }, "bot_id": { "type": "integer", "nullable": true, "description": "Inbound agent answering this number" }, "inbound_context_url": { "type": "string", "nullable": true }, "call_result_url": { "type": "string", "nullable": true }, "webhook_secret_ref": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } } } } }