{ "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 — 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` — 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.", "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" } } ], "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": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:read" ], "description": "Requires one of the following scopes: `sms:read`." } }, "/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" }, "sns_message_id": { "type": [ "string", "null" ] }, "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:write" ], "description": "Requires one of the following scopes: `sms:write`." } }, "/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", "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" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ], "x-required-scopes": [ "sms:read" ], "description": "Requires one of the following scopes: `sms:read`." } }, "/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" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "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 — 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 — 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/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 — 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" }, "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 — 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 — sending SMS/email/Slack messages, calling webhooks, running flows — 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" } } } } } }, "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" }, "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", "enum": [ "blind", "attended" ], "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" ] } } }, "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_role": { "type": [ "string", "null" ], "enum": [ "leasing_agent", "staffing_agent", 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" }, "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" }, "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", null ], "description": "Persona. null clears the role." }, "voicemail_enabled": { "type": "boolean" }, "voicemail_message": { "type": "string" } } }, "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" }, "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", null ], "description": "Persona. null clears the role." }, "voicemail_enabled": { "type": "boolean" }, "voicemail_message": { "type": "string" } } }, "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", "required": [ "bot_id", "destination_phone" ], "properties": { "bot_id": { "type": "string" }, "destination_phone": { "type": "string", "description": "E.164, e.g. +15551234567." }, "callback_url": { "type": "string", "format": "uri", "description": "Required only for webhook-enabled keys; forced null for polling-mode keys." }, "callback_secret": { "type": "string" }, "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}}." }, "scheduled_time": { "type": "string" }, "time_zone": { "type": "string", "default": "UTC" } } }, "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, transcript_summary, extracted_data, recording_url, error) appear as the call progresses.", "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" }, "time_zone": { "type": "string" }, "attempts": { "type": "integer" }, "max_attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "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" } } }, "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" } } }, "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 — 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 — 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 — 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 — 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 } } } } } }