{ "openapi": "3.1.0", "info": { "title": "LumisReach v1 API", "version": "1.0.0", "description": "Programmatic access to the LumisReach voice platform — calls, numbers, caller trust, and brands.", "contact": { "name": "LumisReach", "email": "founders@lumisreach.com" } }, "servers": [ { "url": "https://api.lumisreach.com/api" } ], "tags": [ { "name": "Contacts" }, { "name": "Calls" }, { "name": "Messages" }, { "name": "Emails" }, { "name": "Phone Numbers" }, { "name": "Caller IDs" }, { "name": "Enterprise Registration" }, { "name": "Branded Calling" }, { "name": "Dialer Calls" }, { "name": "SMS" }, { "name": "WebRTC" }, { "name": "Reputation" }, { "name": "Usage" }, { "name": "Account" }, { "name": "Billing" }, { "name": "Documents" }, { "name": "Lincoln AI" }, { "name": "Quick Agent Actions" }, { "name": "Sub-entities" }, { "name": "Video schedules" }, { "name": "Videos" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } }, "doc_url": { "type": "string", "format": "uri" } } } } } } }, "paths": { "/v1": { "get": { "operationId": "v1_get", "tags": ["Account"], "summary": "API status", "description": "Whether the API is up. Needs no API key, touches no data and is never billed, so it suits uptime monitors and a \"test connection\" button. It does not check that your key works: call `GET /v1/me` for that.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "service": { "type": "string" }, "version": { "type": "string", "const": "v1" }, "timestamp": { "type": "string", "description": "Server time (ISO 8601)" }, "docs": { "type": "string" }, "openapi": { "type": "string", "description": "This API's OpenAPI document" } }, "required": ["status", "service", "version", "timestamp", "docs", "openapi"], "additionalProperties": false } } } } } } }, "/v1/account": { "get": { "operationId": "v1_account_get", "tags": ["Account"], "summary": "Current account snapshot", "description": "Plan tier + who the key belongs to + footprint counts. Replaces /v1/voice/account and /v1/dialer/account (which expose whitelabel-dialer-specific fields and are deprecated).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "api_key_id": { "type": "string" }, "plan": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "email": { "type": "string" }, "name": { "type": ["string", "null"] } }, "required": ["id", "email", "name"], "additionalProperties": false }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": ["id", "name", "slug"], "additionalProperties": false }, { "type": "null" } ] }, "footprint": { "type": "object", "properties": { "phone_numbers": { "type": "number" }, "enrolled_reputation_numbers": { "type": "number" }, "own_brand_enterprise": { "type": "boolean" } }, "required": [ "phone_numbers", "enrolled_reputation_numbers", "own_brand_enterprise" ], "additionalProperties": false }, "is_demo": { "type": "boolean" } }, "required": ["api_key_id", "plan", "user", "organization", "footprint", "is_demo"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["account:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/billing": { "get": { "operationId": "v1_billing_get", "tags": ["Billing"], "summary": "Billing summary", "description": "The workspace's plan, prepaid wallet balance (with auto-recharge settings and recent spend), and the current monthly usage period: included voice minutes, SMS segments, emails and AI video credits, how much of each is used, and the overage charged so far (Lincoln AI API turns are never included, so they are all overage). For a per-category breakdown use `GET /v1/billing/usage`. Free: reads are never billed.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "string" }, "subscription_status": { "type": ["string", "null"] }, "is_trial": { "type": "boolean" }, "currency": { "type": "string", "const": "USD" }, "wallet": { "type": "object", "properties": { "balance_usd": { "type": "number", "description": "Prepaid wallet balance that usage beyond the plan draws from" }, "is_paused": { "type": "boolean", "description": "True when the wallet ran dry and billable actions are paused" }, "is_low": { "type": "boolean" }, "auto_recharge": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "threshold_usd": { "type": "number" }, "amount_usd": { "type": "number" }, "last_attempt_failed": { "type": "boolean" } }, "required": ["enabled", "threshold_usd", "amount_usd", "last_attempt_failed"], "additionalProperties": false }, "spend_last_24h_usd": { "type": "number" }, "spend_last_7d_usd": { "type": "number" } }, "required": [ "balance_usd", "is_paused", "is_low", "auto_recharge", "spend_last_24h_usd", "spend_last_7d_usd" ], "additionalProperties": false }, "current_period": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "days_remaining": { "type": "number" } }, "required": ["start", "end", "days_remaining"], "additionalProperties": false }, { "type": "null" } ], "description": "The monthly usage window; null until the first billable usage of the cycle" }, "allowances": { "type": "object", "properties": { "voice_minutes": { "type": "object", "properties": { "used": { "type": "number" }, "included": { "type": "number" }, "remaining": { "type": "number" }, "overage": { "type": "number" }, "percent_used": { "type": "number" } }, "required": ["used", "included", "remaining", "overage", "percent_used"], "additionalProperties": false }, "sms_segments": { "type": "object", "properties": { "used": { "type": "number" }, "included": { "type": "number" }, "remaining": { "type": "number" }, "overage": { "type": "number" }, "percent_used": { "type": "number" } }, "required": ["used", "included", "remaining", "overage", "percent_used"], "additionalProperties": false }, "emails": { "type": "object", "properties": { "used": { "type": "number" }, "included": { "type": "number" }, "remaining": { "type": "number" }, "overage": { "type": "number" }, "percent_used": { "type": "number" } }, "required": ["used", "included", "remaining", "overage", "percent_used"], "additionalProperties": false }, "ai_video_credits": { "type": "object", "properties": { "used": { "type": "number" }, "included": { "type": "number" }, "remaining": { "type": "number" }, "overage": { "type": "number" }, "percent_used": { "type": "number" } }, "required": ["used", "included", "remaining", "overage", "percent_used"], "additionalProperties": false, "description": "1 credit = $1 of AI video at cost" } }, "required": ["voice_minutes", "sms_segments", "emails", "ai_video_credits"], "additionalProperties": false }, "overage_charges_usd": { "type": "object", "properties": { "voice": { "type": "number" }, "sms": { "type": "number" }, "email": { "type": "number" }, "ai_video": { "type": "number" }, "ai_agent": { "type": "number", "description": "Lincoln AI API turns, which no plan includes" }, "total": { "type": "number" } }, "required": ["voice", "sms", "email", "ai_video", "ai_agent", "total"], "additionalProperties": false } }, "required": [ "plan", "subscription_status", "is_trial", "currency", "wallet", "current_period", "allowances", "overage_charges_usd" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["usage:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/billing/events": { "get": { "operationId": "v1_billing_events_get", "tags": ["Billing"], "summary": "List billing events", "description": "Every billable usage event of the current usage period, newest first: each call, text, email, AI video and Lincoln AI API turn with its direction, the other party, quantity, price, whether the plan's allowance covered it, whether a Quick Agent Action produced it, and its `source`: `api` when an API key (REST or MCP) produced the charge (with the key's name), `dashboard` otherwise. Quick Agent emails, iMessages and chat messages are listed as `quick_message`. Filter with `usage_type` and `source`; page with `meta.cursor`. Free: reads are never billed.", "parameters": [ { "name": "usage_type", "in": "query", "required": false, "schema": { "description": "Only this kind of usage", "type": "string", "enum": ["voice", "sms", "email", "ai_video", "ai_agent"] } }, { "name": "source", "in": "query", "required": false, "schema": { "description": "Only what API keys (REST or MCP) produced, or only what the dashboard did", "type": "string", "enum": ["api", "dashboard"] } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 30, "description": "Page size (default 30, max 100)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "`meta.cursor` from the previous page", "type": "string", "pattern": "^\\d+$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "usage_type": { "type": "string", "enum": ["voice", "sms", "email", "ai_video", "ai_agent", "quick_message"], "description": "`quick_message`: a Quick Agent email, iMessage, Slack or Discord message; see `channel`" }, "channel": { "anyOf": [ { "type": "string", "enum": ["email", "imessage", "slack", "discord"] }, { "type": "null" } ] }, "direction": { "anyOf": [ { "type": "string", "enum": ["inbound", "outbound"] }, { "type": "null" } ] }, "counterparty": { "description": "The other phone number or email address", "type": ["string", "null"] }, "quantity": { "type": "number" }, "unit": { "type": "string", "description": "second (voice), segment (SMS), email, cent (AI video, Lincoln AI API), message (quick message)" }, "price_usd": { "type": "number" }, "included_in_plan": { "type": "boolean" }, "triggered_by": { "type": ["string", "null"] }, "quick_action": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["ai_call", "ai_text", "text"] }, "source": { "type": "string", "enum": ["api", "dashboard"] } }, "required": ["kind", "source"], "additionalProperties": false }, { "type": "null" } ] }, "source": { "type": "string", "enum": ["api", "dashboard"], "description": "`api` when an API key (REST or MCP) produced the charge" }, "api_key_name": { "description": "The API key's name, for an API charge", "type": ["string", "null"] }, "created_at": { "type": "string" } }, "required": [ "id", "usage_type", "channel", "direction", "counterparty", "quantity", "unit", "price_usd", "included_in_plan", "triggered_by", "quick_action", "source", "api_key_name", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "total_results": { "type": "number" }, "page_size": { "type": "number" } }, "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["usage:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/billing/usage": { "get": { "operationId": "v1_billing_usage_get", "tags": ["Billing"], "summary": "Usage and charges by category", "description": "Usage and what the wallet was charged, split by category and subcategory: voice (outbound calls, inbound calls, branded caller ID), SMS (sent, received, MMS sent, MMS received), email, Quick Agent Actions (AI calls, AI text conversations, single texts, emails), iMessage, AI video (one charge per video), Lincoln AI API turns, lead enrichment and other. Every subcategory is always listed, zeros included. Defaults to the current usage period; pass `start` and/or `end` (ISO 8601, at most 366 days apart) for any other range. `charged_usd` is what was actually billed, so usage inside the plan's included allowance shows $0. Free: reads are never billed.", "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "description": "Inclusive start (ISO 8601). Defaults to the start of the current usage period.", "type": "string" } }, { "name": "end", "in": "query", "required": false, "schema": { "description": "Exclusive end (ISO 8601). Defaults to the end of the current period, or now when `start` is set.", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "currency": { "type": "string", "const": "USD" }, "total_charged_usd": { "type": "number" }, "credits_added_usd": { "type": "object", "properties": { "total": { "type": "number" }, "by_source": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "purchase, auto_recharge, plan_included, transfer, committed_budget" } }, "required": ["total", "by_source"], "additionalProperties": false }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "voice", "sms", "email", "quick_actions", "imessage", "ai_video", "ai_agent", "lead_enrichment", "other" ] }, "label": { "type": "string" }, "charged_usd": { "type": "number" }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "subcategory": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "number", "description": "Calls, messages, videos, Lincoln AI turns or charges" }, "quantity": { "type": "number", "description": "Amount used, in `unit`" }, "unit": { "type": "string" }, "charged_usd": { "type": "number", "description": "What the wallet was billed. Usage inside the plan's included allowance is $0." } }, "required": [ "subcategory", "label", "count", "quantity", "unit", "charged_usd" ], "additionalProperties": false } } }, "required": ["category", "label", "charged_usd", "subcategories"], "additionalProperties": false } } }, "required": [ "start", "end", "currency", "total_charged_usd", "credits_added_usd", "categories" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["usage:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/brand": { "get": { "operationId": "v1_caller_trust_brand_get", "tags": ["Branded Calling"], "summary": "Retrieve the caller's Display Identity Record (brand)", "description": "Returns the display name, logo, and call reason shown on branded calls. Pre-Branded-Calling-GA, this reflects the local draft state.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "call_reason": { "type": "string" }, "logo_url": { "type": ["string", "null"] }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "submitted_at": { "type": ["string", "null"] }, "approved_at": { "type": ["string", "null"] } }, "required": [ "id", "display_name", "call_reason", "logo_url", "status", "rejection_reasons", "submitted_at", "approved_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read", "brand:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "put": { "operationId": "v1_caller_trust_brand_put", "tags": ["Branded Calling"], "summary": "Save (or update) the Display Identity Record draft", "description": "Persists the brand display name + call reason against the caller's enterprise. Saved as DRAFT until `POST /v1/caller-trust/brand/submit` flips it to PENDING_SUBMIT (which is then batch-pushed to the carrier by a nightly worker once Branded Calling launches).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 64 }, "call_reason": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": ["display_name", "call_reason"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "call_reason": { "type": "string" }, "status": { "type": "string" } }, "required": ["id", "display_name", "call_reason", "status"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["brand:write", "caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/brand/submit": { "post": { "operationId": "v1_caller_trust_brand_submit_post", "tags": ["Branded Calling"], "summary": "Submit the brand profile for vetting", "description": "Flips the DIR status to PENDING_SUBMIT. The actual push to the carrier happens via the nightly cron once Branded Calling is enabled. Requires `display_name`, `call_reason`, and `logo_url` to all be set.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": ["string", "null"] } }, "required": ["id", "status", "submitted_at"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["brand:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/documents": { "post": { "operationId": "v1_caller_trust_documents_post", "tags": ["Documents"], "summary": "Upload a document (e.g. signed LOA)", "description": "Uploads a base64-encoded PDF to the Telnyx Documents API. Returns a document ID that can be passed to the reputation enable endpoint. Documents expire after 30 minutes if not linked to a service — upload immediately before enabling reputation.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "file_base64": { "type": "string", "minLength": 1 }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "customer_reference": { "type": "string", "maxLength": 255 } }, "required": ["file_base64", "filename"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "document_id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": ["string", "null"] }, "status": { "type": ["string", "null"] } }, "required": ["document_id", "filename", "content_type", "status"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/documents/{id}": { "get": { "operationId": "v1_caller_trust_documents_id_get", "tags": ["Documents"], "summary": "Get document status", "description": "Returns metadata for a previously uploaded document, including its verification status and antivirus scan status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "document_id": { "type": "string" }, "filename": { "type": ["string", "null"] }, "content_type": { "type": ["string", "null"] }, "status": { "type": ["string", "null"] }, "av_scan_status": { "type": ["string", "null"] }, "sha256": { "type": ["string", "null"] } }, "required": [ "document_id", "filename", "content_type", "status", "av_scan_status", "sha256" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/enterprise": { "get": { "operationId": "v1_caller_trust_enterprise_get", "tags": ["Enterprise Registration"], "summary": "Get the caller's enterprise registration (deprecated)", "description": "**Deprecated** — use `GET /v1/caller-trust/enterprises` instead for multi-enterprise support. Returns the first own-brand enterprise record if one has been registered, or null otherwise.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "role_type": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": ["string", "null"] }, "loa_document_id": { "type": ["string", "null"] } }, "required": [ "id", "telnyx_enterprise_id", "legal_name", "dba", "role_type", "status", "rejection_reasons", "synced_at", "loa_document_id" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_caller_trust_enterprise_post", "tags": ["Enterprise Registration"], "summary": "Create or update the caller's enterprise registration draft (deprecated)", "description": "**Deprecated** — use `POST /v1/caller-trust/enterprises` to create new enterprises. Idempotent upsert of the own-brand enterprise registration as DRAFT. No carrier-side calls are made here — submission to Telnyx happens in a separate sign-and-submit step.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 3, "maxLength": 64 }, "dba": { "type": "string", "minLength": 1, "maxLength": 255 }, "organization_type": { "type": "string", "enum": ["COMMERCIAL", "GOVERNMENT", "NON_PROFIT"] }, "country_code": { "default": "US", "type": "string", "minLength": 2, "maxLength": 2 }, "website": { "type": "string", "minLength": 1, "maxLength": 255 }, "fein": { "type": "string", "minLength": 9, "maxLength": 20 }, "industry": { "type": "string", "enum": [ "accounting", "finance", "billing", "collections", "business", "charity", "nonprofit", "communications", "telecom", "customer service", "support", "delivery", "shipping", "logistics", "education", "financial", "banking", "government", "public", "healthcare", "health", "pharmacy", "medical", "insurance", "legal", "law", "notifications", "scheduling", "real estate", "property", "retail", "ecommerce", "sales", "marketing", "software", "technology", "tech", "media", "surveys", "market research", "travel", "hospitality", "hotel" ] }, "jurisdiction_of_incorporation": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "GU", "MP", "PR", "VI" ] }, "number_of_employees": { "type": "string", "enum": [ "SIZE_1_10", "SIZE_11_50", "SIZE_51_200", "SIZE_201_500", "SIZE_501_2000", "SIZE_2001_10000", "SIZE_10001_PLUS" ] }, "organization_legal_type": { "type": "string", "enum": ["CORPORATION", "LLC", "PARTNERSHIP", "NONPROFIT", "OTHER"] }, "organization_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "job_title": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 } }, "required": ["first_name", "last_name", "email", "job_title", "phone"], "additionalProperties": false }, "billing_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone_number": { "type": "string", "minLength": 1 } }, "required": ["first_name", "last_name", "email", "phone_number"], "additionalProperties": false }, "organization_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": ["string", "null"] } }, "required": ["country", "administrative_area", "city", "postal_code", "street_address"], "additionalProperties": false }, "billing_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": ["string", "null"] } }, "required": ["country", "administrative_area", "city", "postal_code", "street_address"], "additionalProperties": false } }, "required": [ "legal_name", "dba", "organization_type", "country_code", "website", "fein", "industry", "jurisdiction_of_incorporation", "number_of_employees", "organization_legal_type", "organization_contact", "billing_contact", "organization_address", "billing_address" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "role_type": { "type": "string" } }, "required": ["id", "legal_name", "dba", "status", "role_type"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_caller_trust_enterprise_delete", "tags": ["Enterprise Registration"], "summary": "Delete the caller's enterprise registration (deprecated)", "description": "**Deprecated** — use `DELETE /v1/caller-trust/enterprises/{id}` instead. Deletes the first own-brand enterprise registration. DRAFT records that were never submitted to Telnyx are removed directly. Active records are torn down on Telnyx (enterprise + reputation) and marked DELETED locally.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": ["id", "deleted"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/generate-loa": { "post": { "operationId": "v1_caller_trust_enterprise_generate_loa_post", "tags": ["Enterprise Registration"], "summary": "Generate LOA PDF for hand-signing (deprecated)", "description": "**Deprecated** — use `POST /v1/caller-trust/enterprises/{id}/generate-loa` instead. Generates a Letter of Authorization PDF pre-filled with enterprise data and a blank hand-signature line. Enterprise must have been submitted to Telnyx first (has telnyx_enterprise_id).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["signer_full_name", "signer_email", "signer_title"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "pdf_base64": { "type": "string" }, "filename": { "type": "string" } }, "required": ["pdf_base64", "filename"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/resign": { "post": { "operationId": "v1_caller_trust_enterprise_resign_post", "tags": ["Enterprise Registration"], "summary": "Re-sign the LOA for an enterprise (deprecated)", "description": "**Deprecated** — use `POST /v1/caller-trust/enterprises/{id}/resign` instead. Use when the on-file LOA needs to be replaced. Replaces the LOA on Telnyx; the old LoaSignature row is preserved for audit. Status resets to PENDING_VETTING.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": ["string", "null"] }, "loa_document_id": { "type": ["string", "null"] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": ["string", "null"] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "telnyx_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/sign-and-submit": { "post": { "operationId": "v1_caller_trust_enterprise_sign_and_submit_post", "tags": ["Enterprise Registration"], "summary": "Sign LOA + submit enterprise to carrier (deprecated)", "description": "**Deprecated** — use `POST /v1/caller-trust/enterprises/{id}/sign-and-submit` instead. DRAFT -> PENDING_VETTING in one call. Generates + signs the LOA PDF, uploads it to Telnyx, creates the carrier enterprise record, and enables Number Reputation for it.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": ["string", "null"] }, "loa_document_id": { "type": ["string", "null"] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": ["string", "null"] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "telnyx_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprise/submit": { "post": { "operationId": "v1_caller_trust_enterprise_submit_post", "tags": ["Enterprise Registration"], "summary": "Submit enterprise to Telnyx (deprecated)", "description": "**Deprecated** — use `POST /v1/caller-trust/enterprises/{id}/submit` instead. Accepts Number Reputation Terms of Service and creates the enterprise on Telnyx. Does NOT sign an LOA or enable reputation — those are separate steps.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" } }, "required": ["id", "telnyx_enterprise_id", "legal_name", "dba", "status"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprises": { "get": { "operationId": "v1_caller_trust_enterprises_get", "tags": ["Enterprise Registration"], "summary": "List enterprise registrations", "description": "Returns all own-brand enterprise registrations for the caller. Does not include the Lumis Laboratories umbrella enterprise.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "role_type": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": ["string", "null"] }, "loa_document_id": { "type": ["string", "null"] }, "created_at": { "type": "string" } }, "required": [ "id", "telnyx_enterprise_id", "legal_name", "dba", "role_type", "status", "rejection_reasons", "synced_at", "loa_document_id", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_caller_trust_enterprises_post", "tags": ["Enterprise Registration"], "summary": "Create a new enterprise registration draft", "description": "Always creates a new DRAFT enterprise registration (never upserts). Multiple enterprises per account are supported. No carrier-side calls are made here — submission to Telnyx happens via the sign-and-submit endpoint.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 3, "maxLength": 64 }, "dba": { "type": "string", "minLength": 1, "maxLength": 255 }, "organization_type": { "type": "string", "enum": ["COMMERCIAL", "GOVERNMENT", "NON_PROFIT"] }, "country_code": { "default": "US", "type": "string", "minLength": 2, "maxLength": 2 }, "website": { "type": "string", "minLength": 1, "maxLength": 255 }, "fein": { "type": "string", "minLength": 9, "maxLength": 20 }, "industry": { "type": "string", "enum": [ "accounting", "finance", "billing", "collections", "business", "charity", "nonprofit", "communications", "telecom", "customer service", "support", "delivery", "shipping", "logistics", "education", "financial", "banking", "government", "public", "healthcare", "health", "pharmacy", "medical", "insurance", "legal", "law", "notifications", "scheduling", "real estate", "property", "retail", "ecommerce", "sales", "marketing", "software", "technology", "tech", "media", "surveys", "market research", "travel", "hospitality", "hotel" ] }, "jurisdiction_of_incorporation": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "GU", "MP", "PR", "VI" ] }, "number_of_employees": { "type": "string", "enum": [ "SIZE_1_10", "SIZE_11_50", "SIZE_51_200", "SIZE_201_500", "SIZE_501_2000", "SIZE_2001_10000", "SIZE_10001_PLUS" ] }, "organization_legal_type": { "type": "string", "enum": ["CORPORATION", "LLC", "PARTNERSHIP", "NONPROFIT", "OTHER"] }, "organization_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "job_title": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 } }, "required": ["first_name", "last_name", "email", "job_title", "phone"], "additionalProperties": false }, "billing_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone_number": { "type": "string", "minLength": 1 } }, "required": ["first_name", "last_name", "email", "phone_number"], "additionalProperties": false }, "organization_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": ["string", "null"] } }, "required": ["country", "administrative_area", "city", "postal_code", "street_address"], "additionalProperties": false }, "billing_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": ["string", "null"] } }, "required": ["country", "administrative_area", "city", "postal_code", "street_address"], "additionalProperties": false } }, "required": [ "legal_name", "dba", "organization_type", "country_code", "website", "fein", "industry", "jurisdiction_of_incorporation", "number_of_employees", "organization_legal_type", "organization_contact", "billing_contact", "organization_address", "billing_address" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "role_type": { "type": "string" }, "created_at": { "type": "string" } }, "required": ["id", "legal_name", "dba", "status", "role_type", "created_at"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/caller-trust/enterprises/{id}": { "get": { "operationId": "v1_caller_trust_enterprises_id_get", "tags": ["Enterprise Registration"], "summary": "Get enterprise by ID", "description": "Returns a specific enterprise registration by its ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "role_type": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": ["string", "null"] }, "loa_document_id": { "type": ["string", "null"] }, "created_at": { "type": "string" } }, "required": [ "id", "telnyx_enterprise_id", "legal_name", "dba", "role_type", "status", "rejection_reasons", "synced_at", "loa_document_id", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_caller_trust_enterprises_id_patch", "tags": ["Enterprise Registration"], "summary": "Update a DRAFT enterprise registration", "description": "Updates fields on a DRAFT enterprise. Rejects updates to enterprises that have left DRAFT status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "legal_name": { "type": "string", "minLength": 3, "maxLength": 64 }, "dba": { "type": "string", "minLength": 1, "maxLength": 255 }, "organization_type": { "type": "string", "enum": ["COMMERCIAL", "GOVERNMENT", "NON_PROFIT"] }, "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "website": { "type": "string", "minLength": 1, "maxLength": 255 }, "fein": { "type": "string", "minLength": 9, "maxLength": 20 }, "industry": { "type": "string", "enum": [ "accounting", "finance", "billing", "collections", "business", "charity", "nonprofit", "communications", "telecom", "customer service", "support", "delivery", "shipping", "logistics", "education", "financial", "banking", "government", "public", "healthcare", "health", "pharmacy", "medical", "insurance", "legal", "law", "notifications", "scheduling", "real estate", "property", "retail", "ecommerce", "sales", "marketing", "software", "technology", "tech", "media", "surveys", "market research", "travel", "hospitality", "hotel" ] }, "jurisdiction_of_incorporation": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "GU", "MP", "PR", "VI" ] }, "number_of_employees": { "type": "string", "enum": [ "SIZE_1_10", "SIZE_11_50", "SIZE_51_200", "SIZE_201_500", "SIZE_501_2000", "SIZE_2001_10000", "SIZE_10001_PLUS" ] }, "organization_legal_type": { "type": "string", "enum": ["CORPORATION", "LLC", "PARTNERSHIP", "NONPROFIT", "OTHER"] }, "organization_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "job_title": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 } }, "required": ["first_name", "last_name", "email", "job_title", "phone"], "additionalProperties": false }, "billing_contact": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone_number": { "type": "string", "minLength": 1 } }, "required": ["first_name", "last_name", "email", "phone_number"], "additionalProperties": false }, "organization_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": ["string", "null"] } }, "required": ["country", "administrative_area", "city", "postal_code", "street_address"], "additionalProperties": false }, "billing_address": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "administrative_area": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postal_code": { "type": "string", "minLength": 1 }, "street_address": { "type": "string", "minLength": 1 }, "extended_address": { "type": ["string", "null"] } }, "required": ["country", "administrative_area", "city", "postal_code", "street_address"], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "role_type": { "type": "string" } }, "required": ["id", "legal_name", "dba", "status", "role_type"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_caller_trust_enterprises_id_delete", "tags": ["Enterprise Registration"], "summary": "Delete enterprise by ID", "description": "Deletes a specific enterprise registration. DRAFT records that were never submitted to Telnyx are removed directly. Active records are torn down on Telnyx and marked DELETED locally.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": ["id", "deleted"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprises/{id}/generate-loa": { "post": { "operationId": "v1_caller_trust_enterprises_id_generate_loa_post", "tags": ["Enterprise Registration"], "summary": "Generate LOA PDF for enterprise (by ID)", "description": "Generates a Letter of Authorization PDF pre-filled with the specified enterprise's data and a blank hand-signature line. Enterprise must have been submitted to Telnyx first (has telnyx_enterprise_id).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["signer_full_name", "signer_email", "signer_title"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "pdf_base64": { "type": "string" }, "filename": { "type": "string" } }, "required": ["pdf_base64", "filename"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprises/{id}/resign": { "post": { "operationId": "v1_caller_trust_enterprises_id_resign_post", "tags": ["Enterprise Registration"], "summary": "Re-sign LOA for enterprise (by ID)", "description": "Use when the on-file LOA needs to be replaced for a specific enterprise. Replaces the LOA on Telnyx; the old LoaSignature row is preserved for audit. Status resets to PENDING_VETTING.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": ["string", "null"] }, "loa_document_id": { "type": ["string", "null"] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": ["string", "null"] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "telnyx_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprises/{id}/sign-and-submit": { "post": { "operationId": "v1_caller_trust_enterprises_id_sign_and_submit_post", "tags": ["Enterprise Registration"], "summary": "Sign LOA + submit enterprise to carrier (by ID)", "description": "DRAFT -> PENDING_VETTING in one call. Resolves the enterprise by path parameter ID. Generates + signs the LOA PDF, uploads it to Telnyx, creates the carrier enterprise record, and enables Number Reputation.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "signer_full_name": { "type": "string", "minLength": 2, "maxLength": 255 }, "signer_email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "signer_title": { "type": "string", "minLength": 1, "maxLength": 255 }, "consent_acknowledged_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "confirm_carrier_commit": { "type": "string", "const": "I understand this submits to the carrier" } }, "required": [ "signer_full_name", "signer_email", "signer_title", "consent_acknowledged_at", "confirm_carrier_commit" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "synced_at": { "type": ["string", "null"] }, "loa_document_id": { "type": ["string", "null"] }, "reputation": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": ["string", "null"] } }, "required": [ "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "telnyx_enterprise_id", "legal_name", "dba", "status", "rejection_reasons", "synced_at", "loa_document_id", "reputation" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/enterprises/{id}/submit": { "post": { "operationId": "v1_caller_trust_enterprises_id_submit_post", "tags": ["Enterprise Registration"], "summary": "Submit enterprise to Telnyx (by ID)", "description": "Accepts Number Reputation Terms of Service and creates the enterprise on Telnyx for the specified enterprise ID. Does NOT sign an LOA or enable reputation — those are separate steps.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "telnyx_enterprise_id": { "type": ["string", "null"] }, "legal_name": { "type": "string" }, "dba": { "type": "string" }, "status": { "type": "string" } }, "required": ["id", "telnyx_enterprise_id", "legal_name", "dba", "status"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/reputation": { "get": { "operationId": "v1_caller_trust_reputation_get", "tags": ["Reputation"], "summary": "Get Number Reputation enrollment settings", "description": "Status + check frequency for the caller's enterprise-level reputation monitoring. Returns null when the caller is on the umbrella (no per-enterprise settings).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": ["string", "null"] } }, "required": [ "enterprise_id", "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_caller_trust_reputation_post", "tags": ["Reputation"], "summary": "Enable Number Reputation monitoring", "description": "Enables (or re-enables) enterprise-level reputation monitoring via Telnyx/Hiya. Requires an enterprise that has been submitted to the carrier (has a telnyx_enterprise_id) and has an LOA document on file. Idempotent on REJECTED status — calling this after rejection replaces the rejected record with a fresh PENDING one.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "check_frequency": { "type": "string", "enum": ["business_daily", "daily", "weekly", "biweekly", "monthly", "never"] }, "loa_document_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "status": { "type": "string" }, "check_frequency": { "type": "string" }, "rejection_reasons": { "type": "array", "items": { "type": "string" } }, "last_synced_at": { "type": ["string", "null"] } }, "required": [ "enterprise_id", "status", "check_frequency", "rejection_reasons", "last_synced_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } }, "patch": { "operationId": "v1_caller_trust_reputation_patch", "tags": ["Reputation"], "summary": "Update reputation check frequency", "description": "Changes how often Telnyx refreshes spam scores for enrolled numbers. Each refresh is billed per number, so this is a cost lever. Only works when reputation status is APPROVED.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "check_frequency": { "type": "string", "enum": ["business_daily", "daily", "weekly", "biweekly", "monthly", "never"] } }, "required": ["check_frequency"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "status": { "type": "string" }, "check_frequency": { "type": "string" } }, "required": ["enterprise_id", "status", "check_frequency"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } }, "delete": { "operationId": "v1_caller_trust_reputation_delete", "tags": ["Reputation"], "summary": "Disable Number Reputation monitoring", "description": "Disables reputation monitoring for the caller's enterprise. Only works when the current status is APPROVED. All enrolled numbers will stop being monitored.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "enterprise_id": { "type": "string" }, "disabled": { "type": "boolean", "const": true } }, "required": ["enterprise_id", "disabled"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/reputation/numbers": { "get": { "operationId": "v1_caller_trust_reputation_numbers_get", "tags": ["Reputation"], "summary": "List reputation scores for every enrolled number", "description": "Returns per-phone spam risk + component scores for every number the caller owns that's enrolled under an enterprise (either umbrella or own-brand).", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string" }, "enterprise_id": { "type": "string" }, "spam_risk": { "type": ["string", "null"] }, "spam_category": { "type": ["string", "null"] }, "maturity_score": { "type": ["number", "null"] }, "connection_score": { "type": ["number", "null"] }, "engagement_score": { "type": ["number", "null"] }, "sentiment_score": { "type": ["number", "null"] }, "last_refreshed_at": { "type": ["string", "null"] } }, "required": [ "phone_number", "enterprise_id", "spam_risk", "spam_category", "maturity_score", "connection_score", "engagement_score", "sentiment_score", "last_refreshed_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_caller_trust_reputation_numbers_post", "tags": ["Reputation"], "summary": "Enroll phone numbers in reputation monitoring", "description": "Enrolls one or more phone numbers in Telnyx Number Reputation monitoring. Numbers must belong to the caller and be in US E.164 format. Enrollment is idempotent — re-enrolling an already-enrolled number is a no-op.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "phone_numbers": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^\\+1\\d{10}$" } } }, "required": ["phone_numbers"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "enrolled": { "type": "number" }, "phone_numbers": { "type": "array", "items": { "type": "string" } } }, "required": ["enrolled", "phone_numbers"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/caller-trust/reputation/numbers/{phone}": { "get": { "operationId": "v1_caller_trust_reputation_numbers_phone_get", "tags": ["Reputation"], "summary": "Get reputation scores for a phone number", "description": "Returns Hiya-sourced spam risk + 0-100 component scores. Passing `fresh=true` forces a billed live query (rate-limited to 1/day/number).", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fresh", "in": "query", "required": true, "schema": {} } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_number": { "type": "string" }, "enterprise_id": { "type": ["string", "null"] }, "spam_risk": { "type": ["string", "null"] }, "spam_category": { "type": ["string", "null"] }, "maturity_score": { "type": ["number", "null"] }, "connection_score": { "type": ["number", "null"] }, "engagement_score": { "type": ["number", "null"] }, "sentiment_score": { "type": ["number", "null"] }, "last_refreshed_at": { "type": ["string", "null"] } }, "required": [ "phone_number", "enterprise_id", "spam_risk", "spam_category", "maturity_score", "connection_score", "engagement_score", "sentiment_score", "last_refreshed_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_caller_trust_reputation_numbers_phone_delete", "tags": ["Reputation"], "summary": "Disenroll a phone number from reputation monitoring", "description": "Removes a phone number from Telnyx Number Reputation monitoring. The number must be currently enrolled. Cached reputation scores are deleted.", "parameters": [ { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_number": { "type": "string" }, "disenrolled": { "type": "boolean", "const": true } }, "required": ["phone_number", "disenrolled"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["caller_trust:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/calls": { "get": { "operationId": "v1_calls_get", "tags": ["Calls"], "summary": "List calls", "description": "The workspace's calls, most recent first: inbound and outbound, AI and human, on both LumisReach voice stacks, including Quick AI Phone Calls. Each has its full transcript (plain text and speaker-labelled turns), AI summary, tags, status and duration, plus a `recording_url` to download the audio. Narrow it to one person with `contact_id` or `phone_number`, and filter by `direction`, `status` or a `created_after` / `created_before` window. Free: reads are never billed.", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "schema": { "description": "A contact id (from `GET /v1/contacts`). Its phone number / email is used.", "type": "string", "minLength": 1 } }, { "name": "phone_number", "in": "query", "required": false, "schema": { "description": "The person's phone number, E.164 (+14155550123)", "type": "string", "minLength": 3 } }, { "name": "direction", "in": "query", "required": false, "schema": { "description": "Only `inbound` (they reached you) or `outbound` (you reached them)", "type": "string", "enum": ["inbound", "outbound"] } }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Only calls in this status: `completed`, `voicemail`, `failed`, `busy`, `canceled`, `in_progress`, `ringing` or `queued`", "type": "string", "enum": [ "QUEUED", "RINGING", "IN_PROGRESS", "COMPLETED", "FAILED", "BUSY", "VOICEMAIL", "CANCELED" ] } }, { "name": "created_after", "in": "query", "required": false, "schema": { "description": "Only items created at or after this time (ISO 8601)" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "description": "Only items created before this time (ISO 8601)" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "`meta.cursor` from the previous page", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "anyOf": [ { "type": "string", "enum": ["inbound", "outbound"] }, { "type": "null" } ] }, "status": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" }, "started_at": { "type": ["string", "null"] }, "ended_at": { "type": ["string", "null"] }, "duration_seconds": { "type": ["number", "null"] }, "summary": { "type": ["string", "null"] }, "transcript": { "type": ["string", "null"] }, "transcript_turns": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string", "enum": ["agent", "person"] }, "text": { "type": "string" }, "seconds_from_start": { "type": ["number", "null"] } }, "required": ["speaker", "text", "seconds_from_start"], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "string", "enum": [ "booking_requested", "callback_requested", "complaint", "purchase_interest", "interested", "qualified", "not_interested", "transferred" ] } }, "has_recording": { "type": "boolean" }, "recording_url": { "description": "`GET` it with your API key to download the audio (`GET /v1/calls/{id}/recording`). Null when the call has no recording.", "type": ["string", "null"] }, "created_at": { "type": "string" } }, "required": [ "id", "direction", "status", "from_number", "to_number", "started_at", "ended_at", "duration_seconds", "summary", "transcript", "transcript_turns", "tags", "has_recording", "recording_url", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["calls:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/calls/dial": { "post": { "operationId": "v1_calls_dial_post", "tags": ["Calls"], "summary": "Place an outbound call from one of your numbers to a destination", "description": "Initiates a Call Control session via our Tier-1 carrier. Returns immediately with the call_id; subscribe to the webhook for status updates. Demo keys must target an allowlisted destination.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "from_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "to_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "record": { "default": true, "type": "boolean" }, "amd": { "default": false, "type": "boolean" } }, "required": ["from_number", "to_number", "record", "amd"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "call_id": { "type": "string" }, "provider_call_sid": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" }, "status": { "type": "string" } }, "required": ["call_id", "provider_call_sid", "from_number", "to_number", "status"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["calls:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/calls/{id}": { "get": { "operationId": "v1_calls_id_get", "tags": ["Calls"], "summary": "Get a call", "description": "One call by id (from `GET /v1/calls`, a call webhook, `POST /v1/calls/dial`, or a Quick AI Phone Call job): the full transcript (plain text and speaker-labelled turns), AI summary, tags, status and duration, plus a `recording_url` to download the audio. Free: reads are never billed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "anyOf": [ { "type": "string", "enum": ["inbound", "outbound"] }, { "type": "null" } ] }, "status": { "type": "string" }, "from_number": { "type": "string" }, "to_number": { "type": "string" }, "started_at": { "type": ["string", "null"] }, "ended_at": { "type": ["string", "null"] }, "duration_seconds": { "type": ["number", "null"] }, "summary": { "type": ["string", "null"] }, "transcript": { "type": ["string", "null"] }, "transcript_turns": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string", "enum": ["agent", "person"] }, "text": { "type": "string" }, "seconds_from_start": { "type": ["number", "null"] } }, "required": ["speaker", "text", "seconds_from_start"], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "string", "enum": [ "booking_requested", "callback_requested", "complaint", "purchase_interest", "interested", "qualified", "not_interested", "transferred" ] } }, "has_recording": { "type": "boolean" }, "recording_url": { "description": "`GET` it with your API key to download the audio (`GET /v1/calls/{id}/recording`). Null when the call has no recording.", "type": ["string", "null"] }, "created_at": { "type": "string" } }, "required": [ "id", "direction", "status", "from_number", "to_number", "started_at", "ended_at", "duration_seconds", "summary", "transcript", "transcript_turns", "tags", "has_recording", "recording_url", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["calls:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/calls/{id}/recording": { "get": { "operationId": "v1_calls_id_recording_get", "tags": ["Calls"], "summary": "Download a call recording", "description": "The call's audio file (usually `audio/mpeg`), streamed as raw bytes. Use the `recording_url` on a call from `GET /v1/calls` or `GET /v1/calls/{id}`, or build it from the call id. 404 when the call has no recording, recording was turned off for it, or it is not in your workspace. Every download is recorded in your compliance audit log. Free: reads are never billed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The recording's audio bytes", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["calls:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/contacts": { "get": { "operationId": "v1_contacts_get", "tags": ["Contacts"], "summary": "List contacts", "description": "Everyone the workspace has called, texted or emailed, most recently in touch first, with per-channel counts. A number or address that belongs to a saved contact is folded into that contact (`contact_id` set); someone you have not saved has `contact_id: null`. Get a saved contact's full record with `GET /v1/contacts/{id}`, and pass `contact_id` or `phone_number` to `GET /v1/calls` or `GET /v1/messages`, or `contact_id` or `email` to `GET /v1/emails`, for your history with them. Free: reads are never billed.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "`meta.cursor` from the previous page", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] }, "phone_number": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "call_count": { "type": "number" }, "text_count": { "type": "number" }, "email_count": { "type": "number" }, "first_contacted_at": { "type": "string" }, "last_contacted_at": { "type": "string" } }, "required": [ "contact_id", "name", "phone_number", "email", "call_count", "text_count", "email_count", "first_contacted_at", "last_contacted_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["contacts:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/contacts/{id}": { "get": { "operationId": "v1_contacts_id_get", "tags": ["Contacts"], "summary": "Get a contact", "description": "Everything your workspace knows about one contact: name, phone, email, company, job title, location, notes, tags, custom fields, per-channel consent and CRM link. Get the id from `GET /v1/contacts`, an inbound SMS webhook (`data.contact.id`) or a call or text. Free: reads are never billed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "first_name": { "type": ["string", "null"] }, "last_name": { "type": ["string", "null"] }, "phone_number": { "type": ["string", "null"] }, "email": { "type": ["string", "null"] }, "company": { "type": ["string", "null"] }, "job_title": { "type": ["string", "null"] }, "industry": { "type": ["string", "null"] }, "location": { "type": ["string", "null"] }, "preferred_language": { "type": ["string", "null"] }, "date_of_birth": { "description": "ISO date, `YYYY-MM-DD`", "type": ["string", "null"] }, "notes": { "type": ["string", "null"] }, "tags": { "type": "array", "items": { "type": "string" } }, "subscription_plan": { "type": ["string", "null"] }, "purchase_history": { "type": ["string", "null"] }, "product_preferences": { "type": ["string", "null"] }, "custom_fields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Free-form fields set on the contact (CSV import, Zapier, the API)" }, "consent": { "type": "object", "properties": { "sms_opted_in": { "type": "boolean" }, "voice_opted_in": { "type": "boolean" }, "email_opted_in": { "type": "boolean" }, "email_subscribed": { "type": "boolean", "description": "False once they unsubscribe from marketing email" } }, "required": [ "sms_opted_in", "voice_opted_in", "email_opted_in", "email_subscribed" ], "additionalProperties": false }, "first_inbound_call_at": { "type": ["string", "null"] }, "first_inbound_text_at": { "type": ["string", "null"] }, "first_inbound_email_at": { "type": ["string", "null"] }, "crm": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "contact_id": { "type": ["string", "null"] }, "last_synced_at": { "type": ["string", "null"] } }, "required": ["provider", "contact_id", "last_synced_at"], "additionalProperties": false }, { "type": "null" } ], "description": "The CRM record this contact is synced with, if any" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "first_name", "last_name", "phone_number", "email", "company", "job_title", "industry", "location", "preferred_language", "date_of_birth", "notes", "tags", "subscription_plan", "purchase_history", "product_preferences", "custom_fields", "consent", "first_inbound_call_at", "first_inbound_text_at", "first_inbound_email_at", "crm", "created_at", "updated_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["contacts:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/emails": { "get": { "operationId": "v1_emails_get", "tags": ["Emails"], "summary": "List emails with a person", "description": "Every email with one person, newest first: inbox and workflow email (`source: inbox`) and Quick Emails sent from the shared LumisReach address (`source: quick`). Name the person with `contact_id` or `email`. Free: reads are never billed.", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "schema": { "description": "A contact id (from `GET /v1/contacts`). Its phone number / email is used.", "type": "string", "minLength": 1 } }, { "name": "email", "in": "query", "required": false, "schema": { "description": "The person's email address", "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "`meta.cursor` from the previous page", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "anyOf": [ { "type": "string", "enum": ["inbound", "outbound"] }, { "type": "null" } ] }, "source": { "type": "string", "enum": ["inbox", "quick"] }, "status": { "type": "string" }, "from": { "type": ["string", "null"] }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": ["string", "null"] }, "body": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "direction", "source", "status", "from", "to", "subject", "body", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["email:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/lincoln/conversations": { "get": { "operationId": "v1_lincoln_conversations_get", "tags": ["Lincoln AI"], "summary": "List Lincoln AI conversations", "description": "Every Lincoln AI conversation in the workspace, newest first, including ones started in the dashboard. Free: reads are never billed.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "`meta.cursor` from the previous page", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": ["working", "idle", "awaiting_approval", "failed"], "description": "`working`: Lincoln is mid-turn. `idle`: done, waiting for your next message. `awaiting_approval`: paused until you answer `pending_approvals`. `failed`: the turn errored (see `error`)." }, "error": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "last_message_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "conversation_id", "title", "status", "error", "created_at", "last_message_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["lincoln:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/lincoln/conversations/{id}": { "get": { "operationId": "v1_lincoln_conversations_id_get", "tags": ["Lincoln AI"], "summary": "Get a Lincoln AI conversation", "description": "Where a conversation stands: `status`, Lincoln's latest `reply`, the `actions` it took, any `pending_approvals`, and the full transcript in `messages`. Poll this after `POST /v1/lincoln/messages` returns `status: working`; while Lincoln is still going, `reply` holds what it has said so far. Free: reads are never billed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": ["working", "idle", "awaiting_approval", "failed"], "description": "`working`: Lincoln is mid-turn. `idle`: done, waiting for your next message. `awaiting_approval`: paused until you answer `pending_approvals`. `failed`: the turn errored (see `error`)." }, "run_id": { "type": ["string", "null"] }, "reply": { "description": "Lincoln's latest reply as text. Partial while `status` is `working`.", "type": ["string", "null"] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "tool_call_id": { "type": "string" }, "tool": { "type": "string", "description": "The tool Lincoln used, e.g. `list_phone_numbers`" }, "status": { "type": "string", "enum": [ "running", "awaiting_approval", "approved", "denied", "completed", "failed" ] }, "input": { "description": "The arguments Lincoln passed" }, "output": { "anyOf": [ {}, { "type": "null" } ], "description": "What the tool returned, when it completed" }, "error": { "type": ["string", "null"] } }, "required": ["tool_call_id", "tool", "status", "input", "output", "error"], "additionalProperties": false }, "description": "The tool calls in Lincoln's latest reply" }, "pending_approvals": { "type": "array", "items": { "type": "object", "properties": { "approval_id": { "type": "string" }, "tool_call_id": { "type": "string" }, "tool": { "type": "string" }, "input": {}, "reason": { "description": "Why this action needs a yes: what it costs or changes", "type": ["string", "null"] } }, "required": ["approval_id", "tool_call_id", "tool", "input", "reason"], "additionalProperties": false } }, "error": { "type": ["string", "null"] }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": ["user", "assistant"] }, "text": { "type": "string" }, "platform_update": { "type": "boolean", "description": "`true` for updates LumisReach posted on its own, e.g. a video finishing" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "tool_call_id": { "type": "string" }, "tool": { "type": "string", "description": "The tool Lincoln used, e.g. `list_phone_numbers`" }, "status": { "type": "string", "enum": [ "running", "awaiting_approval", "approved", "denied", "completed", "failed" ] }, "input": { "description": "The arguments Lincoln passed" }, "output": { "anyOf": [ {}, { "type": "null" } ], "description": "What the tool returned, when it completed" }, "error": { "type": ["string", "null"] } }, "required": ["tool_call_id", "tool", "status", "input", "output", "error"], "additionalProperties": false } } }, "required": ["id", "role", "text", "platform_update", "actions"], "additionalProperties": false } } }, "required": [ "conversation_id", "title", "status", "run_id", "reply", "actions", "pending_approvals", "error", "updated_at", "created_at", "messages" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["lincoln:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/lincoln/messages": { "post": { "operationId": "v1_lincoln_messages_post", "tags": ["Lincoln AI"], "summary": "Message Lincoln AI", "description": "Tell Lincoln AI what to do in plain language, the same as typing in Dashboard → Conversations: it plans the work and carries it out with your workspace's tools (phone numbers, voice agents, campaigns, contacts, automations, videos and more). Omit `conversation_id` to start a new conversation; pass it to continue one. The request waits up to `wait_seconds` for Lincoln to finish and returns its `reply` and the `actions` it took. If it is still working, `status` is `working`: poll `GET /v1/lincoln/conversations/{id}`. Anything that spends money or can't be undone pauses with `status: awaiting_approval` and a list of `pending_approvals`; send them back as `approvals` to continue. Requires Lincoln AI on the workspace's plan. Billed per message from the prepaid balance: the AI model cost of the turn plus a 20% markup (Lincoln in the dashboard stays free), itemized as `ai_agent` in `GET /v1/billing/events`. Returns `402 payment_required` when the balance is empty and auto-refill is off. Tool actions are billed on top, as they would be in the dashboard.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "conversation_id": { "description": "Continue this conversation. Omit to start a new one.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "message": { "description": "What you want Lincoln to do, in plain language. Send this or `approvals`, not both.", "type": "string", "minLength": 1, "maxLength": 20000 }, "approvals": { "description": "Answers to the actions Lincoln is waiting on (`pending_approvals`). Every pending approval must be answered. Send this or `message`, not both.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "approval_id": { "type": "string", "minLength": 1, "description": "`pending_approvals[].approval_id` from the previous response" }, "approved": { "type": "boolean", "description": "`true` lets Lincoln run the action, `false` stops it" }, "reason": { "description": "Optional note Lincoln sees, e.g. why you declined", "type": "string", "maxLength": 500 } }, "required": ["approval_id", "approved"], "additionalProperties": false } }, "wait_seconds": { "default": 120, "description": "How long to hold the request open for Lincoln to finish. `0` returns immediately. If the turn is still running when this runs out, `status` is `working`: poll `GET /v1/lincoln/conversations/{id}`.", "type": "integer", "minimum": 0, "maximum": 240 } }, "required": ["wait_seconds"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": ["working", "idle", "awaiting_approval", "failed"], "description": "`working`: Lincoln is mid-turn. `idle`: done, waiting for your next message. `awaiting_approval`: paused until you answer `pending_approvals`. `failed`: the turn errored (see `error`)." }, "run_id": { "type": ["string", "null"] }, "reply": { "description": "Lincoln's latest reply as text. Partial while `status` is `working`.", "type": ["string", "null"] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "tool_call_id": { "type": "string" }, "tool": { "type": "string", "description": "The tool Lincoln used, e.g. `list_phone_numbers`" }, "status": { "type": "string", "enum": [ "running", "awaiting_approval", "approved", "denied", "completed", "failed" ] }, "input": { "description": "The arguments Lincoln passed" }, "output": { "anyOf": [ {}, { "type": "null" } ], "description": "What the tool returned, when it completed" }, "error": { "type": ["string", "null"] } }, "required": ["tool_call_id", "tool", "status", "input", "output", "error"], "additionalProperties": false }, "description": "The tool calls in Lincoln's latest reply" }, "pending_approvals": { "type": "array", "items": { "type": "object", "properties": { "approval_id": { "type": "string" }, "tool_call_id": { "type": "string" }, "tool": { "type": "string" }, "input": {}, "reason": { "description": "Why this action needs a yes: what it costs or changes", "type": ["string", "null"] } }, "required": ["approval_id", "tool_call_id", "tool", "input", "reason"], "additionalProperties": false } }, "error": { "type": ["string", "null"] }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "conversation_id", "title", "status", "run_id", "reply", "actions", "pending_approvals", "error", "updated_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["lincoln:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/me": { "get": { "operationId": "v1_me_get", "tags": ["Account"], "summary": "Current authenticated principal", "description": "Returns the user/organization backing the API key, plus the scopes it carries.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "api_key_id": { "type": "string" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "email": { "type": "string" }, "name": { "type": ["string", "null"] } }, "required": ["id", "email", "name"], "additionalProperties": false }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": ["id", "name", "slug"], "additionalProperties": false }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "is_demo": { "type": "boolean" }, "demo_expires_at": { "type": ["string", "null"] } }, "required": [ "api_key_id", "user", "organization", "scopes", "is_demo", "demo_expires_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/messages": { "get": { "operationId": "v1_messages_get", "tags": ["Messages"], "summary": "List text messages", "description": "The workspace's SMS, most recent first, sent and received, on every number it texts from (including the shared LumisReach lines Quick Agent Actions use). Each has its `direction`, who wrote it (`sender`: `ai_agent`, `business` or `contact`), status and body. Narrow it to one person with `contact_id` or `phone_number`, and filter by `direction` or a `created_after` / `created_before` window. Free: reads are never billed.", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "schema": { "description": "A contact id (from `GET /v1/contacts`). Its phone number / email is used.", "type": "string", "minLength": 1 } }, { "name": "phone_number", "in": "query", "required": false, "schema": { "description": "The person's phone number, E.164 (+14155550123)", "type": "string", "minLength": 3 } }, { "name": "direction", "in": "query", "required": false, "schema": { "description": "Only `inbound` (they reached you) or `outbound` (you reached them)", "type": "string", "enum": ["inbound", "outbound"] } }, { "name": "created_after", "in": "query", "required": false, "schema": { "description": "Only items created at or after this time (ISO 8601)" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "description": "Only items created before this time (ISO 8601)" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "`meta.cursor` from the previous page", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "anyOf": [ { "type": "string", "enum": ["inbound", "outbound"] }, { "type": "null" } ] }, "sender": { "type": "string", "enum": ["ai_agent", "business", "contact"] }, "status": { "type": "string" }, "from_number": { "type": ["string", "null"] }, "to_number": { "type": ["string", "null"] }, "body": { "type": "string" }, "sent_at": { "type": ["string", "null"] }, "delivered_at": { "type": ["string", "null"] }, "created_at": { "type": "string" } }, "required": [ "id", "direction", "sender", "status", "from_number", "to_number", "body", "sent_at", "delivered_at", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/phone-numbers": { "get": { "operationId": "v1_phone_numbers_get", "tags": ["Phone Numbers"], "summary": "List owned phone numbers", "description": "Returns every Phone row owned by the caller's active organization.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "name": { "type": ["string", "null"] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "provider": { "type": "string" }, "is_active": { "type": "boolean" }, "iso_country": { "type": "string" }, "reputation_enrolled_at": { "type": ["string", "null"] }, "cnam_display_name": { "type": ["string", "null"] }, "cnam_status": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "name", "organization_id", "user_id", "provider", "is_active", "iso_country", "reputation_enrolled_at", "cnam_display_name", "cnam_status", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_phone_numbers_post", "tags": ["Phone Numbers"], "summary": "Purchase a new phone number", "description": "Initiates the durable provisioning workflow. Returns 202 with a workflow run id — poll `/v1/phone-numbers/{phone_record_id}` to see when the number goes active. The new number attaches to the caller's active organization. To buy a number AND configure its AI receptionist in one request, use `POST /v1/quick/ai-numbers` instead.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "phone_number": { "type": "string" }, "area_code": { "type": "string", "pattern": "^\\d{3}$" }, "name": { "type": "string", "maxLength": 120 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "phone_record_id": { "type": "number" }, "workflow_run_id": { "type": "string" }, "status_url": { "type": "string" } }, "required": ["phone_record_id", "workflow_run_id", "status_url"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/phone-numbers/search": { "get": { "operationId": "v1_phone_numbers_search_get", "tags": ["Phone Numbers"], "summary": "Search available phone numbers", "description": "Query carrier inventory for numbers matching the given filters. Returns up to 50 results per call.", "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "default": "US", "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "area_code", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{3}$" } }, { "name": "contains", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "in_region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "number_type", "in": "query", "required": true, "schema": { "default": "local", "type": "string", "enum": ["local", "tollFree", "mobile", "national"] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string" }, "locality": { "type": "string" }, "region": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } } }, "required": ["phone_number", "locality", "region", "features"], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/phone-numbers/{id}": { "get": { "operationId": "v1_phone_numbers_id_get", "tags": ["Phone Numbers"], "summary": "Retrieve a phone number", "description": "Polls for status. While provisioning is in flight, `is_active=false` and `phone_number` is a `pending:…` placeholder. Once the workflow completes, both fields update atomically.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "name": { "type": ["string", "null"] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "provider": { "type": "string" }, "is_active": { "type": "boolean" }, "subscription_status": { "type": ["string", "null"] }, "iso_country": { "type": "string" }, "reputation_enrolled_at": { "type": ["string", "null"] }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "name", "organization_id", "user_id", "provider", "is_active", "subscription_status", "iso_country", "reputation_enrolled_at", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_phone_numbers_id_patch", "tags": ["Phone Numbers"], "summary": "Update a phone number's settings", "description": "Mutates name + recording flags + CNAM display name. CNAM is the caller-ID name shown on outbound calls (max 15 chars, US local numbers only). Setting `cnam_display_name` updates the carrier on the spot — propagation to carriers takes 24-72h.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "cnam_display_name": { "type": "string", "minLength": 1, "maxLength": 15 }, "cnam_enabled": { "type": "boolean" }, "recording_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "cnam_display_name": { "type": ["string", "null"] }, "cnam_status": { "type": "string" }, "name": { "type": ["string", "null"] }, "recording_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" } }, "required": [ "id", "cnam_display_name", "cnam_status", "name", "recording_enabled", "transcription_enabled" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_phone_numbers_id_delete", "tags": ["Phone Numbers"], "summary": "Release a phone number", "description": "Releases the phone number from Telnyx, removes it from the LiveKit inbound trunks, cancels the Stripe subscription line item, deletes associated call data and recordings, and removes the database record.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/phone-numbers/{id}/cnam-status": { "get": { "operationId": "v1_phone_numbers_id_cnam_status_get", "tags": ["Phone Numbers"], "summary": "Check live CNAM status", "description": "Queries the carrier for the current CNAM status. If the carrier reports CNAM as enabled and the database status is still PENDING, it is automatically promoted to APPROVED.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "cnam_display_name": { "type": ["string", "null"] }, "cnam_status": { "type": "string" }, "live_status": { "type": "string", "enum": ["active", "inactive", "provisioning"] }, "live_enabled": { "type": "boolean" }, "live_display_name": { "type": ["string", "null"] } }, "required": [ "id", "phone_number", "cnam_display_name", "cnam_status", "live_status", "live_enabled", "live_display_name" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/phone-numbers/{id}/config": { "get": { "operationId": "v1_phone_numbers_id_config_get", "tags": ["Phone Numbers"], "summary": "Get a number's AI configuration", "description": "Everything configurable on the number's Answer page in the dashboard: setup and call settings, the call agent's voice, language and prompt, the SMS auto-reply agent, knowledge, qualification questions, booking, transfer rules, SMS referrals, call forwarding and the keypad phone menu (IVR). Values are effective values: where the number has no override, the workspace default is returned and `inherits_workspace_default` is true.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "provider": { "type": "string" }, "stack": { "type": "string", "enum": ["t1", "t2"], "description": "t1 = Twilio + VAPI, t2 = Telnyx + LiveKit" }, "agent_id": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] }, "is_active": { "type": "boolean" }, "business_name": { "type": ["string", "null"] }, "business_description": { "type": ["string", "null"] }, "timezone": { "type": ["string", "null"] }, "call_settings": { "type": "object", "properties": { "max_call_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 30, "maximum": 1800 }, { "type": "null" } ], "description": "Hang up inbound calls after this long. null = no limit (3-hour system cap)." }, "recording_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" }, "summary_enabled": { "type": "boolean" }, "recording_retention_days": { "anyOf": [ { "type": "number", "const": 90 }, { "type": "number", "const": 365 }, { "type": "number", "const": -1 } ], "description": "90, 365, or -1 for unlimited" }, "hd_voice_enabled": { "type": "boolean", "description": "Wideband audio. T2 (Telnyx) numbers only." } }, "required": [ "max_call_duration_seconds", "recording_enabled", "transcription_enabled", "summary_enabled", "recording_retention_days", "hd_voice_enabled" ], "additionalProperties": false }, "voice": { "type": "object", "properties": { "voice_id": { "description": "A voice_id from GET /v1/phone-numbers/{id}/voices. null = the stack default.", "type": ["string", "null"] }, "voice_model_tier": { "anyOf": [ { "type": "string", "enum": ["standard", "mini"] }, { "type": "null" } ], "description": "T2 only" }, "llm_model": { "anyOf": [ { "type": "string", "enum": [ "claude-haiku-5-5", "gpt-5.4-mini", "gpt-5-mini", "gemini-3.5-flash-lite", "gemini-3.8-flash" ] }, { "type": "null" } ], "description": "LLM for text-to-speech voices. null = stack default." }, "language": { "type": "string", "minLength": 2, "maxLength": 10, "description": "ISO 639-1 code, or 'multi' to match the caller" }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5, "description": "Speaking speed. T1 only." }, "greeting_message": { "description": "First thing the agent says on an inbound call", "type": ["string", "null"] }, "farewell_message": { "type": ["string", "null"] }, "prompt": { "description": "Custom instructions for the call agent (the system prompt you write)", "type": ["string", "null"] }, "background_sound": { "type": "string", "enum": ["off", "office"] }, "outbound_greeting_message": { "type": ["string", "null"] }, "outbound_prompt": { "type": ["string", "null"] }, "inherits_workspace_default": { "type": "boolean" } }, "required": [ "voice_id", "voice_model_tier", "llm_model", "language", "speed", "greeting_message", "farewell_message", "prompt", "background_sound", "outbound_greeting_message", "outbound_prompt", "inherits_workspace_default" ], "additionalProperties": false }, "sms": { "type": "object", "properties": { "auto_reply_enabled": { "type": "boolean", "description": "Whether the AI answers texts to this number" }, "reply_delay_seconds": { "type": "integer", "minimum": 0, "maximum": 300 }, "skip_conditions": { "type": "array", "items": { "type": "string" }, "description": "Situations where the AI skips replying to a message" }, "prompt": { "description": "Custom instructions for the SMS agent", "type": ["string", "null"] }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "llm_model": { "anyOf": [ { "type": "string", "enum": [ "claude-haiku-5-5", "gpt-5.4-mini", "gpt-5-mini", "gemini-3.5-flash-lite", "gemini-3.8-flash" ] }, { "type": "null" } ] }, "stop_on_stop_word": { "type": "boolean" }, "stop_words": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "stop_after_replies": { "type": "boolean", "description": "Stop auto-replying to a contact after max_replies_per_contact" }, "max_replies_per_contact": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Default 50" }, "inherits_workspace_default": { "type": "boolean" } }, "required": [ "auto_reply_enabled", "reply_delay_seconds", "skip_conditions", "prompt", "language", "llm_model", "stop_on_stop_word", "stop_words", "stop_after_replies", "max_replies_per_contact", "inherits_workspace_default" ], "additionalProperties": false }, "knowledge": { "type": "object", "properties": { "knowledge_enabled": { "type": "boolean" }, "web_search_enabled": { "type": "boolean" }, "knowledge_base_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Knowledge documents the agent can reference" }, "faq_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "knowledge_enabled", "web_search_enabled", "knowledge_base_ids", "faq_ids" ], "additionalProperties": false }, "qualification": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contact_info_collection": { "type": "array", "items": { "type": "string", "enum": [ "name", "business_name", "phone", "email", "address", "date_of_birth" ] } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question_text": { "type": "string", "minLength": 1 }, "type": { "default": "OPEN_ENDED", "type": "string", "enum": ["OPEN_ENDED", "YES_NO", "MULTIPLE_CHOICE", "SCALE"] }, "required": { "default": false, "type": "boolean" }, "is_qualifying": { "default": true, "type": "boolean" }, "options": { "description": "MULTIPLE_CHOICE options", "type": "array", "items": { "type": "string" } }, "qualifying_answers": { "type": "array", "items": { "type": "string" } }, "scale_min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scale_max": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "qualifying_min_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "question_text", "type", "required", "is_qualifying"], "additionalProperties": false } } }, "required": ["enabled", "contact_info_collection", "questions"], "additionalProperties": false }, "booking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "event_type_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Event types the agent can book" }, "confirmation_message": { "type": ["string", "null"] }, "minimum_notice_minutes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "available_hours": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } }, "required": ["start", "end"], "additionalProperties": false } }, { "type": "null" } ], "description": "Bookable windows per day, in the number's timezone. Two windows = a lunch break." }, "available_days": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, { "type": "null" } ], "description": "0 = Sunday … 6 = Saturday" } }, "required": [ "enabled", "event_type_ids", "confirmation_message", "minimum_notice_minutes", "available_hours", "available_days" ], "additionalProperties": false }, "transfers": { "type": "object", "properties": { "primary_transfer_number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "condition": { "type": "string", "enum": [ "human_requested", "after_hours", "qualification_failed", "qualification_passed", "urgent_request", "custom" ] }, "custom_condition": { "type": ["string", "null"] }, "action": { "type": "string", "enum": [ "transfer", "voicemail", "schedule_callback", "hang_up", "notify_and_end", "round_robin", "webhook" ] }, "target_number": { "type": ["string", "null"] }, "round_robin_numbers": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string", "format": "uri" }, "webhook_lead_source": { "type": "string" }, "notify_message": { "type": "string" }, "priority": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "default": true, "type": "boolean" } }, "required": ["id", "condition", "action", "priority", "enabled"], "additionalProperties": false } }, "office_hours_only": { "type": "boolean", "description": "Only transfer live calls inside the office-hours window" }, "office_hours_start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "office_hours_end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "office_hours_timezone": { "anyOf": [ {}, { "type": "null" } ] }, "outside_office_hours_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "primary_transfer_number", "rules", "office_hours_only", "office_hours_start", "office_hours_end", "office_hours_timezone", "outside_office_hours_message" ], "additionalProperties": false }, "sms_referrals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "condition": { "type": "string", "enum": [ "human_requested", "after_hours", "qualification_failed", "qualification_passed", "urgent_request", "custom" ] }, "custom_condition": { "type": ["string", "null"] }, "target_number": { "description": "The number the texter is told to text instead", "type": ["string", "null"] }, "priority": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "default": true, "type": "boolean" } }, "required": ["id", "condition", "priority", "enabled"], "additionalProperties": false } }, "forwarding": { "type": "object", "properties": { "phone_config_mode": { "type": "string", "enum": ["lumisreach_number", "existing_number"] }, "phone_service_type": { "anyOf": [ { "type": "string", "enum": ["cellphone", "voip", "landline"] }, { "type": "null" } ] }, "call_handling_mode": { "type": "string", "enum": ["ai_handles_all", "call_me_first"], "description": "call_me_first rings your phone(s) first and lets the AI take over if nobody answers" }, "forwarding_mode": { "anyOf": [ { "type": "string", "enum": ["single_target", "sequential_chain"] }, { "type": "null" } ] }, "forwarding_number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "ring_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 60 }, { "type": "null" } ] }, "sequential_targets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phone_number": { "type": "string" }, "label": { "type": "string", "maxLength": 50 }, "timeout_seconds": { "type": "integer", "minimum": 5, "maximum": 60 }, "active": { "default": true, "type": "boolean" } }, "required": ["id", "phone_number", "timeout_seconds", "active"], "additionalProperties": false } }, "chain_transition_message": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "record_human_calls": { "type": "boolean" }, "office_hours_enabled": { "type": "boolean" }, "office_hours_start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "office_hours_end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "carrier_forwarding_type": { "anyOf": [ { "type": "string", "enum": [ "forward_all", "forward_missed", "forward_busy", "forward_no_answer" ] }, { "type": "null" } ] }, "selected_carrier": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "setup_completed": { "type": "boolean" } }, "required": [ "phone_config_mode", "phone_service_type", "call_handling_mode", "forwarding_mode", "forwarding_number", "ring_duration_seconds", "sequential_targets", "chain_transition_message", "record_human_calls", "office_hours_enabled", "office_hours_start", "office_hours_end", "carrier_forwarding_type", "selected_carrier", "setup_completed" ], "additionalProperties": false }, "ivr": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "When on, the keypad menu answers calls INSTEAD of the AI agent" }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "menus": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Referenced by submenu actions. menus[0] is the main menu." }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "prompt": { "description": "Blank = generated from the option labels", "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "options": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#" ] }, "label": { "type": "string", "maxLength": 100 }, "action": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "transfer" }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "fallback_phone_number": { "anyOf": [ { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, { "type": "null" } ] } }, "required": ["type", "phone_number"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "submenu" }, "menu_id": { "type": "string", "minLength": 1 } }, "required": ["type", "menu_id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "repeat" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "previous" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hangup" }, "message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": ["type"], "additionalProperties": false } ] } }, "required": ["key", "label", "action"], "additionalProperties": false } } }, "required": ["id", "name", "options"], "additionalProperties": false } }, "invalid_input_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "no_input_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "transfer_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "transfer_caller_id": { "type": "string", "enum": ["business", "caller"] }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "speed": { "anyOf": [ { "type": "number", "minimum": 0.8, "maximum": 1.2 }, { "type": "null" } ] }, "timeout_seconds": { "type": "integer", "minimum": 3, "maximum": 15 }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 5 }, "fallback": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "transfer" }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } }, "required": ["type", "phone_number"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hangup" }, "message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": ["type"], "additionalProperties": false } ] } }, "required": [ "enabled", "greeting", "menus", "invalid_input_message", "no_input_message", "transfer_message", "transfer_caller_id", "voice_id", "speed", "timeout_seconds", "max_attempts", "fallback" ], "additionalProperties": false }, { "type": "null" } ], "description": "null until a phone menu has been set up" }, "updated_at": { "type": "string" } }, "required": [ "id", "phone_number", "provider", "stack", "agent_id", "name", "is_active", "business_name", "business_description", "timezone", "call_settings", "voice", "sms", "knowledge", "qualification", "booking", "transfers", "sms_referrals", "forwarding", "ivr", "updated_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_phone_numbers_id_config_patch", "tags": ["Phone Numbers"], "summary": "Update a number's AI configuration", "description": "Changes any setting on the number's Answer page. Send only what you want to change: inside a section, fields you leave out keep their current value. Lists (`transfers.rules`, `qualification.questions`, `sms_referrals`, `forwarding.sequential_targets`, `ivr.menus`) are replaced as a whole, so fetch the config, edit the list, and send it back. Changes apply from the next call or text on both T1 (Twilio + VAPI) and T2 (Telnyx + LiveKit) numbers, exactly as a save in the dashboard does. Returns the full updated configuration.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "is_active": { "description": "false stops the number from answering calls", "type": "boolean" }, "business_name": { "type": "string", "maxLength": 200 }, "business_description": { "type": "string", "maxLength": 2000 }, "timezone": { "description": "IANA zone; drives booking hours and office hours" }, "call_settings": { "type": "object", "properties": { "max_call_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 30, "maximum": 1800 }, { "type": "null" } ], "description": "Hang up inbound calls after this long. null = no limit (3-hour system cap)." }, "recording_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" }, "summary_enabled": { "type": "boolean" }, "recording_retention_days": { "anyOf": [ { "type": "number", "const": 90 }, { "type": "number", "const": 365 }, { "type": "number", "const": -1 } ], "description": "90, 365, or -1 for unlimited" }, "hd_voice_enabled": { "type": "boolean", "description": "Wideband audio. T2 (Telnyx) numbers only." } }, "additionalProperties": false }, "voice": { "type": "object", "properties": { "voice_id": { "type": "string", "minLength": 1 }, "voice_model_tier": { "type": "string", "enum": ["standard", "mini"] }, "llm_model": { "type": "string", "enum": [ "claude-haiku-5-5", "gpt-5.4-mini", "gpt-5-mini", "gemini-3.5-flash-lite", "gemini-3.8-flash" ] }, "language": { "type": "string", "minLength": 2, "maxLength": 10, "description": "ISO 639-1 code, or 'multi' to match the caller" }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5, "description": "Speaking speed. T1 only." }, "greeting_message": { "description": "First thing the agent says on an inbound call", "type": ["string", "null"] }, "farewell_message": { "type": ["string", "null"] }, "prompt": { "description": "Custom instructions for the call agent (the system prompt you write)", "type": ["string", "null"] }, "background_sound": { "type": "string", "enum": ["off", "office"] }, "outbound_greeting_message": { "type": ["string", "null"] }, "outbound_prompt": { "type": ["string", "null"] } }, "additionalProperties": false }, "sms": { "type": "object", "properties": { "auto_reply_enabled": { "type": "boolean", "description": "Whether the AI answers texts to this number" }, "reply_delay_seconds": { "type": "integer", "minimum": 0, "maximum": 300 }, "skip_conditions": { "type": "array", "items": { "type": "string" }, "description": "Situations where the AI skips replying to a message" }, "prompt": { "description": "Custom instructions for the SMS agent", "type": ["string", "null"] }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "llm_model": { "type": "string", "enum": [ "claude-haiku-5-5", "gpt-5.4-mini", "gpt-5-mini", "gemini-3.5-flash-lite", "gemini-3.8-flash" ] }, "stop_on_stop_word": { "type": "boolean" }, "stop_words": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "stop_after_replies": { "type": "boolean", "description": "Stop auto-replying to a contact after max_replies_per_contact" }, "max_replies_per_contact": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Default 50" } }, "additionalProperties": false }, "knowledge": { "type": "object", "properties": { "knowledge_enabled": { "type": "boolean" }, "web_search_enabled": { "type": "boolean" }, "knowledge_base_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Knowledge documents the agent can reference" }, "faq_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "additionalProperties": false }, "qualification": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contact_info_collection": { "type": "array", "items": { "type": "string", "enum": ["name", "business_name", "phone", "email", "address", "date_of_birth"] } }, "questions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Omit to create a new question; existing questions not listed are removed", "type": "string" }, "question_text": { "type": "string", "minLength": 1 }, "type": { "default": "OPEN_ENDED", "type": "string", "enum": ["OPEN_ENDED", "YES_NO", "MULTIPLE_CHOICE", "SCALE"] }, "required": { "default": false, "type": "boolean" }, "is_qualifying": { "default": true, "type": "boolean" }, "options": { "description": "MULTIPLE_CHOICE options", "type": "array", "items": { "type": "string" } }, "qualifying_answers": { "type": "array", "items": { "type": "string" } }, "scale_min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scale_max": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "qualifying_min_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["question_text", "type", "required", "is_qualifying"], "additionalProperties": false } } }, "additionalProperties": false }, "booking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "event_type_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Event types the agent can book" }, "confirmation_message": { "type": ["string", "null"] }, "minimum_notice_minutes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "available_hours": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } }, "required": ["start", "end"], "additionalProperties": false } }, { "type": "null" } ], "description": "Bookable windows per day, in the number's timezone. Two windows = a lunch break." }, "available_days": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, { "type": "null" } ], "description": "0 = Sunday … 6 = Saturday" } }, "additionalProperties": false }, "transfers": { "type": "object", "properties": { "primary_transfer_number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "rules": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "condition": { "type": "string", "enum": [ "human_requested", "after_hours", "qualification_failed", "qualification_passed", "urgent_request", "custom" ] }, "custom_condition": { "type": ["string", "null"] }, "action": { "type": "string", "enum": [ "transfer", "voicemail", "schedule_callback", "hang_up", "notify_and_end", "round_robin", "webhook" ] }, "target_number": { "type": ["string", "null"] }, "round_robin_numbers": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string", "format": "uri" }, "webhook_lead_source": { "type": "string" }, "notify_message": { "type": "string" }, "priority": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "default": true, "type": "boolean" } }, "required": ["condition", "action", "priority", "enabled"], "additionalProperties": false } }, "office_hours_only": { "type": "boolean", "description": "Only transfer live calls inside the office-hours window" }, "office_hours_start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "office_hours_end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "office_hours_timezone": { "anyOf": [ {}, { "type": "null" } ] }, "outside_office_hours_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "additionalProperties": false }, "sms_referrals": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "condition": { "type": "string", "enum": [ "human_requested", "after_hours", "qualification_failed", "qualification_passed", "urgent_request", "custom" ] }, "custom_condition": { "type": ["string", "null"] }, "target_number": { "description": "The number the texter is told to text instead", "type": ["string", "null"] }, "priority": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "default": true, "type": "boolean" } }, "required": ["condition", "priority", "enabled"], "additionalProperties": false } }, "forwarding": { "type": "object", "properties": { "phone_config_mode": { "type": "string", "enum": ["lumisreach_number", "existing_number"] }, "phone_service_type": { "anyOf": [ { "type": "string", "enum": ["cellphone", "voip", "landline"] }, { "type": "null" } ] }, "call_handling_mode": { "type": "string", "enum": ["ai_handles_all", "call_me_first"], "description": "call_me_first rings your phone(s) first and lets the AI take over if nobody answers" }, "forwarding_mode": { "anyOf": [ { "type": "string", "enum": ["single_target", "sequential_chain"] }, { "type": "null" } ] }, "forwarding_number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "ring_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 60 }, { "type": "null" } ] }, "sequential_targets": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phone_number": { "type": "string" }, "label": { "type": "string", "maxLength": 50 }, "timeout_seconds": { "type": "integer", "minimum": 5, "maximum": 60 }, "active": { "default": true, "type": "boolean" } }, "required": ["phone_number", "timeout_seconds", "active"], "additionalProperties": false } }, "chain_transition_message": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "record_human_calls": { "type": "boolean" }, "office_hours_enabled": { "type": "boolean" }, "office_hours_start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "office_hours_end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "carrier_forwarding_type": { "anyOf": [ { "type": "string", "enum": ["forward_all", "forward_missed", "forward_busy", "forward_no_answer"] }, { "type": "null" } ] }, "selected_carrier": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "setup_completed": { "type": "boolean" } }, "additionalProperties": false }, "ivr": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "When on, the keypad menu answers calls INSTEAD of the AI agent" }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "menus": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Referenced by submenu actions. menus[0] is the main menu." }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "prompt": { "description": "Blank = generated from the option labels", "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "options": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string", "enum": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#"] }, "label": { "type": "string", "maxLength": 100 }, "action": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "transfer" }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "fallback_phone_number": { "anyOf": [ { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, { "type": "null" } ] } }, "required": ["type", "phone_number"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "submenu" }, "menu_id": { "type": "string", "minLength": 1 } }, "required": ["type", "menu_id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "repeat" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "previous" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hangup" }, "message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": ["type"], "additionalProperties": false } ] } }, "required": ["key", "label", "action"], "additionalProperties": false } } }, "required": ["id", "name", "options"], "additionalProperties": false } }, "invalid_input_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "no_input_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "transfer_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "transfer_caller_id": { "type": "string", "enum": ["business", "caller"] }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "speed": { "anyOf": [ { "type": "number", "minimum": 0.8, "maximum": 1.2 }, { "type": "null" } ] }, "timeout_seconds": { "type": "integer", "minimum": 3, "maximum": 15 }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 5 }, "fallback": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "transfer" }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } }, "required": ["type", "phone_number"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hangup" }, "message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": ["type"], "additionalProperties": false } ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": "string" }, "provider": { "type": "string" }, "stack": { "type": "string", "enum": ["t1", "t2"], "description": "t1 = Twilio + VAPI, t2 = Telnyx + LiveKit" }, "agent_id": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] }, "is_active": { "type": "boolean" }, "business_name": { "type": ["string", "null"] }, "business_description": { "type": ["string", "null"] }, "timezone": { "type": ["string", "null"] }, "call_settings": { "type": "object", "properties": { "max_call_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 30, "maximum": 1800 }, { "type": "null" } ], "description": "Hang up inbound calls after this long. null = no limit (3-hour system cap)." }, "recording_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" }, "summary_enabled": { "type": "boolean" }, "recording_retention_days": { "anyOf": [ { "type": "number", "const": 90 }, { "type": "number", "const": 365 }, { "type": "number", "const": -1 } ], "description": "90, 365, or -1 for unlimited" }, "hd_voice_enabled": { "type": "boolean", "description": "Wideband audio. T2 (Telnyx) numbers only." } }, "required": [ "max_call_duration_seconds", "recording_enabled", "transcription_enabled", "summary_enabled", "recording_retention_days", "hd_voice_enabled" ], "additionalProperties": false }, "voice": { "type": "object", "properties": { "voice_id": { "description": "A voice_id from GET /v1/phone-numbers/{id}/voices. null = the stack default.", "type": ["string", "null"] }, "voice_model_tier": { "anyOf": [ { "type": "string", "enum": ["standard", "mini"] }, { "type": "null" } ], "description": "T2 only" }, "llm_model": { "anyOf": [ { "type": "string", "enum": [ "claude-haiku-5-5", "gpt-5.4-mini", "gpt-5-mini", "gemini-3.5-flash-lite", "gemini-3.8-flash" ] }, { "type": "null" } ], "description": "LLM for text-to-speech voices. null = stack default." }, "language": { "type": "string", "minLength": 2, "maxLength": 10, "description": "ISO 639-1 code, or 'multi' to match the caller" }, "speed": { "type": "number", "minimum": 0.6, "maximum": 1.5, "description": "Speaking speed. T1 only." }, "greeting_message": { "description": "First thing the agent says on an inbound call", "type": ["string", "null"] }, "farewell_message": { "type": ["string", "null"] }, "prompt": { "description": "Custom instructions for the call agent (the system prompt you write)", "type": ["string", "null"] }, "background_sound": { "type": "string", "enum": ["off", "office"] }, "outbound_greeting_message": { "type": ["string", "null"] }, "outbound_prompt": { "type": ["string", "null"] }, "inherits_workspace_default": { "type": "boolean" } }, "required": [ "voice_id", "voice_model_tier", "llm_model", "language", "speed", "greeting_message", "farewell_message", "prompt", "background_sound", "outbound_greeting_message", "outbound_prompt", "inherits_workspace_default" ], "additionalProperties": false }, "sms": { "type": "object", "properties": { "auto_reply_enabled": { "type": "boolean", "description": "Whether the AI answers texts to this number" }, "reply_delay_seconds": { "type": "integer", "minimum": 0, "maximum": 300 }, "skip_conditions": { "type": "array", "items": { "type": "string" }, "description": "Situations where the AI skips replying to a message" }, "prompt": { "description": "Custom instructions for the SMS agent", "type": ["string", "null"] }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "llm_model": { "anyOf": [ { "type": "string", "enum": [ "claude-haiku-5-5", "gpt-5.4-mini", "gpt-5-mini", "gemini-3.5-flash-lite", "gemini-3.8-flash" ] }, { "type": "null" } ] }, "stop_on_stop_word": { "type": "boolean" }, "stop_words": { "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "stop_after_replies": { "type": "boolean", "description": "Stop auto-replying to a contact after max_replies_per_contact" }, "max_replies_per_contact": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Default 50" }, "inherits_workspace_default": { "type": "boolean" } }, "required": [ "auto_reply_enabled", "reply_delay_seconds", "skip_conditions", "prompt", "language", "llm_model", "stop_on_stop_word", "stop_words", "stop_after_replies", "max_replies_per_contact", "inherits_workspace_default" ], "additionalProperties": false }, "knowledge": { "type": "object", "properties": { "knowledge_enabled": { "type": "boolean" }, "web_search_enabled": { "type": "boolean" }, "knowledge_base_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Knowledge documents the agent can reference" }, "faq_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "knowledge_enabled", "web_search_enabled", "knowledge_base_ids", "faq_ids" ], "additionalProperties": false }, "qualification": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "contact_info_collection": { "type": "array", "items": { "type": "string", "enum": [ "name", "business_name", "phone", "email", "address", "date_of_birth" ] } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question_text": { "type": "string", "minLength": 1 }, "type": { "default": "OPEN_ENDED", "type": "string", "enum": ["OPEN_ENDED", "YES_NO", "MULTIPLE_CHOICE", "SCALE"] }, "required": { "default": false, "type": "boolean" }, "is_qualifying": { "default": true, "type": "boolean" }, "options": { "description": "MULTIPLE_CHOICE options", "type": "array", "items": { "type": "string" } }, "qualifying_answers": { "type": "array", "items": { "type": "string" } }, "scale_min": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scale_max": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "qualifying_min_score": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "question_text", "type", "required", "is_qualifying"], "additionalProperties": false } } }, "required": ["enabled", "contact_info_collection", "questions"], "additionalProperties": false }, "booking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "event_type_ids": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Event types the agent can book" }, "confirmation_message": { "type": ["string", "null"] }, "minimum_notice_minutes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "available_hours": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } }, "required": ["start", "end"], "additionalProperties": false } }, { "type": "null" } ], "description": "Bookable windows per day, in the number's timezone. Two windows = a lunch break." }, "available_days": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, { "type": "null" } ], "description": "0 = Sunday … 6 = Saturday" } }, "required": [ "enabled", "event_type_ids", "confirmation_message", "minimum_notice_minutes", "available_hours", "available_days" ], "additionalProperties": false }, "transfers": { "type": "object", "properties": { "primary_transfer_number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "condition": { "type": "string", "enum": [ "human_requested", "after_hours", "qualification_failed", "qualification_passed", "urgent_request", "custom" ] }, "custom_condition": { "type": ["string", "null"] }, "action": { "type": "string", "enum": [ "transfer", "voicemail", "schedule_callback", "hang_up", "notify_and_end", "round_robin", "webhook" ] }, "target_number": { "type": ["string", "null"] }, "round_robin_numbers": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string", "format": "uri" }, "webhook_lead_source": { "type": "string" }, "notify_message": { "type": "string" }, "priority": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "default": true, "type": "boolean" } }, "required": ["id", "condition", "action", "priority", "enabled"], "additionalProperties": false } }, "office_hours_only": { "type": "boolean", "description": "Only transfer live calls inside the office-hours window" }, "office_hours_start": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "office_hours_end": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "office_hours_timezone": { "anyOf": [ {}, { "type": "null" } ] }, "outside_office_hours_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "primary_transfer_number", "rules", "office_hours_only", "office_hours_start", "office_hours_end", "office_hours_timezone", "outside_office_hours_message" ], "additionalProperties": false }, "sms_referrals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "condition": { "type": "string", "enum": [ "human_requested", "after_hours", "qualification_failed", "qualification_passed", "urgent_request", "custom" ] }, "custom_condition": { "type": ["string", "null"] }, "target_number": { "description": "The number the texter is told to text instead", "type": ["string", "null"] }, "priority": { "default": 0, "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "default": true, "type": "boolean" } }, "required": ["id", "condition", "priority", "enabled"], "additionalProperties": false } }, "forwarding": { "type": "object", "properties": { "phone_config_mode": { "type": "string", "enum": ["lumisreach_number", "existing_number"] }, "phone_service_type": { "anyOf": [ { "type": "string", "enum": ["cellphone", "voip", "landline"] }, { "type": "null" } ] }, "call_handling_mode": { "type": "string", "enum": ["ai_handles_all", "call_me_first"], "description": "call_me_first rings your phone(s) first and lets the AI take over if nobody answers" }, "forwarding_mode": { "anyOf": [ { "type": "string", "enum": ["single_target", "sequential_chain"] }, { "type": "null" } ] }, "forwarding_number": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "ring_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 5, "maximum": 60 }, { "type": "null" } ] }, "sequential_targets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "phone_number": { "type": "string" }, "label": { "type": "string", "maxLength": 50 }, "timeout_seconds": { "type": "integer", "minimum": 5, "maximum": 60 }, "active": { "default": true, "type": "boolean" } }, "required": ["id", "phone_number", "timeout_seconds", "active"], "additionalProperties": false } }, "chain_transition_message": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "record_human_calls": { "type": "boolean" }, "office_hours_enabled": { "type": "boolean" }, "office_hours_start": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "office_hours_end": { "anyOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, { "type": "null" } ] }, "carrier_forwarding_type": { "anyOf": [ { "type": "string", "enum": [ "forward_all", "forward_missed", "forward_busy", "forward_no_answer" ] }, { "type": "null" } ] }, "selected_carrier": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "setup_completed": { "type": "boolean" } }, "required": [ "phone_config_mode", "phone_service_type", "call_handling_mode", "forwarding_mode", "forwarding_number", "ring_duration_seconds", "sequential_targets", "chain_transition_message", "record_human_calls", "office_hours_enabled", "office_hours_start", "office_hours_end", "carrier_forwarding_type", "selected_carrier", "setup_completed" ], "additionalProperties": false }, "ivr": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "When on, the keypad menu answers calls INSTEAD of the AI agent" }, "greeting": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "menus": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Referenced by submenu actions. menus[0] is the main menu." }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "prompt": { "description": "Blank = generated from the option labels", "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "options": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#" ] }, "label": { "type": "string", "maxLength": 100 }, "action": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "transfer" }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "fallback_phone_number": { "anyOf": [ { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, { "type": "null" } ] } }, "required": ["type", "phone_number"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "submenu" }, "menu_id": { "type": "string", "minLength": 1 } }, "required": ["type", "menu_id"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "repeat" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "previous" } }, "required": ["type"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hangup" }, "message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": ["type"], "additionalProperties": false } ] } }, "required": ["key", "label", "action"], "additionalProperties": false } } }, "required": ["id", "name", "options"], "additionalProperties": false } }, "invalid_input_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "no_input_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "transfer_message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "transfer_caller_id": { "type": "string", "enum": ["business", "caller"] }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "speed": { "anyOf": [ { "type": "number", "minimum": 0.8, "maximum": 1.2 }, { "type": "null" } ] }, "timeout_seconds": { "type": "integer", "minimum": 3, "maximum": 15 }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 5 }, "fallback": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "transfer" }, "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } }, "required": ["type", "phone_number"], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hangup" }, "message": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": ["type"], "additionalProperties": false } ] } }, "required": [ "enabled", "greeting", "menus", "invalid_input_message", "no_input_message", "transfer_message", "transfer_caller_id", "voice_id", "speed", "timeout_seconds", "max_attempts", "fallback" ], "additionalProperties": false }, { "type": "null" } ], "description": "null until a phone menu has been set up" }, "updated_at": { "type": "string" } }, "required": [ "id", "phone_number", "provider", "stack", "agent_id", "name", "is_active", "business_name", "business_description", "timezone", "call_settings", "voice", "sms", "knowledge", "qualification", "booking", "transfers", "sms_referrals", "forwarding", "ivr", "updated_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/phone-numbers/{id}/voices": { "get": { "operationId": "v1_phone_numbers_id_voices_get", "tags": ["Phone Numbers"], "summary": "List voices for a number", "description": "The voices available to this number's call agent, which depend on its stack (T2 numbers use LiveKit voices, T1 numbers Cartesia/ElevenLabs voices). Pass a `voice_id` from here as `voice.voice_id` to `PATCH /v1/phone-numbers/{id}/config`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "voice_id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "gender": { "type": ["string", "null"] }, "accent": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "preview_audio_url": { "type": ["string", "null"] }, "supported_languages": { "type": "array", "items": { "type": "string" } }, "recommended": { "type": "boolean" } }, "required": [ "voice_id", "name", "provider", "gender", "accent", "description", "preview_audio_url", "supported_languages", "recommended" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/posts/{id}": { "delete": { "operationId": "v1_posts_id_delete", "tags": ["Videos"], "summary": "Cancel a scheduled post", "description": "Cancel a post that is still `scheduled`, before it goes out. A post already published or in progress cannot be canceled (400). Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string" } }, "required": ["id", "status"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/actions": { "get": { "operationId": "v1_quick_actions_get", "tags": ["Quick Agent Actions"], "summary": "List Quick Agent Action jobs", "description": "Returns the caller's recent Quick AI Phone Call and Quick AI Text jobs, newest first. Use `GET /v1/quick/actions/{id}` for per-number detail.", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": ["ai_call", "ai_text"] } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string" }, "status": { "type": "string" }, "goal": { "type": "string" }, "from_number": { "type": "string" }, "created_at": { "type": "string" } }, "required": ["id", "kind", "status", "goal", "from_number", "created_at"], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/quick/actions/{id}": { "get": { "operationId": "v1_quick_actions_id_get", "tags": ["Quick Agent Actions"], "summary": "Get a Quick Agent Action job", "description": "Per-number progress for a Quick AI Phone Call or Quick AI Text job: attempt counts, live call state, messages exchanged, whether the goal was met, and why each target stopped.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string" }, "status": { "type": "string" }, "goal": { "type": "string" }, "from_number": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "targets": { "type": "array", "items": { "type": "object", "properties": { "to_number": { "type": "string" }, "from_number": { "type": ["string", "null"] }, "status": { "type": "string" }, "live_call_status": { "type": ["string", "null"] }, "attempts": { "type": "number" }, "last_attempt_at": { "type": ["string", "null"] }, "last_call_id": { "type": ["string", "null"] }, "messages_sent": { "type": "number" }, "messages_received": { "type": "number" }, "goal_achieved": { "type": "boolean" }, "end_reason": { "type": ["string", "null"] }, "summary": { "type": ["string", "null"] } }, "required": [ "to_number", "from_number", "status", "live_call_status", "attempts", "last_attempt_at", "last_call_id", "messages_sent", "messages_received", "goal_achieved", "end_reason", "summary" ], "additionalProperties": false } }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "pending": { "type": "number" }, "in_progress": { "type": "number" }, "completed": { "type": "number" }, "no_answer": { "type": "number" }, "failed": { "type": "number" }, "opted_out": { "type": "number" }, "canceled": { "type": "number" } }, "required": [ "total", "pending", "in_progress", "completed", "no_answer", "failed", "opted_out", "canceled" ], "additionalProperties": false }, "created_at": { "type": "string" }, "completed_at": { "type": ["string", "null"] } }, "required": [ "id", "kind", "status", "goal", "from_number", "config", "targets", "counts", "created_at", "completed_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/quick/actions/{id}/cancel": { "post": { "operationId": "v1_quick_actions_id_cancel_post", "tags": ["Quick Agent Actions"], "summary": "Cancel a Quick Agent Action job", "description": "Stops remaining dials and AI text replies for the job. Calls already connected are allowed to finish. Cancelling is idempotent.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "canceled" }, "canceled_targets": { "type": "number" } }, "required": ["id", "status", "canceled_targets"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/ai-calls": { "post": { "operationId": "v1_quick_ai_calls_post", "tags": ["Quick Agent Actions"], "summary": "Start a Quick AI Phone Call", "description": "Has an AI agent call one or more recipients (phone numbers in any common format, +1 assumed when the country code is missing, or names of contacts in the workspace, matched case-insensitively with small typos tolerated; an ambiguous name is rejected with the candidates) to accomplish a goal. No phone-number purchase is required — the call is placed from a shared LumisReach number on the LumisReach Official account, and that is the number the recipient sees. Configure voice, language, goal, opening line, retry attempts and maximum call length per request. Billing: $0.20 per initiated call (each retry counts) plus $0.20 per minute of conversation, charged to the wallet of the organization that owns the API key. Shared numbers have a daily volume ceiling (75 calls once warmed up) so carriers do not flag them; a job spreads across the pool and each destination reports the `from_number` it used. Returns 202 with a job id; poll `GET /v1/quick/actions/{id}` for per-number progress. Returns 409 when the shared pool has no daily volume left.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "to_numbers": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Phone number in any common format (+1 assumed when missing) or a contact's name" }, "description": "Who to reach: phone numbers in any common format (415-555-0123, (415) 555-0123, +14155550123; +1 is assumed when the country code is missing) and/or names of contacts in the workspace (case-insensitive, small typos are fine). Each entry is detected automatically" }, "goal": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "What the AI should accomplish on the call. Drives the system prompt." }, "instructions": { "type": "string", "maxLength": 4000 }, "opening_message": { "type": "string", "maxLength": 500 }, "voice": { "type": "string", "maxLength": 120 }, "voice_model_tier": { "type": "string", "enum": ["standard", "mini"] }, "language": { "default": "en", "type": "string", "maxLength": 10 }, "retry_attempts": { "default": 1, "type": "integer", "minimum": 0, "maximum": 5 }, "retry_delay_minutes": { "default": 10, "type": "integer", "minimum": 1, "maximum": 1440 }, "max_call_duration_seconds": { "default": 600, "type": "integer", "minimum": 30, "maximum": 1800 }, "voicemail_enabled": { "default": true, "type": "boolean" }, "voicemail_message": { "type": "string", "maxLength": 600 }, "record": { "default": true, "type": "boolean" }, "contact_name": { "type": "string", "maxLength": 120 } }, "required": [ "to_numbers", "goal", "language", "retry_attempts", "retry_delay_minutes", "max_call_duration_seconds", "voicemail_enabled", "record" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "ai_call" }, "status": { "type": "string" }, "from_number": { "type": "string" }, "target_count": { "type": "number" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "to_number": { "type": "string" }, "contact_id": { "type": ["string", "null"] }, "contact_name": { "type": ["string", "null"] } }, "required": ["input", "to_number", "contact_id", "contact_name"], "additionalProperties": false } }, "status_url": { "type": "string" }, "pricing": { "type": "object", "properties": { "start_fee_usd": { "type": "number" }, "per_minute_usd": { "type": "number" }, "note": { "type": "string" } }, "required": ["start_fee_usd", "per_minute_usd", "note"], "additionalProperties": false } }, "required": [ "id", "kind", "status", "from_number", "target_count", "recipients", "status_url", "pricing" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/ai-numbers": { "post": { "operationId": "v1_quick_ai_numbers_post", "tags": ["Quick Agent Actions"], "summary": "Buy a phone number and set up its AI agent", "description": "Provisions a new Telnyx number on the LiveKit stack and configures the AI agent that answers it — business context, system prompt, greeting, voice and language — in a single request. Set `handle_calls` (default true) for inbound AI call answering and `handle_texts` (default false) to have the same agent answer inbound SMS on the number. Returns 202; poll `GET /v1/quick/ai-numbers/{id}` until `status` is `ready`. Billing: the number's $5/month line fee is charged immediately to the organization that owns the API key; calls and texts on your own number are billed at your plan's rates, not the Quick Action rates.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "phone_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "area_code": { "type": "string", "pattern": "^\\d{3}$" }, "name": { "type": "string", "maxLength": 120 }, "business_name": { "type": "string", "maxLength": 200 }, "business_description": { "type": "string", "maxLength": 4000 }, "agent_prompt": { "type": "string", "maxLength": 8000 }, "greeting": { "type": "string", "maxLength": 500 }, "voice": { "type": "string", "maxLength": 120 }, "voice_model_tier": { "type": "string", "enum": ["standard", "mini"] }, "language": { "default": "en", "type": "string", "maxLength": 10 }, "timezone": { "type": "string", "maxLength": 64 }, "handle_calls": { "default": true, "type": "boolean" }, "handle_texts": { "default": false, "type": "boolean" }, "sms_prompt": { "type": "string", "maxLength": 8000 } }, "required": ["language", "handle_calls", "handle_texts"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "status": { "type": "string", "const": "provisioning" }, "workflow_run_id": { "type": "string" }, "handles_calls": { "type": "boolean" }, "handles_texts": { "type": "boolean" }, "status_url": { "type": "string" } }, "required": [ "id", "status", "workflow_run_id", "handles_calls", "handles_texts", "status_url" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/ai-numbers/{id}": { "get": { "operationId": "v1_quick_ai_numbers_id_get", "tags": ["Quick Agent Actions"], "summary": "Get AI phone number status", "description": "Provisioning state plus the configured agent for a number created with `POST /v1/quick/ai-numbers`. `status` is `provisioning` while the number is being wired up, `ready` once it can take calls, and `failed` if provisioning could not complete.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "number" }, "phone_number": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] }, "status": { "type": "string" }, "subscription_status": { "type": ["string", "null"] }, "provider": { "type": "string" }, "telephony_region": { "type": "string" }, "handles_calls": { "type": "boolean" }, "handles_texts": { "type": "boolean" }, "sms_registered": { "type": "boolean" }, "agent": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "voice": { "type": ["string", "null"] }, "language": { "type": "string" }, "greeting": { "type": ["string", "null"] }, "prompt": { "type": ["string", "null"] } }, "required": ["id", "name", "voice", "language", "greeting", "prompt"], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "type": "string" } }, "required": [ "id", "phone_number", "name", "status", "subscription_status", "provider", "telephony_region", "handles_calls", "handles_texts", "sms_registered", "agent", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["phone_numbers:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/quick/ai-texts": { "post": { "operationId": "v1_quick_ai_texts_post", "tags": ["Quick Agent Actions"], "summary": "Start a Quick AI Text conversation", "description": "Has an AI agent text one or more recipients (phone numbers in any common format, +1 assumed when the country code is missing, or names of contacts in the workspace, matched case-insensitively with small typos tolerated; an ambiguous name is rejected with the candidates) and keep the conversation going until the goal is met. No phone-number purchase is required — messages are sent from a shared LumisReach number that is already registered on the approved LumisReach A2P 10DLC campaign. Supply `first_message` or let the agent write the opener from the goal. STOP is honored automatically. Shared numbers have a daily volume ceiling (500 messages) so carriers do not throttle the shared campaign; a job spreads across the pool and each destination reports the `from_number` it used. Billing: $0.05 per outbound message (opener and every AI reply; inbound replies are free), charged to the wallet of the organization that owns the API key. Returns 409 when the shared pool has no daily volume left.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "to_numbers": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Phone number in any common format (+1 assumed when missing) or a contact's name" }, "description": "Who to reach: phone numbers in any common format (415-555-0123, (415) 555-0123, +14155550123; +1 is assumed when the country code is missing) and/or names of contacts in the workspace (case-insensitive, small typos are fine). Each entry is detected automatically" }, "goal": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "What the AI should accomplish over the thread. Drives the system prompt." }, "first_message": { "type": "string", "minLength": 1, "maxLength": 1200 }, "instructions": { "type": "string", "maxLength": 4000 }, "language": { "default": "en", "type": "string", "maxLength": 10 }, "max_messages": { "default": 15, "description": "Most messages the AI sends on each thread, opener included, before it ends the conversation (default 15, max 20). The recipient's replies do not count toward it", "type": "integer", "minimum": 1, "maximum": 20 }, "reply_delay_seconds": { "default": 0, "type": "integer", "minimum": 0, "maximum": 300 }, "conversation_timeout_hours": { "default": 48, "type": "integer", "minimum": 1, "maximum": 168 }, "contact_name": { "type": "string", "maxLength": 120 } }, "required": [ "to_numbers", "goal", "language", "max_messages", "reply_delay_seconds", "conversation_timeout_hours" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "ai_text" }, "status": { "type": "string" }, "from_number": { "type": "string" }, "target_count": { "type": "number" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "to_number": { "type": "string" }, "contact_id": { "type": ["string", "null"] }, "contact_name": { "type": ["string", "null"] } }, "required": ["input", "to_number", "contact_id", "contact_name"], "additionalProperties": false } }, "status_url": { "type": "string" }, "pricing": { "type": "object", "properties": { "per_message_usd": { "type": "number" }, "note": { "type": "string" } }, "required": ["per_message_usd", "note"], "additionalProperties": false } }, "required": [ "id", "kind", "status", "from_number", "target_count", "recipients", "status_url", "pricing" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/chat-channels": { "get": { "operationId": "v1_quick_chat_channels_get", "tags": ["Quick Agent Actions"], "summary": "List connected chat channels", "description": "Returns the Slack and Discord channels connected to the workspace (Dashboard > Connections > Team chat, or `POST /v1/quick/chat-channels`). Use a channel's `id` with `POST /v1/quick/chat-messages`. Webhook URLs are never returned.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "platform": { "type": "string", "enum": ["slack", "discord"] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "last_used_at": { "type": ["string", "null"] } }, "required": ["id", "platform", "name", "created_at", "last_used_at"], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["chat:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_quick_chat_channels_post", "tags": ["Quick Agent Actions"], "summary": "Connect a chat channel", "description": "Connects a Slack or Discord channel through an incoming-webhook URL (Slack: https://api.slack.com/messaging/webhooks; Discord: Channel Settings > Integrations > Webhooks > New Webhook > Copy Webhook URL). A short confirmation message is posted to the channel first; if the webhook does not accept it, nothing is saved (400). The URL is stored encrypted and never returned.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "platform": { "type": "string", "enum": ["slack", "discord"], "description": "Which chat app the webhook belongs to." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A label for the channel, e.g. \"#sales\"." }, "webhook_url": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The incoming-webhook URL: https://hooks.slack.com/services/... for Slack, https://discord.com/api/webhooks// for Discord." } }, "required": ["platform", "name", "webhook_url"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "platform": { "type": "string", "enum": ["slack", "discord"] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "last_used_at": { "type": ["string", "null"] } }, "required": ["id", "platform", "name", "created_at", "last_used_at"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["chat:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/chat-messages": { "post": { "operationId": "v1_quick_chat_messages_post", "tags": ["Quick Agent Actions"], "summary": "Send a quick chat message", "description": "Posts one plain-text message (up to 2000 characters) to a Slack or Discord channel connected to the workspace (see `GET /v1/quick/chat-channels`). Mentions such as @channel, @here, @everyone and user or role pings are neutralized. 404 when the channel id is not connected to the workspace; 409 when the webhook was revoked or the chat app rejected the message (reconnect it in Connections), or past 1000 messages per workspace per rolling 24 hours. Free.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "channel_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "A connected channel id from GET /v1/quick/chat-channels." }, "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Plain text, up to 2000 characters. @channel/@here/@everyone and user mentions are not triggered." } }, "required": ["channel_id", "text"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "chat_message" }, "status": { "type": "string", "const": "sent" }, "channel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "platform": { "type": "string", "enum": ["slack", "discord"] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "last_used_at": { "type": ["string", "null"] } }, "required": ["id", "platform", "name", "created_at", "last_used_at"], "additionalProperties": false } }, "required": ["id", "kind", "status", "channel"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["chat:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/emails": { "post": { "operationId": "v1_quick_emails_post", "tags": ["Quick Agent Actions"], "summary": "Send a Quick Email", "description": "Sends one plain-text email to up to 20 recipients (each gets an individual copy). Each `to` entry is an email address or the name of a contact in the workspace, matched case-insensitively with small typos tolerated, whose email on file is used; a name that matches no one returns 404, and one that could be two people returns 422 listing the candidates. It goes out from a shared LumisReach address, shown as \" via LumisReach\". No sending domain is required. Replies go to `reply_to`, defaulting to the email of the user who owns the API key. Recipients on the workspace's suppression list (unsubscribes, bounces) are skipped and reported in `suppressed`. Limited to 200 recipients per workspace per rolling 24 hours (409 past it); for bulk or marketing email use your own verified domain. Billing: $0.01 per recipient sent to, charged to the wallet of the organization that owns the API key; 403 when the wallet cannot cover it.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 254 }, "description": "Recipients: email addresses and/or names of contacts in the workspace (case-insensitive, small typos are fine; the contact's email on file is used). Each gets an individual copy; they do not see each other" }, "subject": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 20000 }, "reply_to": { "type": "string", "maxLength": 254, "pattern": "^[^\\s@<>(),;:\"]+@[^\\s@<>(),;:\"]+\\.[a-z]{2,}$" }, "from_name": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": ["to", "subject", "body"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "email" }, "status": { "type": "string", "const": "sent" }, "from": { "type": "string" }, "reply_to": { "type": ["string", "null"] }, "sent_to": { "type": "array", "items": { "type": "string" } }, "suppressed": { "type": "array", "items": { "type": "string" } }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "email": { "type": "string" }, "contact_id": { "type": ["string", "null"] }, "contact_name": { "type": ["string", "null"] } }, "required": ["input", "email", "contact_id", "contact_name"], "additionalProperties": false } }, "cost_usd": { "type": "number" }, "pricing": { "type": "object", "properties": { "per_recipient_usd": { "type": "number" }, "note": { "type": "string" } }, "required": ["per_recipient_usd", "note"], "additionalProperties": false } }, "required": [ "id", "kind", "status", "from", "reply_to", "sent_to", "suppressed", "recipients", "cost_usd", "pricing" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["email:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/imessages": { "post": { "operationId": "v1_quick_imessages_post", "tags": ["Quick Agent Actions"], "summary": "Send a Quick iMessage", "description": "Sends one iMessage to one person (E.164 phone number or Apple ID email) from a shared LumisReach iMessage line, so no Apple device or line has to be owned. One-way: replies are not delivered back to the API yet. Apple filters unsolicited blue bubbles hard, so: a first message to someone the line has never messaged cannot contain a link (400), the shared line opens a limited number of new conversations per day across all customers (409 when spent), each workspace may send 20 per rolling 24 hours (409), and numbers on the workspace's opt-out list are refused (403). Returns 409 while iMessage is not enabled on the deployment. Billing: $0.10 per message sent, charged to the wallet of the organization that owns the API key.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "to": { "type": "string", "maxLength": 254, "pattern": "^(\\+[1-9]\\d{1,14}|[^\\s@<>(),;:\"]+@[^\\s@<>(),;:\"]+\\.[a-zA-Z]{2,})$", "description": "Recipient: E.164 phone (+14155550123) or the email address of their Apple ID" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": ["to", "text"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "imessage" }, "status": { "type": "string", "const": "sent" }, "to": { "type": "string" }, "from": { "type": "string" }, "cost_usd": { "type": "number" }, "pricing": { "type": "object", "properties": { "per_message_usd": { "type": "number" }, "note": { "type": "string" } }, "required": ["per_message_usd", "note"], "additionalProperties": false } }, "required": ["id", "kind", "status", "to", "from", "cost_usd", "pricing"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["imessage:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/quick/texts": { "post": { "operationId": "v1_quick_texts_post", "tags": ["Quick Agent Actions"], "summary": "Send a single text message", "description": "Sends one SMS, exactly as written, to one phone number. No phone-number purchase is required: it goes out from a shared LumisReach number that is already registered on the approved LumisReach A2P 10DLC campaign, and `from_number` in the response is the number the recipient sees. Unlike `POST /v1/quick/ai-texts`, there is no AI conversation: replies are not answered. Opt-out language is appended when the recipient has not been texted by this workspace before, and numbers on the workspace's opt-out list are refused (403). Synchronous: returns 200 once the carrier has accepted the message. Billing: $0.05 per message, charged to the wallet of the organization that owns the API key. Returns 409 when the shared pool has no daily volume left.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "to_number": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "description": "Destination in E.164 format" }, "message": { "type": "string", "minLength": 1, "maxLength": 1600, "description": "The text to send, exactly as the recipient should see it" } }, "required": ["to_number", "message"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "text" }, "status": { "type": "string", "const": "sent" }, "to_number": { "type": "string" }, "from_number": { "type": "string" }, "message_id": { "type": "string" }, "cost_usd": { "type": "number" }, "status_url": { "type": "string" } }, "required": [ "id", "kind", "status", "to_number", "from_number", "message_id", "cost_usd", "status_url" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/sms/send": { "post": { "operationId": "v1_sms_send_post", "tags": ["SMS"], "summary": "Send an SMS message", "description": "Sends an outbound SMS from the specified Telnyx phone number. The 'from' number must be an active Telnyx phone number owned by the authenticated organization.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "to": { "type": "string", "minLength": 1 }, "from": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": ["to", "from", "message"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:write"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/sms/stream": { "get": { "operationId": "v1_sms_stream_get", "tags": ["SMS"], "summary": "Stream inbound texts", "description": "A Server-Sent Events stream of texts people send to the workspace's numbers, on either carrier. Sends `connected` first, then one `sms_received` event per text (its `data` has `message_id`, `from`, `to`, `body` and `received_at`), and a `: heartbeat` comment every 30 seconds. Each `sms_received` carries an SSE `id`: reconnect with it in the `Last-Event-ID` header to resume without missing a text. A stream stays open for up to about 5 minutes, then closes so you reconnect. For server-to-server delivery prefer the signed, retried `POST /v1/sms/webhooks`. Free.", "responses": { "200": { "description": "An open Server-Sent Events stream of `connected` and `sms_received` events", "content": { "text/event-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/sms/webhooks": { "get": { "operationId": "v1_sms_webhooks_get", "tags": ["SMS"], "summary": "List inbound SMS webhooks", "description": "The URLs registered to receive an `sms.received` event whenever someone texts one of the workspace's numbers. Signing secrets are never returned.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "active": { "type": "boolean" }, "phone_number_id": { "type": ["number", "null"] }, "phone_number": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "const": "sms.received" } }, "created_at": { "type": "string" } }, "required": [ "id", "url", "description", "active", "phone_number_id", "phone_number", "events", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_sms_webhooks_post", "tags": ["SMS"], "summary": "Create an inbound SMS webhook", "description": "Registers an HTTPS URL that LumisReach POSTs an `sms.received` event to whenever someone texts one of your numbers (or only `phone_number_id`, if given). The event says who texted (`from` plus their contact record), which of your numbers they texted (`to`) and what they said. Works on both voice/SMS stacks. Each delivery is signed with `X-LumisReach-Signature-256` (hex HMAC-SHA256 of the raw body, keyed with the `secret` returned here once). A delivery that fails or gets a non-2xx response is retried 3 times over about 36 minutes.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS endpoint that receives a POST for every inbound text" }, "phone_number_id": { "description": "Only texts to this number (id from `GET /v1/phone-numbers`). Omit for all your numbers.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "description": "A label for the webhook", "type": "string", "maxLength": 100 } }, "required": ["url"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "active": { "type": "boolean" }, "phone_number_id": { "type": ["number", "null"] }, "phone_number": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "const": "sms.received" } }, "created_at": { "type": "string" }, "secret": { "type": "string", "description": "Signing secret. Every delivery carries `X-LumisReach-Signature-256`: the hex HMAC-SHA256 of the raw body with this secret. Shown once." } }, "required": [ "id", "url", "description", "active", "phone_number_id", "phone_number", "events", "created_at", "secret" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:read"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/sms/webhooks/{id}": { "delete": { "operationId": "v1_sms_webhooks_id_delete", "tags": ["SMS"], "summary": "Delete an inbound SMS webhook", "description": "Stops `sms.received` deliveries to this webhook. Retries already scheduled for it are dropped.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": ["id", "deleted"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:read"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/sms/webhooks/{id}/test": { "post": { "operationId": "v1_sms_webhooks_id_test_post", "tags": ["SMS"], "summary": "Send a test inbound SMS event", "description": "POSTs a sample, correctly signed `sms.received` event (with `test: true`) to the webhook right away and reports how your server answered. Not retried.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "status": { "type": ["number", "null"] }, "error": { "type": ["string", "null"] } }, "required": ["delivered", "status", "error"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sms:read"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/social-connections": { "get": { "operationId": "v1_social_connections_get", "tags": ["Videos"], "summary": "List social connections", "description": "The TikTok, Instagram, Facebook, X, LinkedIn and YouTube accounts connected to the workspace (Dashboard → Connections). Pass their `id`s as `connection_ids` to post a video or run a posting schedule. Accounts are connected in the dashboard. Free.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "account_name": { "type": ["string", "null"] }, "account_handle": { "type": ["string", "null"] }, "avatar_url": { "type": ["string", "null"] }, "connected_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "provider", "account_name", "account_handle", "avatar_url", "connected_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/sub-entities": { "get": { "operationId": "v1_sub_entities_get", "tags": ["Sub-entities"], "summary": "List sub-entities under the caller's umbrella organization", "description": "Every managed child organization (sub-entity) of the authenticated org. Each entry includes member + phone-number counts so the caller can tell which sub-entities are live.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": ["string", "null"] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sub_entities:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_sub_entities_post", "tags": ["Sub-entities"], "summary": "Create a sub-entity under the caller's umbrella organization", "description": "Creates a new managed child organization. When the key carries a user, that user becomes the owner. HIPAA is opt-in per sub-entity via PATCH, so the new sub-entity starts HIPAA-disabled.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "slug": { "type": "string", "pattern": "^[a-z0-9-]{1,64}$" } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": ["string", "null"] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sub_entities:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/sub-entities/{id}": { "get": { "operationId": "v1_sub_entities_id_get", "tags": ["Sub-entities"], "summary": "Retrieve a sub-entity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": ["string", "null"] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sub_entities:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_sub_entities_id_patch", "tags": ["Sub-entities"], "summary": "Update a sub-entity", "description": "Rename or flip the `hipaa_enabled` flag. Flipping `hipaa_enabled=false` on an org with enrolled reputation numbers that require BAA coverage will surface a warning but succeed — audit the downstream state after.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "hipaa_enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "slug": { "type": ["string", "null"] }, "parent_organization_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hipaa_enabled": { "type": "boolean" }, "member_count": { "type": "number" }, "phone_number_count": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "parent_organization_id", "hipaa_enabled", "member_count", "phone_number_count", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["sub_entities:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/usage": { "get": { "operationId": "v1_usage_get", "tags": ["Usage"], "summary": "Current-month usage rollup", "description": "Aggregated counts across all numbers the key can see: outbound calls, minutes used, and spam-risk distribution across enrolled numbers.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "period_start": { "type": "string" }, "period_end": { "type": "string" }, "calls_placed": { "type": "number" }, "minutes_used": { "type": "number" }, "phone_numbers_active": { "type": "number" }, "spam_risk_distribution": { "type": "object", "properties": { "low": { "type": "number" }, "medium": { "type": "number" }, "high": { "type": "number" }, "unknown": { "type": "number" } }, "required": ["low", "medium", "high", "unknown"], "additionalProperties": false } }, "required": [ "period_start", "period_end", "calls_placed", "minutes_used", "phone_numbers_active", "spam_risk_distribution" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["usage:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/video-schedules": { "get": { "operationId": "v1_video_schedules_get", "tags": ["Video schedules"], "summary": "List video schedules", "description": "The workspace's posting schedules (Dashboard → Create Video → Schedules), newest first, with when each next runs and about what each video costs. Free.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["active", "paused", "completed"], "description": "`completed` once it ran through `ends_on`" }, "cadence": { "type": "string", "description": "In words, e.g. \"2 videos every Mon, Wed, Fri at 9am\"" }, "videos_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "post_hour": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "time_zone": { "type": "string" }, "starts_on": { "type": "string" }, "ends_on": { "type": ["string", "null"] }, "skip_dates": { "type": "array", "items": { "type": "string" } }, "notify_hours_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notify_by_email": { "type": "boolean" }, "connection_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "caption": { "type": ["string", "null"] }, "direction": { "type": ["string", "null"] }, "allowed_templates": { "type": "array", "items": { "type": "string" } }, "video_settings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "source_url": { "type": "string", "format": "uri" }, "source_text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "preset": { "type": "string" }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right"] }, "avatar_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "type": "string" }, "video_model": { "type": "string" }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_size": { "type": "string", "enum": ["small", "medium", "large"] } }, "additionalProperties": false }, { "type": "null" } ] }, "source_video_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "next_run": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "string" }, "post_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "plan_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that day's videos are planned and made" } }, "required": ["day", "post_at", "plan_at"], "additionalProperties": false }, { "type": "null" } ] }, "last_run_on": { "type": ["string", "null"] }, "last_error": { "type": ["string", "null"] }, "estimated_price_cents_per_video": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About what each video costs. Each one is charged when its script is approved, like any other video." }, "estimate_depends_on_template": { "type": "boolean", "description": "True when the director picks the template per video, so the real price can differ" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "status", "cadence", "videos_per_day", "days_of_week", "post_hour", "time_zone", "starts_on", "ends_on", "skip_dates", "notify_hours_before", "notify_by_email", "connection_ids", "caption", "direction", "allowed_templates", "video_settings", "source_video_id", "next_run", "last_run_on", "last_error", "estimated_price_cents_per_video", "estimate_depends_on_template", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_video_schedules_post", "tags": ["Video schedules"], "summary": "Create a video schedule", "description": "Keep making videos and posting them on a cadence: `videos_per_day` on `days_of_week` at `post_hour` in `time_zone`, to `connection_ids`. Before each posting day (`notify_hours_before`), an AI director picks each video's template, angle and script from your marketing profile, `direction` and what is trending; the videos are then made and posted with no review. Pin parts of the recipe with `video_settings` or `allowed_templates`, or model it on a video with `source_video_id`. Creating a schedule is free. Each video it makes is charged when its script is approved, like any other video; `estimated_price_cents_per_video` is about what each costs.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "videos_per_day": { "type": "integer", "minimum": 1, "maximum": 10 }, "days_of_week": { "description": "0 = Sunday to 6 = Saturday. Omit or empty for every day.", "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "post_hour": { "description": "Hour of the day posts go out. Default 9.", "type": "integer", "minimum": 0, "maximum": 23 }, "time_zone": { "description": "IANA time zone, e.g. America/New_York. Default UTC.", "type": "string", "minLength": 1, "maxLength": 64 }, "starts_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "First posting day, YYYY-MM-DD" }, "ends_on": { "description": "Last posting day. Omit or null to run until paused.", "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "connection_ids": { "minItems": 1, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Accounts every video is posted to" }, "caption": { "description": "One caption for every post. Omit to have one written per video.", "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "direction": { "description": "What the videos should be about, in your words", "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "allowed_templates": { "description": "Templates the director may pick from. Omit or empty for any it can make.", "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage" ] } }, "notify_hours_before": { "description": "How far ahead the videos are planned and you are told what is coming. Default 1.", "type": "integer", "minimum": 0, "maximum": 24 }, "notify_by_email": { "type": "boolean" }, "video_settings": { "description": "Recipe parts pinned for every video: presenter, style, format, length, source.", "type": "object", "properties": { "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "source_url": { "type": "string", "format": "uri" }, "source_text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "preset": { "type": "string" }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right"] }, "avatar_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "type": "string" }, "video_model": { "type": "string" }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_size": { "type": "string", "enum": ["small", "medium", "large"] } }, "additionalProperties": false }, "source_video_id": { "description": "Model the schedule on this video: its template and recipe are pinned", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["name", "videos_per_day", "starts_on", "connection_ids"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["active", "paused", "completed"], "description": "`completed` once it ran through `ends_on`" }, "cadence": { "type": "string", "description": "In words, e.g. \"2 videos every Mon, Wed, Fri at 9am\"" }, "videos_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "post_hour": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "time_zone": { "type": "string" }, "starts_on": { "type": "string" }, "ends_on": { "type": ["string", "null"] }, "skip_dates": { "type": "array", "items": { "type": "string" } }, "notify_hours_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notify_by_email": { "type": "boolean" }, "connection_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "caption": { "type": ["string", "null"] }, "direction": { "type": ["string", "null"] }, "allowed_templates": { "type": "array", "items": { "type": "string" } }, "video_settings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "source_url": { "type": "string", "format": "uri" }, "source_text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "preset": { "type": "string" }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right"] }, "avatar_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "type": "string" }, "video_model": { "type": "string" }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_size": { "type": "string", "enum": ["small", "medium", "large"] } }, "additionalProperties": false }, { "type": "null" } ] }, "source_video_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "next_run": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "string" }, "post_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "plan_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that day's videos are planned and made" } }, "required": ["day", "post_at", "plan_at"], "additionalProperties": false }, { "type": "null" } ] }, "last_run_on": { "type": ["string", "null"] }, "last_error": { "type": ["string", "null"] }, "estimated_price_cents_per_video": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About what each video costs. Each one is charged when its script is approved, like any other video." }, "estimate_depends_on_template": { "type": "boolean", "description": "True when the director picks the template per video, so the real price can differ" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "status", "cadence", "videos_per_day", "days_of_week", "post_hour", "time_zone", "starts_on", "ends_on", "skip_dates", "notify_hours_before", "notify_by_email", "connection_ids", "caption", "direction", "allowed_templates", "video_settings", "source_video_id", "next_run", "last_run_on", "last_error", "estimated_price_cents_per_video", "estimate_depends_on_template", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/video-schedules/{id}": { "get": { "operationId": "v1_video_schedules_id_get", "tags": ["Video schedules"], "summary": "Get a video schedule", "description": "A posting schedule: its cadence, accounts, pinned recipe, `next_run`, the last error if a video did not go out, and about what each video costs. Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["active", "paused", "completed"], "description": "`completed` once it ran through `ends_on`" }, "cadence": { "type": "string", "description": "In words, e.g. \"2 videos every Mon, Wed, Fri at 9am\"" }, "videos_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "post_hour": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "time_zone": { "type": "string" }, "starts_on": { "type": "string" }, "ends_on": { "type": ["string", "null"] }, "skip_dates": { "type": "array", "items": { "type": "string" } }, "notify_hours_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notify_by_email": { "type": "boolean" }, "connection_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "caption": { "type": ["string", "null"] }, "direction": { "type": ["string", "null"] }, "allowed_templates": { "type": "array", "items": { "type": "string" } }, "video_settings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "source_url": { "type": "string", "format": "uri" }, "source_text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "preset": { "type": "string" }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right"] }, "avatar_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "type": "string" }, "video_model": { "type": "string" }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_size": { "type": "string", "enum": ["small", "medium", "large"] } }, "additionalProperties": false }, { "type": "null" } ] }, "source_video_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "next_run": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "string" }, "post_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "plan_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that day's videos are planned and made" } }, "required": ["day", "post_at", "plan_at"], "additionalProperties": false }, { "type": "null" } ] }, "last_run_on": { "type": ["string", "null"] }, "last_error": { "type": ["string", "null"] }, "estimated_price_cents_per_video": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About what each video costs. Each one is charged when its script is approved, like any other video." }, "estimate_depends_on_template": { "type": "boolean", "description": "True when the director picks the template per video, so the real price can differ" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "status", "cadence", "videos_per_day", "days_of_week", "post_hour", "time_zone", "starts_on", "ends_on", "skip_dates", "notify_hours_before", "notify_by_email", "connection_ids", "caption", "direction", "allowed_templates", "video_settings", "source_video_id", "next_run", "last_run_on", "last_error", "estimated_price_cents_per_video", "estimate_depends_on_template", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "patch": { "operationId": "v1_video_schedules_id_patch", "tags": ["Video schedules"], "summary": "Update a video schedule", "description": "Change any of a schedule's fields; the ones you leave out stay as they are. `video_settings` is merged over the pinned recipe. Pause with `status: paused` and resume with `status: active`. Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "videos_per_day": { "type": "integer", "minimum": 1, "maximum": 10 }, "days_of_week": { "description": "0 = Sunday to 6 = Saturday. Omit or empty for every day.", "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "post_hour": { "description": "Hour of the day posts go out. Default 9.", "type": "integer", "minimum": 0, "maximum": 23 }, "time_zone": { "description": "IANA time zone, e.g. America/New_York. Default UTC.", "type": "string", "minLength": 1, "maxLength": 64 }, "starts_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "First posting day, YYYY-MM-DD" }, "ends_on": { "description": "Last posting day. Omit or null to run until paused.", "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "connection_ids": { "minItems": 1, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Accounts every video is posted to" }, "caption": { "description": "One caption for every post. Omit to have one written per video.", "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "direction": { "description": "What the videos should be about, in your words", "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "allowed_templates": { "description": "Templates the director may pick from. Omit or empty for any it can make.", "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage" ] } }, "notify_hours_before": { "description": "How far ahead the videos are planned and you are told what is coming. Default 1.", "type": "integer", "minimum": 0, "maximum": 24 }, "notify_by_email": { "type": "boolean" }, "video_settings": { "description": "Recipe parts pinned for every video: presenter, style, format, length, source.", "type": "object", "properties": { "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "source_url": { "type": "string", "format": "uri" }, "source_text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "preset": { "type": "string" }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right"] }, "avatar_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "type": "string" }, "video_model": { "type": "string" }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_size": { "type": "string", "enum": ["small", "medium", "large"] } }, "additionalProperties": false }, "status": { "description": "Pause or resume the schedule", "type": "string", "enum": ["active", "paused"] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["active", "paused", "completed"], "description": "`completed` once it ran through `ends_on`" }, "cadence": { "type": "string", "description": "In words, e.g. \"2 videos every Mon, Wed, Fri at 9am\"" }, "videos_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "post_hour": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "time_zone": { "type": "string" }, "starts_on": { "type": "string" }, "ends_on": { "type": ["string", "null"] }, "skip_dates": { "type": "array", "items": { "type": "string" } }, "notify_hours_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notify_by_email": { "type": "boolean" }, "connection_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "caption": { "type": ["string", "null"] }, "direction": { "type": ["string", "null"] }, "allowed_templates": { "type": "array", "items": { "type": "string" } }, "video_settings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "source_url": { "type": "string", "format": "uri" }, "source_text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "preset": { "type": "string" }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right"] }, "avatar_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "type": "string" }, "video_model": { "type": "string" }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_size": { "type": "string", "enum": ["small", "medium", "large"] } }, "additionalProperties": false }, { "type": "null" } ] }, "source_video_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "next_run": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "string" }, "post_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "plan_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that day's videos are planned and made" } }, "required": ["day", "post_at", "plan_at"], "additionalProperties": false }, { "type": "null" } ] }, "last_run_on": { "type": ["string", "null"] }, "last_error": { "type": ["string", "null"] }, "estimated_price_cents_per_video": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About what each video costs. Each one is charged when its script is approved, like any other video." }, "estimate_depends_on_template": { "type": "boolean", "description": "True when the director picks the template per video, so the real price can differ" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "status", "cadence", "videos_per_day", "days_of_week", "post_hour", "time_zone", "starts_on", "ends_on", "skip_dates", "notify_hours_before", "notify_by_email", "connection_ids", "caption", "direction", "allowed_templates", "video_settings", "source_video_id", "next_run", "last_run_on", "last_error", "estimated_price_cents_per_video", "estimate_depends_on_template", "created_at" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } }, "delete": { "operationId": "v1_video_schedules_id_delete", "tags": ["Video schedules"], "summary": "Delete a video schedule", "description": "Stop and remove a posting schedule. The videos it already made, and their posts, stay.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "deleted": { "type": "boolean", "const": true } }, "required": ["id", "deleted"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/video-schedules/{id}/skip": { "post": { "operationId": "v1_video_schedules_id_skip_post", "tags": ["Video schedules"], "summary": "Skip a posting day", "description": "Skip one posting day of a schedule: nothing is made, charged or posted that day. Send `{}` to skip the next one, or `day` (YYYY-MM-DD, in the schedule's time zone) for another. Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "day": { "description": "The posting day to skip. Omit for the next one.", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "skipped": { "type": "string" }, "schedule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["active", "paused", "completed"], "description": "`completed` once it ran through `ends_on`" }, "cadence": { "type": "string", "description": "In words, e.g. \"2 videos every Mon, Wed, Fri at 9am\"" }, "videos_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "days_of_week": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "post_hour": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "time_zone": { "type": "string" }, "starts_on": { "type": "string" }, "ends_on": { "type": ["string", "null"] }, "skip_dates": { "type": "array", "items": { "type": "string" } }, "notify_hours_before": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notify_by_email": { "type": "boolean" }, "connection_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "caption": { "type": ["string", "null"] }, "direction": { "type": ["string", "null"] }, "allowed_templates": { "type": "array", "items": { "type": "string" } }, "video_settings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "source_url": { "type": "string", "format": "uri" }, "source_text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "preset": { "type": "string" }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right"] }, "avatar_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "type": "string" }, "video_model": { "type": "string" }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_size": { "type": "string", "enum": ["small", "medium", "large"] } }, "additionalProperties": false }, { "type": "null" } ] }, "source_video_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "next_run": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "string" }, "post_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "plan_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When that day's videos are planned and made" } }, "required": ["day", "post_at", "plan_at"], "additionalProperties": false }, { "type": "null" } ] }, "last_run_on": { "type": ["string", "null"] }, "last_error": { "type": ["string", "null"] }, "estimated_price_cents_per_video": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "About what each video costs. Each one is charged when its script is approved, like any other video." }, "estimate_depends_on_template": { "type": "boolean", "description": "True when the director picks the template per video, so the real price can differ" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "status", "cadence", "videos_per_day", "days_of_week", "post_hour", "time_zone", "starts_on", "ends_on", "skip_dates", "notify_hours_before", "notify_by_email", "connection_ids", "caption", "direction", "allowed_templates", "video_settings", "source_video_id", "next_run", "last_run_on", "last_error", "estimated_price_cents_per_video", "estimate_depends_on_template", "created_at" ], "additionalProperties": false } }, "required": ["skipped", "schedule"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/video-schedules/{id}/videos": { "get": { "operationId": "v1_video_schedules_id_videos_get", "tags": ["Video schedules"], "summary": "List a schedule's videos", "description": "The videos a posting schedule has made, newest first. Read one with `GET /v1/videos/{id}` for its script, price, `video_url` and posts. Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "unsubmitted", "queued", "researching", "script_review", "rendering", "compositing", "ready", "failed" ] }, "template": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage", "video_edit" ] }, "error": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": ["id", "title", "status", "template", "error", "created_at"], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/videos": { "get": { "operationId": "v1_videos_get", "tags": ["Videos"], "summary": "List videos", "description": "The workspace's videos, newest first, including ones made in the dashboard or by a posting schedule. Filter by `status`; page with `meta.cursor`. Free.", "parameters": [ { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "`meta.cursor` from the previous page", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Only videos in this status", "type": "string", "enum": [ "unsubmitted", "queued", "researching", "script_review", "rendering", "compositing", "ready", "failed" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "unsubmitted", "queued", "researching", "script_review", "rendering", "compositing", "ready", "failed" ], "description": "`queued` → `researching` → `script_review` (waiting for approval) → `rendering` → `compositing` → `ready`, or `failed`. `unsubmitted` is a draft saved in the dashboard." }, "template": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage", "video_edit" ] }, "preset": { "type": ["string", "null"] }, "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "duration_seconds": { "type": ["number", "null"] }, "video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The finished MP4, once `ready`. A signed link that needs no API key, safe to hand to other services." }, "thumbnail_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "billed_cents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What the video was charged, once, when it was released to render. Null until then." }, "error": { "description": "Why it failed, or (in `script_review`) why an automatic approval was held back", "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "status": { "type": "string", "enum": [ "scheduled", "pending", "publishing", "published", "failed", "canceled", "deleted" ] }, "media_type": { "type": "string", "enum": ["video", "carousel", "image", "text"] }, "permalink": { "type": ["string", "null"] }, "scheduled_for": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "provider", "status", "media_type", "permalink", "scheduled_for", "published_at", "error" ], "additionalProperties": false } } }, "required": [ "id", "title", "status", "template", "preset", "format", "duration_seconds", "video_url", "thumbnail_url", "billed_cents", "error", "created_at", "updated_at", "posts" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_videos_post", "tags": ["Videos"], "summary": "Create a video", "description": "Make a video with every setting the dashboard's Configure step has: the template and style, format, length, sources, presenter, background, captions and more. Send `script` to have it spoken word for word (templates that read a script only): the video skips script review and is charged now. Without one, a script is written from your sources first, then approved automatically as soon as it is written (`script_review: auto`, the default) or left in `script_review` for `POST /v1/videos/{id}/approve` (`manual`). The video is charged once, when it is released to render, at the price `POST /v1/videos/quote` gives; set `max_price_cents` to cap it. Included video credits are used first, then the prepaid balance. Poll `GET /v1/videos/{id}` until `status` is `ready`, then download `video_url` or post it with `POST /v1/videos/{id}/posts`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "template": { "default": "talking_avatar", "description": "Which recipe makes the video: `talking_avatar` (a presenter over your site), `remotion` (motion graphics with a narrator), `site_demo` (an automated demo: an agent clicks through your website, screen-recorded, with a narrator), `freeform_ai` (one generated clip per scene), `meme_hook` (a viral clip into your presenter), `interview` (2 to 4 avatars in a split screen), `phone_mockup` (your video, site or photos on a phone in a hand), `slideshow` (captioned still slides) or `real_footage` (a real stock clip with a caption).", "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage" ] }, "preset": { "description": "A style of that template, e.g. `imessage` for `remotion`. Omit for the template's default.", "type": "string" }, "format": { "default": "vertical", "description": "`vertical` (9:16) or `horizontal` (16:9)", "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "default": 30, "description": "Roughly how long a written script runs. Ignored when you send `script`. Each template supports its own subset.", "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "title": { "description": "Your name for the video. Kept as its `title`; omit it and the title is written from the script.", "type": "string", "minLength": 1, "maxLength": 100 }, "brief": { "description": "What you want this video to be, in a sentence or two: the subject, the audience and the feel. The script is written to it. Ignored when you send `script`.", "type": "string", "minLength": 1, "maxLength": 1000 }, "source_url": { "description": "The website the video is about", "type": "string", "format": "uri" }, "source_text": { "description": "A description of the business, product or offer, in your words", "type": "string", "minLength": 1, "maxLength": 5000 }, "source_image_urls": { "description": "Images already uploaded to LumisReach, in the order the video shows them", "maxItems": 10, "type": "array", "items": { "type": "string", "format": "uri" } }, "source_video_urls": { "description": "Videos already uploaded to LumisReach, in order", "maxItems": 5, "type": "array", "items": { "type": "string", "format": "uri" } }, "source_image_kinds": { "description": "What each of `source_image_urls` is, in the same order: `screen` (a screenshot), `photo`, `logo` (your logo: shown by the end logo scene and nowhere else in the video) or `other` (a flyer, a chart, an illustration). `null`, or leaving the list out, has us read the image and decide.", "maxItems": 10, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": ["screen", "photo", "logo", "other"] }, { "type": "null" } ] } }, "source_video_kinds": { "description": "What each of `source_video_urls` is, in the same order: `talking` (someone talking to the camera), `broll` (footage to cut away to) or `screen` (a screen recording). `null`, or leaving the list out, has us read the video and decide.", "maxItems": 5, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": ["talking", "broll", "screen"] }, { "type": "null" } ] } }, "script": { "description": "Your own script, spoken word for word. Only for templates that read a script (`talking_avatar`, `meme_hook`, `phone_mockup`, `real_footage`). The video skips script review and is charged when it is created.", "type": "string", "minLength": 1, "maxLength": 60000 }, "avatar_provider": { "description": "Who renders the presenter. Left out with a `replica_id` or `avatar_id`, that presenter is a Tavus one. Left out with neither, it is `tavus` for an interview (cast from its stock faces) and `heygen` otherwise. HeyGen without `replica_id` or `avatar_id` uses one of its pre-made presenters, chosen to fit the source text where one does; Tavus without them uses the account's default presenter.", "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "default": "center", "description": "Where the presenter sits. `audio_only` is for an automated demo only.", "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right", "audio_only"] }, "avatar_id": { "description": "One of your saved avatars (required for ElevenLabs)", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "description": "A pre-made presenter: a Tavus face or a HeyGen look", "type": "string", "minLength": 1, "maxLength": 100 }, "heygen_engine": { "description": "HeyGen only. Omit for the most advanced engine the look supports.", "type": "string", "enum": ["avatar_iii", "avatar_iv", "avatar_v"] }, "voice_id": { "description": "An ElevenLabs avatar's voice, or the narrator of a narrated template: an ElevenLabs voice id, or a built-in speaker as `openai:` (e.g. `openai:ash`). A narrator left unset is the ElevenLabs default, spoken with `eleven_v4`", "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "description": "The ElevenLabs speech model an ElevenLabs narrator is spoken with: `eleven_v4` (the default), `eleven_v3`, `eleven_multilingual_v2` or `eleven_flash_v2_5`. Ignored for a built-in speaker.", "type": "string" }, "interview_cast": { "description": "`interview` only: who is in each window, in order. A null window is cast for you.", "maxItems": 4, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "replica_id": { "description": "A pre-made presenter id", "type": "string", "minLength": 1, "maxLength": 100 }, "avatar_id": { "description": "One of your own saved avatars", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false }, { "type": "null" } ] } }, "background_mode": { "default": "static", "description": "What the presenter stands in front of: `static` (a still of the site), `scrolling` (scrolls the site or several images), `footage` (your uploaded video), `automated_demo` (an agent clicks through your product), `original` (the presenter's own set) or `image` (a photo).", "type": "string", "enum": ["static", "scrolling", "footage", "automated_demo", "original", "image"] }, "background_image": { "description": "`image` background: a built-in photo's slug, or `upload:` for one of your images", "anyOf": [ { "type": "string", "enum": [ "modern-office", "classical-hall", "library", "city-skyline", "city-street", "mountains", "park", "beach", "cafe", "loft" ] }, { "type": "string", "pattern": "^upload:(\\d{1,2})$" } ] }, "b_roll": { "description": "`talking_avatar`: cut away to B-roll while the presenter talks (never while they talk about what is behind them). `remotion`: cut to B-roll scenes between the drawn ones; each comes on once the scene before it has finished, with the narration over it.", "type": "boolean" }, "b_roll_sources": { "description": "With `b_roll`: what it is made of; several is a mix, chosen per cutaway or scene. For `talking_avatar`: `stock` (filmed stock footage), `motion_graphics` (one animated scene of the point being made), `ai` (a 5 second clip generated for the topic, charged per clip) or `greenscreen` (one of your own screenshots or screen recordings from `source_image_urls` and `source_video_urls`, shown on a filmed phone or laptop, whichever fits its shape) or `image` (one of your own `source_image_urls` held full frame for a few seconds; see `b_roll_images`). Or `any`, alone: the planner picks per cutaway from all of those the video can use, and decides whether the video ends on an end card. For `remotion`: `automated_demo` (a recording of your product being clicked through; needs `source_url`, takes `demo_focus` and `demo_login`), `stock`, `ai`, `talking_avatar` (a presenter says that scene on camera in their original background; HeyGen or Tavus, chosen with `avatar_provider` and `replica_id` or `avatar_id`, charged per second) `uploaded` (shots cut from `source_video_urls`) or `image` (one of your own `source_image_urls` held full frame for the line about what it shows, blended in and out). Default `[\"stock\"]`.", "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "any", "stock", "motion_graphics", "ai", "greenscreen", "image", "automated_demo", "talking_avatar", "uploaded" ] } }, "b_roll_images": { "description": "With the `image` B-roll source: which of `source_image_urls` the cutaways may show, by index from 0. Each is shown at most once, on the words about what it shows. Omitted, the planner chooses among your photos.", "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "b_roll_opening": { "description": "With `b_roll`: let the video open on a cutaway instead of on the presenter. Default false.", "type": "boolean" }, "b_roll_end_scene": { "description": "`talking_avatar`, with or without `b_roll`: join an end card (a motion-graphics scene, for example a like and follow card, or where to book) to the end of the video, played after it has finished. It is always drawn, never footage. Drawn in `b_roll_motion_style`. Default false.", "type": "boolean" }, "b_roll_end_scene_text": { "description": "With `b_roll_end_scene`: the line the end card shows. Omitted, it is written for the video.", "type": "string", "maxLength": 70 }, "b_roll_end_scene_sound": { "description": "With `b_roll_end_scene`: the sound effect the scene comes on with. Omitted is none.", "type": "string", "enum": [ "sparkle", "pop", "whoosh", "ding", "chime", "success", "notification", "impact", "riser" ] }, "b_roll_end_scene_voice_id": { "description": "With `b_roll_end_scene`: the voice that says the end card's line out loud as it plays, an ElevenLabs voice id or a built-in speaker such as `openai:ash`. Omitted is no voiceover.", "type": "string", "minLength": 1, "maxLength": 200 }, "b_roll_motion_style": { "description": "With `motion_graphics` B-roll: the `remotion` style the cutaways are drawn in. Default `motion-graphics-1`.", "type": "string", "enum": [ "motion-graphics-1", "launch-video", "motion-graphics-2", "motion-graphics-3", "motion-graphics-4", "motion-graphics-5", "motion-graphics-6", "diorama", "clinic", "boutique", "notebook", "newsroom", "motion-graphics-7", "motion-graphics-8", "prism", "momentum" ] }, "subtitle_style": { "description": "Captions of what is said, burned in along the bottom of the frame. `dynamic` adds each word as it is said and clears after a pause or about six words; `dynamic_highlight` does the same with a black border on the text and only the newest word in colour; `emphasis` does the same with a black border on the text and the important words in colour; `enlarge` shows four or five words at a time the same way, with one important word of each set bold and larger; `one_word` shows only the word being said; `highlight` shows a few words at a time with the one being said in colour; `comic` is comic-book lettering, a few big yellow capitals at a time with a heavy outline. Default `none`. Ignored by `real_footage`, which has written captions instead; on `slideshow` it styles the slide captions (`classic`, `boxed` or `bold_words`).", "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "description": "Where the captions sit. On `real_footage` null is the top, on `slideshow` null keeps each slide's own place, and for spoken captions null is along the bottom.", "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_emojis": { "description": "Floats an emoji beside the spoken captions at the few moments that deserve one (a question, a shocking fact, the call to action), chosen from what is said. Needs a `subtitle_style` other than `none`. Default `false`.", "type": "boolean" }, "subtitle_size": { "description": "How big the captions are drawn, relative to the style's own size. Default `medium`.", "type": "string", "enum": ["small", "medium", "large"] }, "video_model": { "description": "`freeform_ai` only: `@`, e.g. `seedance-2.5@720p`. Omit for the default.", "type": "string" }, "slide_count": { "description": "`slideshow` only", "type": "integer", "minimum": 3, "maximum": 10 }, "slide_source": { "description": "`slideshow` only: where the pictures come from. Default `ai`.", "type": "string", "enum": ["uploaded", "website", "ai"] }, "image_model": { "description": "`slideshow` with AI pictures: the image model. Omit for the default.", "type": "string" }, "stock_footage": { "description": "`real_footage` only: the clip, by slug. It must be one filmed in the video's `format`.", "type": "string", "enum": [ "young-woman-braids-portrait", "stylish-senior-woman-hat", "man-coffee-fedora", "woman-curly-hair-turns", "taxi-driver-by-cab", "bald-man-smiling", "asian-woman-laughing", "nurse-in-corridor", "woman-hijab-smiling", "man-dimple-smile", "grandmother-on-sofa", "man-coat-field", "older-man-plants", "young-man-glasses-curls", "construction-worker-hard-hat", "shop-owner-packing-box", "barista-iced-coffee", "man-making-pancakes", "senior-woman-reading", "man-driving-car", "florist-arranging-bouquet", "woman-cooking-spices", "woman-laptop-phone-breakfast", "woman-morning-coffee", "older-man-tea", "grandma-baking-with-granddaughter", "man-typing-laptop", "barista-pouring-milk", "builder-hammering-wall", "woman-treadmill-gym", "older-man-white-beard", "man-glasses-sunset", "woman-hugging-herself", "woman-walks-up-courtyard", "woman-laughing-brick-wall", "woman-laughing-forest", "man-grinning-forest", "bald-man-glare", "man-chin-thinking", "man-gasps-disbelief", "woman-glasses-ties-hair", "barista-pour-over", "market-vendor-tray", "builder-shovelling-sand", "painter-rolling-wall", "support-agent-headset", "man-phone-call-laptop", "older-man-laptop-park", "woman-tablet-cafe", "woman-phone-smiling", "office-worker-late", "pharmacist-typing", "woman-blow-drying-hair", "cook-lifts-pot-lid", "woman-sipping-mug" ] }, "on_screen_caption": { "description": "`real_footage` only: the caption over the clip, or up to 3 captions shown one after another, separated by a blank line (each at most 150 characters). Omit to have one written.", "type": "string", "maxLength": 454 }, "footage_narrated": { "description": "`real_footage` only: whether a narrator reads the script. Default true.", "type": "boolean" }, "meme_clip_id": { "description": "`meme_hook`: a clip from your library...", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "stock_meme_clip": { "description": "...or a built-in clip, by slug", "type": "string", "enum": [ "dramatic-chipmunk", "sneezing-panda", "keyboard-cat", "vibing-cat", "screaming-goat", "coffin-dance", "epic-sax-guy", "rick-roll", "office-rage", "surprised-kitty" ] }, "phone_screen": { "description": "`phone_mockup` only: what plays on the device's screen. Omit to pick video, then website, then photos.", "type": "string", "enum": ["video", "website", "photos"] }, "device_clip": { "description": "`phone_mockup` only: the device clip (a phone, tablet, laptop or monitor with a green screen), by slug. It must be one filmed in the video's `format`. Omit to have one picked that suits what is on screen.", "type": "string", "enum": [ "hand-phone", "phone-shop-floor", "phone-scrolling", "phone-in-car", "phone-sideways-sofa", "phone-cafe", "tablet-wood-desk", "tablet-marble-desk", "tablet-coffee-break", "tablet-flat-lay", "laptop-typing", "laptop-alarm-clock", "laptop-sideboard", "monitor-home-office", "phone-sideways-backdrop", "phone-backdrop" ] }, "device_background": { "description": "`phone_mockup` with a `device_clip` filmed against a green backdrop (a `-backdrop` slug): the built-in photo behind the device. Omit for the default.", "type": "string", "enum": [ "modern-office", "classical-hall", "library", "city-skyline", "city-street", "mountains", "park", "beach", "cafe", "loft" ] }, "demo_focus": { "description": "Site demos: the features to show, in your words", "type": "string", "maxLength": 1000 }, "demo_login": { "description": "Site demos: sign in first to show the product behind the login", "type": "object", "properties": { "login_url": { "description": "The sign-in page, if not the site's own", "type": "string", "maxLength": 2000, "format": "uri" }, "email": { "type": "string", "minLength": 1, "maxLength": 320 }, "password": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Stored encrypted; never returned" } }, "required": ["email", "password"], "additionalProperties": false }, "script_review": { "default": "auto", "description": "Without your own `script`, one is written first. `auto` approves it (and charges the video) as soon as it is written; `manual` stops in `script_review` until you call `POST /v1/videos/{id}/approve`. Ignored when you send `script`: your script needs no review.", "type": "string", "enum": ["auto", "manual"] }, "max_price_cents": { "description": "A spending cap. With your own `script` the price is known now, and a video above the cap is rejected with 400 before anything is created. Otherwise the written script is priced when it is approved automatically; above the cap it is not approved and waits in `script_review` with the reason in `error`. With `script_review: manual`, pass the cap to the approve call instead.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caption": { "description": "The post caption. Omit to use the one written with the script.", "type": "string", "maxLength": 4000 }, "hashtags": { "description": "Hashtags for the post, with or without `#`", "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 101 } }, "music": { "description": "Background music mixed under the finished video. A `talking_avatar` video sent without it gets a random royalty-free track at volume 30.", "type": "object", "properties": { "library": { "default": "lumisreach", "description": "`lumisreach`: a track from the built-in royalty-free library, by slug. `epidemic`: an Epidemic Sound track id.", "type": "string", "enum": ["lumisreach", "epidemic"] }, "track_id": { "type": "string", "minLength": 1, "maxLength": 100 }, "volume": { "default": 30, "description": "0 to 100, ducked under speech", "type": "integer", "minimum": 0, "maximum": 100 } }, "required": ["library", "track_id", "volume"], "additionalProperties": false } }, "required": [ "template", "format", "target_duration_seconds", "avatar_layout", "background_mode", "script_review" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "unsubmitted", "queued", "researching", "script_review", "rendering", "compositing", "ready", "failed" ], "description": "`queued` → `researching` → `script_review` (waiting for approval) → `rendering` → `compositing` → `ready`, or `failed`. `unsubmitted` is a draft saved in the dashboard." }, "template": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage", "video_edit" ] }, "preset": { "type": ["string", "null"] }, "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "duration_seconds": { "type": ["number", "null"] }, "video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The finished MP4, once `ready`. A signed link that needs no API key, safe to hand to other services." }, "thumbnail_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "billed_cents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What the video was charged, once, when it was released to render. Null until then." }, "error": { "description": "Why it failed, or (in `script_review`) why an automatic approval was held back", "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "status": { "type": "string", "enum": [ "scheduled", "pending", "publishing", "published", "failed", "canceled", "deleted" ] }, "media_type": { "type": "string", "enum": ["video", "carousel", "image", "text"] }, "permalink": { "type": ["string", "null"] }, "scheduled_for": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "provider", "status", "media_type", "permalink", "scheduled_for", "published_at", "error" ], "additionalProperties": false } }, "price_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the video costs: the amount charged once released, otherwise the quote for the script (or, before it is written, the estimate)." }, "price_estimated": { "type": "boolean", "description": "True while the price is an estimate from the length asked for" }, "script_approved": { "type": "boolean" }, "user_script": { "type": "boolean", "description": "True when you supplied the script" }, "script": { "description": "The spoken words, once written", "type": ["string", "null"] }, "script_sections": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "text": { "type": "string" } }, "required": ["label", "text"], "additionalProperties": false } }, { "type": "null" } ], "description": "A scrolling background's script, one part per section" }, "scenes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "duration_seconds": { "type": "number" }, "voiceover": { "type": "string" }, "caption": { "type": ["string", "null"] }, "prompt": { "type": ["string", "null"] } }, "required": [ "id", "label", "duration_seconds", "voiceover", "caption", "prompt" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A scene template's shot list, once planned" }, "slides": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "headline": { "type": "string" }, "body": { "type": ["string", "null"] }, "position": { "type": "string" }, "prompt": { "type": ["string", "null"] }, "image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "role", "headline", "body", "position", "prompt", "image_url" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A slideshow's slides, once planned; `image_url` once rendered" }, "interview": { "anyOf": [ { "type": "object", "properties": { "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "face_name": { "type": "string" } }, "required": ["id", "role", "face_name"], "additionalProperties": false } }, "turns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "speaker_id": { "type": "string" }, "text": { "type": "string" } }, "required": ["id", "speaker_id", "text"], "additionalProperties": false } } }, "required": ["speakers", "turns"], "additionalProperties": false }, { "type": "null" } ] }, "caption": { "type": ["string", "null"] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "post_caption": { "description": "The caption with its hashtags, as it is posted by default", "type": ["string", "null"] }, "music": { "anyOf": [ { "type": "object", "properties": { "library": { "type": "string", "enum": ["lumisreach", "epidemic", "generated"], "description": "`generated`: a track an AI model made for your organization in the dashboard" }, "track_id": { "type": "string" }, "title": { "type": "string" }, "volume": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["pending", "mixing", "applied", "failed"] } }, "required": ["library", "track_id", "title", "volume", "status"], "additionalProperties": false }, { "type": "null" } ] }, "brief": { "description": "What the video was asked to be, when a `brief` was given", "type": ["string", "null"] }, "source_url": { "type": ["string", "null"] }, "target_duration_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right", "audio_only"] }, "background_mode": { "type": "string", "enum": ["static", "scrolling", "footage", "automated_demo", "original", "image"] }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_emojis": { "type": "boolean" }, "video_model": { "type": ["string", "null"] }, "dashboard_url": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "status", "template", "preset", "format", "duration_seconds", "video_url", "thumbnail_url", "billed_cents", "error", "created_at", "updated_at", "posts", "price_cents", "price_estimated", "script_approved", "user_script", "script", "script_sections", "scenes", "slides", "interview", "caption", "hashtags", "post_caption", "music", "brief", "source_url", "target_duration_seconds", "avatar_provider", "avatar_layout", "background_mode", "subtitle_style", "subtitle_emojis", "video_model", "dashboard_url" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/videos/music": { "get": { "operationId": "v1_videos_music_get", "tags": ["Videos"], "summary": "List music tracks", "description": "The built-in library of royalty-free background tracks (hip-hop beats, lo-fi, chill, dance, feel-good, quirky, hype), cleared for every platform we post to. Pass a `track_id` as `music: { library: \"lumisreach\", track_id }` when creating a video. Free.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "track_id": { "type": "string", "description": "Pass as `music.track_id` with `library: lumisreach`" }, "title": { "type": "string" }, "artist": { "type": "string" }, "category": { "type": "string", "description": "e.g. \"Lo-fi\", \"Hype\"" }, "length_seconds": { "type": ["number", "null"] } }, "required": ["track_id", "title", "artist", "category", "length_seconds"], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/videos/quote": { "post": { "operationId": "v1_videos_quote_post", "tags": ["Videos"], "summary": "Quote a video", "description": "The price of a video with these settings (the same body as `POST /v1/videos`), without making it. Videos are priced at the cost of the providers that make them (presenter renders, generated shots and pictures, narration, rendering) plus a small markup, and charged once, when released to render; retries are free. With your own `script` the quote is exact. Without one it is an estimate from `target_duration_seconds` (`estimated: true`), and the charge at approval is for what was actually written. Free.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "template": { "default": "talking_avatar", "description": "Which recipe makes the video: `talking_avatar` (a presenter over your site), `remotion` (motion graphics with a narrator), `site_demo` (an automated demo: an agent clicks through your website, screen-recorded, with a narrator), `freeform_ai` (one generated clip per scene), `meme_hook` (a viral clip into your presenter), `interview` (2 to 4 avatars in a split screen), `phone_mockup` (your video, site or photos on a phone in a hand), `slideshow` (captioned still slides) or `real_footage` (a real stock clip with a caption).", "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage" ] }, "preset": { "description": "A style of that template, e.g. `imessage` for `remotion`. Omit for the template's default.", "type": "string" }, "format": { "default": "vertical", "description": "`vertical` (9:16) or `horizontal` (16:9)", "type": "string", "enum": ["vertical", "horizontal"] }, "target_duration_seconds": { "default": 30, "description": "Roughly how long a written script runs. Ignored when you send `script`. Each template supports its own subset.", "type": "number", "enum": [10, 15, 20, 30, 45, 60, 120, 180, 300] }, "title": { "description": "Your name for the video. Kept as its `title`; omit it and the title is written from the script.", "type": "string", "minLength": 1, "maxLength": 100 }, "brief": { "description": "What you want this video to be, in a sentence or two: the subject, the audience and the feel. The script is written to it. Ignored when you send `script`.", "type": "string", "minLength": 1, "maxLength": 1000 }, "source_url": { "description": "The website the video is about", "type": "string", "format": "uri" }, "source_text": { "description": "A description of the business, product or offer, in your words", "type": "string", "minLength": 1, "maxLength": 5000 }, "source_image_urls": { "description": "Images already uploaded to LumisReach, in the order the video shows them", "maxItems": 10, "type": "array", "items": { "type": "string", "format": "uri" } }, "source_video_urls": { "description": "Videos already uploaded to LumisReach, in order", "maxItems": 5, "type": "array", "items": { "type": "string", "format": "uri" } }, "source_image_kinds": { "description": "What each of `source_image_urls` is, in the same order: `screen` (a screenshot), `photo`, `logo` (your logo: shown by the end logo scene and nowhere else in the video) or `other` (a flyer, a chart, an illustration). `null`, or leaving the list out, has us read the image and decide.", "maxItems": 10, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": ["screen", "photo", "logo", "other"] }, { "type": "null" } ] } }, "source_video_kinds": { "description": "What each of `source_video_urls` is, in the same order: `talking` (someone talking to the camera), `broll` (footage to cut away to) or `screen` (a screen recording). `null`, or leaving the list out, has us read the video and decide.", "maxItems": 5, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": ["talking", "broll", "screen"] }, { "type": "null" } ] } }, "script": { "description": "Your own script, spoken word for word. Only for templates that read a script (`talking_avatar`, `meme_hook`, `phone_mockup`, `real_footage`). The video skips script review and is charged when it is created.", "type": "string", "minLength": 1, "maxLength": 60000 }, "avatar_provider": { "description": "Who renders the presenter. Left out with a `replica_id` or `avatar_id`, that presenter is a Tavus one. Left out with neither, it is `tavus` for an interview (cast from its stock faces) and `heygen` otherwise. HeyGen without `replica_id` or `avatar_id` uses one of its pre-made presenters, chosen to fit the source text where one does; Tavus without them uses the account's default presenter.", "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "default": "center", "description": "Where the presenter sits. `audio_only` is for an automated demo only.", "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right", "audio_only"] }, "avatar_id": { "description": "One of your saved avatars (required for ElevenLabs)", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replica_id": { "description": "A pre-made presenter: a Tavus face or a HeyGen look", "type": "string", "minLength": 1, "maxLength": 100 }, "heygen_engine": { "description": "HeyGen only. Omit for the most advanced engine the look supports.", "type": "string", "enum": ["avatar_iii", "avatar_iv", "avatar_v"] }, "voice_id": { "description": "An ElevenLabs avatar's voice, or the narrator of a narrated template: an ElevenLabs voice id, or a built-in speaker as `openai:` (e.g. `openai:ash`). A narrator left unset is the ElevenLabs default, spoken with `eleven_v4`", "type": "string", "minLength": 1, "maxLength": 100 }, "voice_model": { "description": "The ElevenLabs speech model an ElevenLabs narrator is spoken with: `eleven_v4` (the default), `eleven_v3`, `eleven_multilingual_v2` or `eleven_flash_v2_5`. Ignored for a built-in speaker.", "type": "string" }, "interview_cast": { "description": "`interview` only: who is in each window, in order. A null window is cast for you.", "maxItems": 4, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "replica_id": { "description": "A pre-made presenter id", "type": "string", "minLength": 1, "maxLength": 100 }, "avatar_id": { "description": "One of your own saved avatars", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false }, { "type": "null" } ] } }, "background_mode": { "default": "static", "description": "What the presenter stands in front of: `static` (a still of the site), `scrolling` (scrolls the site or several images), `footage` (your uploaded video), `automated_demo` (an agent clicks through your product), `original` (the presenter's own set) or `image` (a photo).", "type": "string", "enum": ["static", "scrolling", "footage", "automated_demo", "original", "image"] }, "background_image": { "description": "`image` background: a built-in photo's slug, or `upload:` for one of your images", "anyOf": [ { "type": "string", "enum": [ "modern-office", "classical-hall", "library", "city-skyline", "city-street", "mountains", "park", "beach", "cafe", "loft" ] }, { "type": "string", "pattern": "^upload:(\\d{1,2})$" } ] }, "b_roll": { "description": "`talking_avatar`: cut away to B-roll while the presenter talks (never while they talk about what is behind them). `remotion`: cut to B-roll scenes between the drawn ones; each comes on once the scene before it has finished, with the narration over it.", "type": "boolean" }, "b_roll_sources": { "description": "With `b_roll`: what it is made of; several is a mix, chosen per cutaway or scene. For `talking_avatar`: `stock` (filmed stock footage), `motion_graphics` (one animated scene of the point being made), `ai` (a 5 second clip generated for the topic, charged per clip) or `greenscreen` (one of your own screenshots or screen recordings from `source_image_urls` and `source_video_urls`, shown on a filmed phone or laptop, whichever fits its shape) or `image` (one of your own `source_image_urls` held full frame for a few seconds; see `b_roll_images`). Or `any`, alone: the planner picks per cutaway from all of those the video can use, and decides whether the video ends on an end card. For `remotion`: `automated_demo` (a recording of your product being clicked through; needs `source_url`, takes `demo_focus` and `demo_login`), `stock`, `ai`, `talking_avatar` (a presenter says that scene on camera in their original background; HeyGen or Tavus, chosen with `avatar_provider` and `replica_id` or `avatar_id`, charged per second) `uploaded` (shots cut from `source_video_urls`) or `image` (one of your own `source_image_urls` held full frame for the line about what it shows, blended in and out). Default `[\"stock\"]`.", "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "any", "stock", "motion_graphics", "ai", "greenscreen", "image", "automated_demo", "talking_avatar", "uploaded" ] } }, "b_roll_images": { "description": "With the `image` B-roll source: which of `source_image_urls` the cutaways may show, by index from 0. Each is shown at most once, on the words about what it shows. Omitted, the planner chooses among your photos.", "maxItems": 8, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "b_roll_opening": { "description": "With `b_roll`: let the video open on a cutaway instead of on the presenter. Default false.", "type": "boolean" }, "b_roll_end_scene": { "description": "`talking_avatar`, with or without `b_roll`: join an end card (a motion-graphics scene, for example a like and follow card, or where to book) to the end of the video, played after it has finished. It is always drawn, never footage. Drawn in `b_roll_motion_style`. Default false.", "type": "boolean" }, "b_roll_end_scene_text": { "description": "With `b_roll_end_scene`: the line the end card shows. Omitted, it is written for the video.", "type": "string", "maxLength": 70 }, "b_roll_end_scene_sound": { "description": "With `b_roll_end_scene`: the sound effect the scene comes on with. Omitted is none.", "type": "string", "enum": [ "sparkle", "pop", "whoosh", "ding", "chime", "success", "notification", "impact", "riser" ] }, "b_roll_end_scene_voice_id": { "description": "With `b_roll_end_scene`: the voice that says the end card's line out loud as it plays, an ElevenLabs voice id or a built-in speaker such as `openai:ash`. Omitted is no voiceover.", "type": "string", "minLength": 1, "maxLength": 200 }, "b_roll_motion_style": { "description": "With `motion_graphics` B-roll: the `remotion` style the cutaways are drawn in. Default `motion-graphics-1`.", "type": "string", "enum": [ "motion-graphics-1", "launch-video", "motion-graphics-2", "motion-graphics-3", "motion-graphics-4", "motion-graphics-5", "motion-graphics-6", "diorama", "clinic", "boutique", "notebook", "newsroom", "motion-graphics-7", "motion-graphics-8", "prism", "momentum" ] }, "subtitle_style": { "description": "Captions of what is said, burned in along the bottom of the frame. `dynamic` adds each word as it is said and clears after a pause or about six words; `dynamic_highlight` does the same with a black border on the text and only the newest word in colour; `emphasis` does the same with a black border on the text and the important words in colour; `enlarge` shows four or five words at a time the same way, with one important word of each set bold and larger; `one_word` shows only the word being said; `highlight` shows a few words at a time with the one being said in colour; `comic` is comic-book lettering, a few big yellow capitals at a time with a heavy outline. Default `none`. Ignored by `real_footage`, which has written captions instead; on `slideshow` it styles the slide captions (`classic`, `boxed` or `bold_words`).", "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_position": { "description": "Where the captions sit. On `real_footage` null is the top, on `slideshow` null keeps each slide's own place, and for spoken captions null is along the bottom.", "anyOf": [ { "type": "string", "enum": ["top", "middle", "bottom"] }, { "type": "null" } ] }, "subtitle_emojis": { "description": "Floats an emoji beside the spoken captions at the few moments that deserve one (a question, a shocking fact, the call to action), chosen from what is said. Needs a `subtitle_style` other than `none`. Default `false`.", "type": "boolean" }, "subtitle_size": { "description": "How big the captions are drawn, relative to the style's own size. Default `medium`.", "type": "string", "enum": ["small", "medium", "large"] }, "video_model": { "description": "`freeform_ai` only: `@`, e.g. `seedance-2.5@720p`. Omit for the default.", "type": "string" }, "slide_count": { "description": "`slideshow` only", "type": "integer", "minimum": 3, "maximum": 10 }, "slide_source": { "description": "`slideshow` only: where the pictures come from. Default `ai`.", "type": "string", "enum": ["uploaded", "website", "ai"] }, "image_model": { "description": "`slideshow` with AI pictures: the image model. Omit for the default.", "type": "string" }, "stock_footage": { "description": "`real_footage` only: the clip, by slug. It must be one filmed in the video's `format`.", "type": "string", "enum": [ "young-woman-braids-portrait", "stylish-senior-woman-hat", "man-coffee-fedora", "woman-curly-hair-turns", "taxi-driver-by-cab", "bald-man-smiling", "asian-woman-laughing", "nurse-in-corridor", "woman-hijab-smiling", "man-dimple-smile", "grandmother-on-sofa", "man-coat-field", "older-man-plants", "young-man-glasses-curls", "construction-worker-hard-hat", "shop-owner-packing-box", "barista-iced-coffee", "man-making-pancakes", "senior-woman-reading", "man-driving-car", "florist-arranging-bouquet", "woman-cooking-spices", "woman-laptop-phone-breakfast", "woman-morning-coffee", "older-man-tea", "grandma-baking-with-granddaughter", "man-typing-laptop", "barista-pouring-milk", "builder-hammering-wall", "woman-treadmill-gym", "older-man-white-beard", "man-glasses-sunset", "woman-hugging-herself", "woman-walks-up-courtyard", "woman-laughing-brick-wall", "woman-laughing-forest", "man-grinning-forest", "bald-man-glare", "man-chin-thinking", "man-gasps-disbelief", "woman-glasses-ties-hair", "barista-pour-over", "market-vendor-tray", "builder-shovelling-sand", "painter-rolling-wall", "support-agent-headset", "man-phone-call-laptop", "older-man-laptop-park", "woman-tablet-cafe", "woman-phone-smiling", "office-worker-late", "pharmacist-typing", "woman-blow-drying-hair", "cook-lifts-pot-lid", "woman-sipping-mug" ] }, "on_screen_caption": { "description": "`real_footage` only: the caption over the clip, or up to 3 captions shown one after another, separated by a blank line (each at most 150 characters). Omit to have one written.", "type": "string", "maxLength": 454 }, "footage_narrated": { "description": "`real_footage` only: whether a narrator reads the script. Default true.", "type": "boolean" }, "meme_clip_id": { "description": "`meme_hook`: a clip from your library...", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "stock_meme_clip": { "description": "...or a built-in clip, by slug", "type": "string", "enum": [ "dramatic-chipmunk", "sneezing-panda", "keyboard-cat", "vibing-cat", "screaming-goat", "coffin-dance", "epic-sax-guy", "rick-roll", "office-rage", "surprised-kitty" ] }, "phone_screen": { "description": "`phone_mockup` only: what plays on the device's screen. Omit to pick video, then website, then photos.", "type": "string", "enum": ["video", "website", "photos"] }, "device_clip": { "description": "`phone_mockup` only: the device clip (a phone, tablet, laptop or monitor with a green screen), by slug. It must be one filmed in the video's `format`. Omit to have one picked that suits what is on screen.", "type": "string", "enum": [ "hand-phone", "phone-shop-floor", "phone-scrolling", "phone-in-car", "phone-sideways-sofa", "phone-cafe", "tablet-wood-desk", "tablet-marble-desk", "tablet-coffee-break", "tablet-flat-lay", "laptop-typing", "laptop-alarm-clock", "laptop-sideboard", "monitor-home-office", "phone-sideways-backdrop", "phone-backdrop" ] }, "device_background": { "description": "`phone_mockup` with a `device_clip` filmed against a green backdrop (a `-backdrop` slug): the built-in photo behind the device. Omit for the default.", "type": "string", "enum": [ "modern-office", "classical-hall", "library", "city-skyline", "city-street", "mountains", "park", "beach", "cafe", "loft" ] }, "demo_focus": { "description": "Site demos: the features to show, in your words", "type": "string", "maxLength": 1000 }, "demo_login": { "description": "Site demos: sign in first to show the product behind the login", "type": "object", "properties": { "login_url": { "description": "The sign-in page, if not the site's own", "type": "string", "maxLength": 2000, "format": "uri" }, "email": { "type": "string", "minLength": 1, "maxLength": 320 }, "password": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Stored encrypted; never returned" } }, "required": ["email", "password"], "additionalProperties": false } }, "required": [ "template", "format", "target_duration_seconds", "avatar_layout", "background_mode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "price_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the video will be charged, in cents" }, "price_usd": { "type": "string", "description": "The same, formatted, e.g. \"$1.23\"" }, "estimated": { "type": "boolean", "description": "True when the words or shots are not known yet (no `script`): the price assumes `target_duration_seconds`, and the charge at approval is for what was actually written." }, "seconds": { "type": "number", "description": "How long the quote assumes the video runs" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["label", "cents"], "additionalProperties": false }, "description": "What the price is made of. They add up to `price_cents`." } }, "required": ["price_cents", "price_usd", "estimated", "seconds", "line_items"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/videos/{id}": { "get": { "operationId": "v1_videos_id_get", "tags": ["Videos"], "summary": "Get a video", "description": "Where a video stands: `status`, the script (or shot list, slides or interview) once written, what it costs (`price_cents`) and was charged (`billed_cents`), any `error`, its posts, and once `ready`, `video_url` and `thumbnail_url`. Those are signed links that work without an API key, so you can download the MP4 or hand the link to another service. Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "unsubmitted", "queued", "researching", "script_review", "rendering", "compositing", "ready", "failed" ], "description": "`queued` → `researching` → `script_review` (waiting for approval) → `rendering` → `compositing` → `ready`, or `failed`. `unsubmitted` is a draft saved in the dashboard." }, "template": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage", "video_edit" ] }, "preset": { "type": ["string", "null"] }, "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "duration_seconds": { "type": ["number", "null"] }, "video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The finished MP4, once `ready`. A signed link that needs no API key, safe to hand to other services." }, "thumbnail_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "billed_cents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What the video was charged, once, when it was released to render. Null until then." }, "error": { "description": "Why it failed, or (in `script_review`) why an automatic approval was held back", "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "status": { "type": "string", "enum": [ "scheduled", "pending", "publishing", "published", "failed", "canceled", "deleted" ] }, "media_type": { "type": "string", "enum": ["video", "carousel", "image", "text"] }, "permalink": { "type": ["string", "null"] }, "scheduled_for": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "provider", "status", "media_type", "permalink", "scheduled_for", "published_at", "error" ], "additionalProperties": false } }, "price_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the video costs: the amount charged once released, otherwise the quote for the script (or, before it is written, the estimate)." }, "price_estimated": { "type": "boolean", "description": "True while the price is an estimate from the length asked for" }, "script_approved": { "type": "boolean" }, "user_script": { "type": "boolean", "description": "True when you supplied the script" }, "script": { "description": "The spoken words, once written", "type": ["string", "null"] }, "script_sections": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "text": { "type": "string" } }, "required": ["label", "text"], "additionalProperties": false } }, { "type": "null" } ], "description": "A scrolling background's script, one part per section" }, "scenes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "duration_seconds": { "type": "number" }, "voiceover": { "type": "string" }, "caption": { "type": ["string", "null"] }, "prompt": { "type": ["string", "null"] } }, "required": [ "id", "label", "duration_seconds", "voiceover", "caption", "prompt" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A scene template's shot list, once planned" }, "slides": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "headline": { "type": "string" }, "body": { "type": ["string", "null"] }, "position": { "type": "string" }, "prompt": { "type": ["string", "null"] }, "image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "role", "headline", "body", "position", "prompt", "image_url" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A slideshow's slides, once planned; `image_url` once rendered" }, "interview": { "anyOf": [ { "type": "object", "properties": { "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "face_name": { "type": "string" } }, "required": ["id", "role", "face_name"], "additionalProperties": false } }, "turns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "speaker_id": { "type": "string" }, "text": { "type": "string" } }, "required": ["id", "speaker_id", "text"], "additionalProperties": false } } }, "required": ["speakers", "turns"], "additionalProperties": false }, { "type": "null" } ] }, "caption": { "type": ["string", "null"] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "post_caption": { "description": "The caption with its hashtags, as it is posted by default", "type": ["string", "null"] }, "music": { "anyOf": [ { "type": "object", "properties": { "library": { "type": "string", "enum": ["lumisreach", "epidemic", "generated"], "description": "`generated`: a track an AI model made for your organization in the dashboard" }, "track_id": { "type": "string" }, "title": { "type": "string" }, "volume": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["pending", "mixing", "applied", "failed"] } }, "required": ["library", "track_id", "title", "volume", "status"], "additionalProperties": false }, { "type": "null" } ] }, "brief": { "description": "What the video was asked to be, when a `brief` was given", "type": ["string", "null"] }, "source_url": { "type": ["string", "null"] }, "target_duration_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right", "audio_only"] }, "background_mode": { "type": "string", "enum": ["static", "scrolling", "footage", "automated_demo", "original", "image"] }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_emojis": { "type": "boolean" }, "video_model": { "type": ["string", "null"] }, "dashboard_url": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "status", "template", "preset", "format", "duration_seconds", "video_url", "thumbnail_url", "billed_cents", "error", "created_at", "updated_at", "posts", "price_cents", "price_estimated", "script_approved", "user_script", "script", "script_sections", "scenes", "slides", "interview", "caption", "hashtags", "post_caption", "music", "brief", "source_url", "target_duration_seconds", "avatar_provider", "avatar_layout", "background_mode", "subtitle_style", "subtitle_emojis", "video_model", "dashboard_url" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "delete": { "operationId": "v1_videos_id_delete", "tags": ["Videos"], "summary": "Delete a video", "description": "Delete a video and its files. Posts already published stay on the platforms. A video that was charged is not refunded.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "deleted": { "type": "boolean", "const": true } }, "required": ["id", "deleted"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/videos/{id}/approve": { "post": { "operationId": "v1_videos_id_approve_post", "tags": ["Videos"], "summary": "Approve a video's script", "description": "Approve the script of a video in `script_review`, with any edits, and release it to render. Send `{}` to approve it as written. Approving is what charges the video, at the price of the approved script: the video's `price_cents` when approved as written. Set `max_price_cents` to refuse the approval, with 400, if your edits would take it above that. A workspace that cannot pay for it (included video credits, then the prepaid balance) gets 400 and the video stays in review.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "script": { "description": "The edited script, for a script-based video. Omit to approve it as written.", "type": "string", "maxLength": 6000 }, "sections": { "description": "A scrolling background: one text per section, in order", "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 1500 } }, "on_screen_caption": { "description": "`real_footage`: the caption over the clip, or several separated by a blank line", "type": "string", "minLength": 1, "maxLength": 454 }, "scenes": { "description": "Scene templates: edits by scene id. Scenes you leave out keep what was planned.", "minItems": 1, "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "voiceover": { "type": "string", "maxLength": 1500 }, "caption": { "anyOf": [ { "type": "string", "maxLength": 90 }, { "type": "null" } ] }, "prompt": { "type": "string", "maxLength": 1200 }, "duration_seconds": { "type": "number", "minimum": 2, "maximum": 12 } }, "required": ["id"], "additionalProperties": false } }, "slides": { "description": "`slideshow`: edits by slide id", "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 32 }, "headline": { "type": "string", "maxLength": 90 }, "body": { "anyOf": [ { "type": "string", "maxLength": 180 }, { "type": "null" } ] }, "position": { "type": "string", "enum": ["top", "center", "bottom"] }, "prompt": { "type": "string", "maxLength": 800 } }, "required": ["id"], "additionalProperties": false } }, "interview_turns": { "description": "`interview`: line edits by turn id", "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 16 }, "text": { "type": "string", "maxLength": 400 } }, "required": ["id", "text"], "additionalProperties": false } }, "max_price_cents": { "description": "A spending cap: above it the script is not approved and the request fails with 400", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "unsubmitted", "queued", "researching", "script_review", "rendering", "compositing", "ready", "failed" ], "description": "`queued` → `researching` → `script_review` (waiting for approval) → `rendering` → `compositing` → `ready`, or `failed`. `unsubmitted` is a draft saved in the dashboard." }, "template": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage", "video_edit" ] }, "preset": { "type": ["string", "null"] }, "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "duration_seconds": { "type": ["number", "null"] }, "video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The finished MP4, once `ready`. A signed link that needs no API key, safe to hand to other services." }, "thumbnail_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "billed_cents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What the video was charged, once, when it was released to render. Null until then." }, "error": { "description": "Why it failed, or (in `script_review`) why an automatic approval was held back", "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "status": { "type": "string", "enum": [ "scheduled", "pending", "publishing", "published", "failed", "canceled", "deleted" ] }, "media_type": { "type": "string", "enum": ["video", "carousel", "image", "text"] }, "permalink": { "type": ["string", "null"] }, "scheduled_for": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "provider", "status", "media_type", "permalink", "scheduled_for", "published_at", "error" ], "additionalProperties": false } }, "price_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the video costs: the amount charged once released, otherwise the quote for the script (or, before it is written, the estimate)." }, "price_estimated": { "type": "boolean", "description": "True while the price is an estimate from the length asked for" }, "script_approved": { "type": "boolean" }, "user_script": { "type": "boolean", "description": "True when you supplied the script" }, "script": { "description": "The spoken words, once written", "type": ["string", "null"] }, "script_sections": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "text": { "type": "string" } }, "required": ["label", "text"], "additionalProperties": false } }, { "type": "null" } ], "description": "A scrolling background's script, one part per section" }, "scenes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "duration_seconds": { "type": "number" }, "voiceover": { "type": "string" }, "caption": { "type": ["string", "null"] }, "prompt": { "type": ["string", "null"] } }, "required": [ "id", "label", "duration_seconds", "voiceover", "caption", "prompt" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A scene template's shot list, once planned" }, "slides": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "headline": { "type": "string" }, "body": { "type": ["string", "null"] }, "position": { "type": "string" }, "prompt": { "type": ["string", "null"] }, "image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "role", "headline", "body", "position", "prompt", "image_url" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A slideshow's slides, once planned; `image_url` once rendered" }, "interview": { "anyOf": [ { "type": "object", "properties": { "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "face_name": { "type": "string" } }, "required": ["id", "role", "face_name"], "additionalProperties": false } }, "turns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "speaker_id": { "type": "string" }, "text": { "type": "string" } }, "required": ["id", "speaker_id", "text"], "additionalProperties": false } } }, "required": ["speakers", "turns"], "additionalProperties": false }, { "type": "null" } ] }, "caption": { "type": ["string", "null"] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "post_caption": { "description": "The caption with its hashtags, as it is posted by default", "type": ["string", "null"] }, "music": { "anyOf": [ { "type": "object", "properties": { "library": { "type": "string", "enum": ["lumisreach", "epidemic", "generated"], "description": "`generated`: a track an AI model made for your organization in the dashboard" }, "track_id": { "type": "string" }, "title": { "type": "string" }, "volume": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["pending", "mixing", "applied", "failed"] } }, "required": ["library", "track_id", "title", "volume", "status"], "additionalProperties": false }, { "type": "null" } ] }, "brief": { "description": "What the video was asked to be, when a `brief` was given", "type": ["string", "null"] }, "source_url": { "type": ["string", "null"] }, "target_duration_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right", "audio_only"] }, "background_mode": { "type": "string", "enum": ["static", "scrolling", "footage", "automated_demo", "original", "image"] }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_emojis": { "type": "boolean" }, "video_model": { "type": ["string", "null"] }, "dashboard_url": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "status", "template", "preset", "format", "duration_seconds", "video_url", "thumbnail_url", "billed_cents", "error", "created_at", "updated_at", "posts", "price_cents", "price_estimated", "script_approved", "user_script", "script", "script_sections", "scenes", "slides", "interview", "caption", "hashtags", "post_caption", "music", "brief", "source_url", "target_duration_seconds", "avatar_provider", "avatar_layout", "background_mode", "subtitle_style", "subtitle_emojis", "video_model", "dashboard_url" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/videos/{id}/posts": { "get": { "operationId": "v1_videos_id_posts_get", "tags": ["Videos"], "summary": "List a video's posts", "description": "Every post of this video to a social account: scheduled, in progress, published (with its `permalink`), failed or canceled. Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "status": { "type": "string", "enum": [ "scheduled", "pending", "publishing", "published", "failed", "canceled", "deleted" ] }, "media_type": { "type": "string", "enum": ["video", "carousel", "image", "text"] }, "permalink": { "type": ["string", "null"] }, "scheduled_for": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "provider", "status", "media_type", "permalink", "scheduled_for", "published_at", "error" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "cursor": { "type": "string" }, "page_size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_videos_id_posts_post", "tags": ["Videos"], "summary": "Post a video", "description": "Post a `ready` video to connected social accounts (`GET /v1/social-connections`) now, or at `scheduled_for`. One post per account, so a failure on one network leaves the others alone. `caption` defaults to the video's caption and hashtags; `captions` overrides it per platform. A slideshow can go out as its slides with `media_type: carousel` (TikTok and Instagram). Cancel a scheduled post with `DELETE /v1/posts/{id}`. Free.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "connection_ids": { "minItems": 1, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "Accounts to post to, from `GET /v1/social-connections`" }, "caption": { "description": "The caption for every platform without its own. Omit to use the video's caption and hashtags.", "type": "string", "maxLength": 4000 }, "captions": { "description": "A platform's own caption, checked against that platform's limits", "type": "object", "propertyNames": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "additionalProperties": { "type": "string", "maxLength": 4000 } }, "media_type": { "default": "video", "description": "What goes out. `video` is the MP4. A slideshow post goes out as what it is: `carousel` (its slides; every platform but YouTube), `image` (its one picture; every platform but YouTube) or `text` (its text alone; X, LinkedIn and Facebook only)", "type": "string", "enum": ["video", "carousel", "image", "text"] }, "scheduled_for": { "description": "Post at this time (at least a minute ahead, up to a year). Omit to post now.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "settings": { "default": {}, "description": "Per-platform options; omitted ones use their defaults", "type": "object", "properties": { "tiktok": { "type": "object", "properties": { "mode": { "description": "`draft` sends it to the TikTok inbox to finish in the app", "type": "string", "enum": ["direct", "draft"] }, "privacy_level": { "type": "string", "enum": [ "public_to_everyone", "mutual_follow_friends", "follower_of_creator", "self_only" ] }, "allow_comments": { "type": "boolean" }, "allow_duet": { "type": "boolean" }, "allow_stitch": { "type": "boolean" }, "is_ai_generated": { "type": "boolean" }, "promotes_own_business": { "type": "boolean" }, "paid_partnership": { "type": "boolean" }, "cover_seconds": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 600 }, { "type": "null" } ] }, "photo_title": { "type": "string", "maxLength": 90 }, "auto_add_music": { "type": "boolean" }, "photo_cover_index": { "type": "integer", "minimum": 0, "maximum": 34 } }, "additionalProperties": false }, "instagram": { "type": "object", "properties": { "share_to_feed": { "type": "boolean" }, "location_id": { "description": "A Facebook Page id with an address", "type": ["string", "null"] }, "user_tags": { "maxItems": 20, "type": "array", "items": { "type": "string" } }, "collaborators": { "maxItems": 3, "type": "array", "items": { "type": "string" } }, "alt_texts": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "audio_name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "cover_seconds": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 900 }, { "type": "null" } ] }, "is_ai_generated": { "type": "boolean" } }, "additionalProperties": false }, "facebook": { "type": "object", "properties": { "published": { "type": "boolean" }, "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, "x": { "type": "object", "properties": { "reply_settings": { "type": "string", "enum": ["everyone", "following", "mentioned_users"] } }, "additionalProperties": false }, "linkedin": { "type": "object", "properties": { "visibility": { "type": "string", "enum": ["public", "connections"] } }, "additionalProperties": false }, "youtube": { "type": "object", "properties": { "title": { "description": "The video's title. Omit to use the caption's first line", "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": ["public", "unlisted", "private"] }, "made_for_kids": { "type": "boolean" }, "notify_subscribers": { "type": "boolean" }, "is_ai_generated": { "description": "Adds YouTube's altered or synthetic content disclosure", "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": ["connection_ids", "media_type", "settings"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "scheduled_for": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "connection_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": ["id", "connection_id"], "additionalProperties": false } } }, "required": ["scheduled_for", "posts"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/videos/{id}/retry": { "post": { "operationId": "v1_videos_id_retry_post", "tags": ["Videos"], "summary": "Retry a video", "description": "Resume a `failed` video (or one stuck mid-pipeline) from where it stopped, keeping every part that was already made. Free: a video is charged once, however many times it is retried. No body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "unsubmitted", "queued", "researching", "script_review", "rendering", "compositing", "ready", "failed" ], "description": "`queued` → `researching` → `script_review` (waiting for approval) → `rendering` → `compositing` → `ready`, or `failed`. `unsubmitted` is a draft saved in the dashboard." }, "template": { "type": "string", "enum": [ "talking_avatar", "remotion", "site_demo", "freeform_ai", "meme_hook", "interview", "phone_mockup", "slideshow", "real_footage", "video_edit" ] }, "preset": { "type": ["string", "null"] }, "format": { "type": "string", "enum": ["vertical", "horizontal"] }, "duration_seconds": { "type": ["number", "null"] }, "video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The finished MP4, once `ready`. A signed link that needs no API key, safe to hand to other services." }, "thumbnail_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "billed_cents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What the video was charged, once, when it was released to render. Null until then." }, "error": { "description": "Why it failed, or (in `script_review`) why an automatic approval was held back", "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "provider": { "type": "string", "enum": ["tiktok", "instagram", "facebook", "x", "linkedin", "youtube"] }, "status": { "type": "string", "enum": [ "scheduled", "pending", "publishing", "published", "failed", "canceled", "deleted" ] }, "media_type": { "type": "string", "enum": ["video", "carousel", "image", "text"] }, "permalink": { "type": ["string", "null"] }, "scheduled_for": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, "error": { "type": ["string", "null"] } }, "required": [ "id", "provider", "status", "media_type", "permalink", "scheduled_for", "published_at", "error" ], "additionalProperties": false } }, "price_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the video costs: the amount charged once released, otherwise the quote for the script (or, before it is written, the estimate)." }, "price_estimated": { "type": "boolean", "description": "True while the price is an estimate from the length asked for" }, "script_approved": { "type": "boolean" }, "user_script": { "type": "boolean", "description": "True when you supplied the script" }, "script": { "description": "The spoken words, once written", "type": ["string", "null"] }, "script_sections": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "text": { "type": "string" } }, "required": ["label", "text"], "additionalProperties": false } }, { "type": "null" } ], "description": "A scrolling background's script, one part per section" }, "scenes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "duration_seconds": { "type": "number" }, "voiceover": { "type": "string" }, "caption": { "type": ["string", "null"] }, "prompt": { "type": ["string", "null"] } }, "required": [ "id", "label", "duration_seconds", "voiceover", "caption", "prompt" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A scene template's shot list, once planned" }, "slides": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "headline": { "type": "string" }, "body": { "type": ["string", "null"] }, "position": { "type": "string" }, "prompt": { "type": ["string", "null"] }, "image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "role", "headline", "body", "position", "prompt", "image_url" ], "additionalProperties": false } }, { "type": "null" } ], "description": "A slideshow's slides, once planned; `image_url` once rendered" }, "interview": { "anyOf": [ { "type": "object", "properties": { "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "face_name": { "type": "string" } }, "required": ["id", "role", "face_name"], "additionalProperties": false } }, "turns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "speaker_id": { "type": "string" }, "text": { "type": "string" } }, "required": ["id", "speaker_id", "text"], "additionalProperties": false } } }, "required": ["speakers", "turns"], "additionalProperties": false }, { "type": "null" } ] }, "caption": { "type": ["string", "null"] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "post_caption": { "description": "The caption with its hashtags, as it is posted by default", "type": ["string", "null"] }, "music": { "anyOf": [ { "type": "object", "properties": { "library": { "type": "string", "enum": ["lumisreach", "epidemic", "generated"], "description": "`generated`: a track an AI model made for your organization in the dashboard" }, "track_id": { "type": "string" }, "title": { "type": "string" }, "volume": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": ["pending", "mixing", "applied", "failed"] } }, "required": ["library", "track_id", "title", "volume", "status"], "additionalProperties": false }, { "type": "null" } ] }, "brief": { "description": "What the video was asked to be, when a `brief` was given", "type": ["string", "null"] }, "source_url": { "type": ["string", "null"] }, "target_duration_seconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avatar_provider": { "type": "string", "enum": ["heygen", "tavus", "elevenlabs"] }, "avatar_layout": { "type": "string", "enum": ["center", "bubble_bottom_left", "bubble_bottom_right", "audio_only"] }, "background_mode": { "type": "string", "enum": ["static", "scrolling", "footage", "automated_demo", "original", "image"] }, "subtitle_style": { "type": "string", "enum": [ "none", "classic", "boxed", "bold_words", "dynamic", "dynamic_highlight", "emphasis", "enlarge", "one_word", "comic", "highlight" ] }, "subtitle_emojis": { "type": "boolean" }, "video_model": { "type": ["string", "null"] }, "dashboard_url": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "status", "template", "preset", "format", "duration_seconds", "video_url", "thumbnail_url", "billed_cents", "error", "created_at", "updated_at", "posts", "price_cents", "price_estimated", "script_approved", "user_script", "script", "script_sections", "scenes", "slides", "interview", "caption", "hashtags", "post_caption", "music", "brief", "source_url", "target_duration_seconds", "avatar_provider", "avatar_layout", "background_mode", "subtitle_style", "subtitle_emojis", "video_model", "dashboard_url" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["videos:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/caller-ids": { "get": { "operationId": "v1_voice_caller_ids_get", "tags": ["Caller IDs"], "summary": "List caller IDs", "description": "Returns all caller IDs for the authenticated team, including verification status and CNAM details.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_voice_caller_ids_post", "tags": ["Caller IDs"], "summary": "Start caller ID verification", "description": "Initiates a call-based verification for the given phone number. Telnyx will call the number and read a verification code that must be submitted via POST /v1/voice/caller-ids/{id}/verify.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "phone_number": { "type": "string", "minLength": 1 } }, "required": ["phone_number"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/caller-ids/{id}": { "patch": { "operationId": "v1_voice_caller_ids_id_patch", "tags": ["Caller IDs"], "summary": "Update CNAM display name", "description": "Sets the CNAM display name for a verified caller ID. If the caller ID's phone number is also a Telnyx-provisioned phone, the CNAM update is pushed to the carrier.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "cnam_display_name": { "type": "string", "minLength": 1, "maxLength": 15 } }, "required": ["cnam_display_name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/caller-ids/{id}/verify": { "post": { "operationId": "v1_voice_caller_ids_id_verify_post", "tags": ["Caller IDs"], "summary": "Submit verification code", "description": "Submits the verification code received during the caller ID verification call. On success the caller ID status changes to VERIFIED.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "verification_code": { "type": "string", "minLength": 1 } }, "required": ["verification_code"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/calls": { "get": { "operationId": "v1_voice_calls_get", "tags": ["Dialer Calls"], "summary": "List dialer calls", "description": "The workspace's dialer calls (`POST /v1/voice/calls`), with optional filtering by status, date range, and pagination. For every call, including the AI agent's, with transcripts, use `GET /v1/calls`.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_voice_calls_post", "tags": ["Dialer Calls"], "summary": "Place a dialer call", "description": "Places a click-to-call dialer call that shows one of your verified caller IDs (`GET /v1/voice/caller-ids`). The call is routed through Telnyx with caller ID masking applied. For an AI agent call use `POST /v1/quick/ai-calls`; to call from one of your own numbers use `POST /v1/calls/dial`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "caller_id": { "type": "string", "minLength": 1 }, "destination": { "type": "string", "minLength": 1 }, "record": { "type": "boolean" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["caller_id", "destination"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/calls/webhooks": { "get": { "operationId": "v1_voice_calls_webhooks_get", "tags": ["Calls"], "summary": "List call webhooks", "description": "The URLs registered to receive `call.started` and/or `call.ended` events for the workspace's calls. Signing secrets are never returned.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "active": { "type": "boolean" }, "phone_number_id": { "type": ["number", "null"] }, "phone_number": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "enum": ["call.started", "call.ended"] } }, "created_at": { "type": "string" } }, "required": [ "id", "url", "description", "active", "phone_number_id", "phone_number", "events", "created_at" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page_size": { "type": "number" } }, "required": ["page_size"], "additionalProperties": false } }, "required": ["data", "meta"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true }, "post": { "operationId": "v1_voice_calls_webhooks_post", "tags": ["Calls"], "summary": "Create a call webhook", "description": "Registers an HTTPS URL that LumisReach POSTs to when a call on one of your numbers (or only `phone_number_id`, if given) starts (`call.started`) and when it ends (`call.ended`). `call.ended` is sent once the call's transcript is saved and carries the full transcript, as plain text and turn by turn. Covers inbound and outbound AI calls on both voice stacks. Each delivery is signed with `X-LumisReach-Signature-256` (hex HMAC-SHA256 of the raw body, keyed with the `secret` returned here once). A delivery that fails or gets a non-2xx response is retried 3 times over about 36 minutes.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS endpoint that receives a POST for every call event" }, "events": { "description": "Which events to send. Defaults to both `call.started` and `call.ended`.", "minItems": 1, "type": "array", "items": { "type": "string", "enum": ["call.started", "call.ended"] } }, "phone_number_id": { "description": "Only calls on this number (id from `GET /v1/phone-numbers`). Omit for all your numbers.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "description": "A label for the webhook", "type": "string", "maxLength": 100 } }, "required": ["url"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": ["string", "null"] }, "active": { "type": "boolean" }, "phone_number_id": { "type": ["number", "null"] }, "phone_number": { "type": ["string", "null"] }, "events": { "type": "array", "items": { "type": "string", "enum": ["call.started", "call.ended"] } }, "created_at": { "type": "string" }, "secret": { "type": "string", "description": "Signing secret. Every delivery carries `X-LumisReach-Signature-256`: the hex HMAC-SHA256 of the raw body with this secret. Shown once." } }, "required": [ "id", "url", "description", "active", "phone_number_id", "phone_number", "events", "created_at", "secret" ], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/calls/webhooks/{id}": { "delete": { "operationId": "v1_voice_calls_webhooks_id_delete", "tags": ["Calls"], "summary": "Delete a call webhook", "description": "Stops `call.started` / `call.ended` deliveries to this webhook. Retries already scheduled for it are dropped.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": ["id", "deleted"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/calls/webhooks/{id}/test": { "post": { "operationId": "v1_voice_calls_webhooks_id_test_post", "tags": ["Calls"], "summary": "Send a test call event", "description": "POSTs a sample, correctly signed event (with `test: true`) to the webhook right away and reports how your server answered: a `call.ended` with a short transcript, or `call.started` if the webhook only listens for that. Not retried.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "status": { "type": ["number", "null"] }, "error": { "type": ["string", "null"] } }, "required": ["delivered", "status", "error"], "additionalProperties": false } }, "required": ["data"], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/calls/{id}": { "get": { "operationId": "v1_voice_calls_id_get", "tags": ["Dialer Calls"], "summary": "Get a dialer call", "description": "One dialer call by id, including duration, status, and recording URL.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/voice/calls/{id}/hangup": { "post": { "operationId": "v1_voice_calls_id_hangup_post", "tags": ["Dialer Calls"], "summary": "Hang up a dialer call", "description": "Terminates an active call. The call must be in a ringing or in-progress state. Uses the stored Telnyx call_control_id to issue the hangup command.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } }, "/v1/voice/usage": { "get": { "operationId": "v1_voice_usage_get", "tags": ["Usage"], "summary": "Voice usage stats", "description": "Returns aggregated voice usage for the current calendar month: total calls placed, minutes used, and a breakdown by call status.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/voice/usage/{phoneId}": { "get": { "operationId": "v1_voice_usage_phoneId_get", "tags": ["Usage"], "summary": "Per-phone usage", "description": "Returns voice usage for a specific phone number in the current calendar month. The phone must belong to the authenticated user or team.", "parameters": [ { "name": "phoneId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:read"], "x-rate-limit": { "requestsPerMinute": 600 }, "x-demo-eligible": true } }, "/v1/voice/webrtc-token": { "post": { "operationId": "v1_voice_webrtc_token_post", "tags": ["WebRTC"], "summary": "Get WebRTC connection token", "description": "Generates a short-lived Telnyx WebRTC JWT for use with the TelnyxRTC SDK. The mobile/web client uses this token to establish a WebRTC session and dial directly from the client side.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID. When present, deduplicates repeat submissions. See /api-reference/idempotency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (incl. idempotency conflicts)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-scopes": ["voice:write"], "x-rate-limit": { "requestsPerMinute": 600 } } } } }