{ "openapi": "3.1.0", "info": { "title": "AgentLine", "description": "AgentLine gives every AI agent a real US or Canadian phone number and a human-like voice. Agents can make and receive calls and send and receive SMS. This spec covers the core developer surface: agents, numbers, calls, messages, events, webhooks, billing, and voice.", "version": "0.3.0", "summary": "US and Canadian phone numbers and voice for AI agents, with SMS in both directions.", "contact": { "name": "AgentLine", "url": "https://agentline.cloud" }, "license": { "name": "MIT", "url": "https://opensource.org/license/mit" } }, "paths": { "/v1/account/voice": { "get": { "tags": [ "Voice" ], "summary": "Get Account Voice", "description": "Get the current account-level default voice for AI phone agents.\n\nReturns which voice is used for all AI agents under this account\nunless overridden at the agent level or per-call. Controls how\nyour AI agents sound during phone conversations.", "operationId": "get_account_voice", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "voice" ], "x-fern-sdk-method-name": "get" }, "delete": { "tags": [ "Voice" ], "summary": "Reset Account Voice", "description": "Reset account voice to the system default.\n\nRemoves the account-level voice override so all AI agents fall back\nto the system default voice during phone calls (unless they have\ntheir own voice_id configured).", "operationId": "reset_account_voice", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "voice" ], "x-fern-sdk-method-name": "reset" }, "patch": { "tags": [ "Voice" ], "summary": "Update Account Voice", "description": "Set the account-level default voice for AI phone agents.\n\nThis becomes the default voice for ALL AI agents under this account,\ncontrolling how they sound on phone calls. Individual agents or\nspecific calls can still override this setting.\n\nVoice resolution priority:\n 1. Per-call voice_id (POST /v1/calls)\n 2. Agent voice_id (PATCH /v1/agents/{id})\n 3. Account default (this endpoint) ← you are here\n 4. System default (Supportive Male)\n\nAccepts:\n - A preset name: \"female-1\", \"female-2\", \"female-3\", \"male-1\", \"male-2\", \"male-3\"\n - A Cartesia voice UUID: \"f786b574-daa5-4673-aa0c-cbe3e8534c02\"", "operationId": "set_account_voice", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSettingUpdate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "voice" ], "x-fern-sdk-method-name": "set" } }, "/v1/agents": { "get": { "tags": [ "Agents" ], "summary": "List Agents", "description": "List all AI voice agents configured on your account.\n\nReturns every AI phone agent you've created, including their\nsystem prompts, voice settings, and associated phone numbers.\nUseful for checking which agents are ready to make or receive calls.", "operationId": "list_agents", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "list" }, "post": { "tags": [ "Agents" ], "summary": "Create Agent", "description": "Create a new AI voice agent for telephony.\n\nSets up a new AI phone agent with a custom system prompt, voice,\nand greeting. Once created, buy a phone number and attach it to\nthis agent so it can make and receive calls autonomously.\n\nFields:\n - name: Display name for the agent\n - system_prompt: Instructions that define the agent's personality and behavior on calls\n - initial_greeting: What the AI agent says when the call connects\n - voice_id: TTS voice preset (e.g. \"female-1\") or Cartesia UUID\n - transfer_number: Must be the owner phone. Live calls transfer only to owner_phone.\n - voicemail_message: Message the agent leaves if the call goes to voicemail\n - owner_phone: Owner's E.164 number. Task mode, and the only transfer destination.", "operationId": "create_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOut" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "create" } }, "/v1/agents/{agent_id}": { "get": { "tags": [ "Agents" ], "summary": "Get Agent", "description": "Get details of a specific AI voice agent.\n\nReturns the agent's full configuration including system prompt,\nvoice settings, greeting, and transfer number.", "operationId": "get_agent", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "get" }, "patch": { "tags": [ "Agents" ], "summary": "Update Agent", "description": "Update an AI voice agent's configuration.\n\nModify any combination of the agent's settings: system prompt,\nvoice, greeting, transfer number, or voicemail message.\nChanges take effect on the next call the agent handles.\nOnly include the fields you want to change — unset fields are preserved.", "operationId": "update_agent", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "update" }, "delete": { "tags": [ "Agents" ], "summary": "Delete Agent", "description": "Delete an AI voice agent.\n\nPermanently removes the agent, its calls, messages, and conversations,\nand detaches any phone numbers assigned to it. Detached numbers remain\nactive on your account and can be reassigned to another agent.", "operationId": "delete_agent", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "delete" } }, "/v1/billing/balance": { "get": { "tags": [ "Billing" ], "summary": "Get Balance", "description": "Get your AI telephony account balance and rate card.\n\nReturns the current balance and currency. Plan allowances are used first. Calls beyond the allowance are 0.12 USD per minute in both directions. A 0-second call is free. A connected call has a one-minute minimum, then the actual duration rounded up to the cent. Additional phone numbers are 3.00 USD per month. The rate card also includes SMS, sent or received.\nUse this to check affordability before paid telephony operations.", "operationId": "get_account_balance", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "billing" ], "x-fern-sdk-method-name": "get_balance" } }, "/v1/billing/expenditure": { "get": { "tags": [ "Billing" ], "summary": "Get Expenditure", "description": "Get a detailed expenditure breakdown for AI telephony usage.\n\nShows total spend split by category (voice calls, phone number\nprovisioning, top-ups, refunds) with counts and averages.\nUseful for tracking how much your AI agents are spending on\nphone calls and phone numbers.", "operationId": "get_expenditure_breakdown", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "description": "Time period: 'current_month', 'last_month', 'all_time', or 'YYYY-MM'", "default": "current_month", "title": "Period" }, "description": "Time period: 'current_month', 'last_month', 'all_time', or 'YYYY-MM'" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "billing" ], "x-fern-sdk-method-name": "get_expenditure" } }, "/v1/billing/expenditure/calls": { "get": { "tags": [ "Billing" ], "summary": "Get Call Expenditure", "description": "List individual call charges from AI agent phone calls.\n\nEach entry includes the voice call duration, cost, direction\n(inbound/outbound), phone numbers involved, and timestamp.\nShows exactly how much each AI agent call cost.", "operationId": "get_call_charges", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of call charges to return (1-200)", "default": 50, "title": "Limit" }, "description": "Maximum number of call charges to return (1-200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of records to skip for pagination", "default": 0, "title": "Offset" }, "description": "Number of records to skip for pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "billing" ], "x-fern-sdk-method-name": "list_call_charges" } }, "/v1/billing/expenditure/numbers": { "get": { "tags": [ "Billing" ], "summary": "Get Number Expenditure", "description": "List phone number provisioning charges.\n\nShows the cost of each phone number bought for your AI agents,\nincluding the number, country, and current status.", "operationId": "get_number_charges", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of number charges to return (1-200)", "default": 50, "title": "Limit" }, "description": "Maximum number of number charges to return (1-200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of records to skip for pagination", "default": 0, "title": "Offset" }, "description": "Number of records to skip for pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "billing" ], "x-fern-sdk-method-name": "list_number_charges" } }, "/v1/billing/summary": { "get": { "tags": [ "Billing" ], "summary": "Get Spending Summary", "description": "Month-over-month spending summary.\n\nReturns total debits grouped by month for trend analysis.", "operationId": "get_spending_summary", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "months", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 24, "minimum": 1, "description": "Number of months to show", "default": 6, "title": "Months" }, "description": "Number of months to show" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "billing" ], "x-fern-sdk-method-name": "get_summary" } }, "/v1/calls": { "post": { "tags": [ "Calls" ], "summary": "Create Call", "description": "Make an outbound phone call from your AI agent.\n\nDials a real person or business from the agent's number. The agent holds\nthe whole conversation on its own with its system prompt, voice and\ngreeting (or this call's overrides). The call reaches a third party and\nis billed to the account at $0.12 per minute, first minute charged in\nfull, so confirm with the user first. Not idempotent: every successful\ncall dials again.\n\nPrerequisites: an agent with an active number from buy_phone_number\n(HTTP 400 otherwise), plus remaining subscription minutes or at least\n$0.50 of wallet balance (HTTP 402 otherwise). Included minutes are used\nfirst; only uncovered call time is charged to the wallet.\n\nReturns right after dialing with the call id (call_...), agent_id,\nfrom_number, to_number, direction, status and started_at; the call runs\non its own. Check get_call_details for progress and call\nget_call_transcript once status is completed.", "operationId": "make_outbound_call", "security": [ { "API Key or OAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "calls" ], "x-fern-sdk-method-name": "create" }, "get": { "tags": [ "Calls" ], "summary": "List Calls", "description": "List voice calls made by your AI agents.\n\nReturns call history with optional filters by agent or status.\nEach entry includes direction (inbound/outbound), duration,\nphone numbers, and current status.\n\nFilters:\n - agent_id: only calls for a specific AI agent\n - status: \"initiated\", \"in-progress\", \"completed\", or \"failed\"", "operationId": "list_calls", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter calls by AI agent ID", "title": "Agent Id" }, "description": "Filter calls by AI agent ID" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by call status: 'initiated', 'in-progress', 'completed', or 'failed'", "title": "Status" }, "description": "Filter by call status: 'initiated', 'in-progress', 'completed', or 'failed'" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of calls to return (1-200)", "default": 50, "title": "Limit" }, "description": "Maximum number of calls to return (1-200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of calls to skip for pagination", "default": 0, "title": "Offset" }, "description": "Number of calls to skip for pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "calls" ], "x-fern-sdk-method-name": "list" } }, "/v1/calls/{call_id}": { "get": { "tags": [ "Calls" ], "summary": "Get Call", "description": "Get full details of a specific voice call.\n\nReturns the call's metadata including direction, phone numbers,\nstatus, duration, AI agent configuration used, and the full\nconversation transcript between the AI agent and the caller.", "operationId": "get_call_details", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "calls" ], "x-fern-sdk-method-name": "get" } }, "/v1/calls/{call_id}/context": { "post": { "tags": [ "Calls" ], "summary": "Push Call Context", "description": "Push context into a LIVE relay-mode call (mid-call context injection).\n\nThis is the required way for backend agents (Hermes, OpenClaw, etc.) to\nanswer a live caller after a ``call.utterance`` event. Do your work, then\nPOST short facts, not a script. Include ``disposition``.\n``progress`` adds a note and keeps the caller on hold with canned lines; the text is not spoken, and the turn stays open.\n``done`` (the default), ``facts``, and ``failed`` close the turn. The hosted voice rephrases the facts in one or two sentences. It does not read your text aloud.\n``noop`` closes the turn with no facts.\nYou receive this request only for something\nthe hosted voice does not know. Poll ``GET /v1/calls/{call_id}`` for updates.\n\nAUTHENTICATION (one of):\n 1. **Push token** (preferred — no API key): the ``push_token`` from the\n ``call.utterance`` payload, via ``X-Push-Token`` header, ``?token=``\n query param, or ``push_token`` body field.\n 2. **Bearer API key**: ``Authorization: Bearer al_live_...`` for the\n account that owns the call.\n\nBody — any of these keys works (``context`` is canonical):\n {\"context\": \"John emailed yesterday about an invoice.\"}\n\nOther accepted keys: ``summary``, ``answer``, ``response``, ``reply``,\n``text``, ``result``.\n\nEvery response must include the exact ``turn_id`` from ``call.utterance``.\nLate context is rejected instead of being applied to another question.\n\nReturns:\n delivered=true, status=\"live\" — accepted for this turn\n delivered=true, status=\"duplicate\" — identical retry already accepted\n HTTP 409 — turn is stale/cancelled\n HTTP 410 — **call has ended.** STOP working\n on this request and abandon any in-flight lookup.", "operationId": "push_call_context", "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } }, { "name": "token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Push token (alt to X-Push-Token header / body).", "title": "Token" }, "description": "Push token (alt to X-Push-Token header / body)." }, { "name": "turn_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Turn ID from call.utterance.", "title": "Turn Id" }, "description": "Turn ID from call.utterance." }, { "name": "X-Push-Token", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Push-Token" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "calls" ], "x-fern-sdk-method-name": "push_context", "security": [ { "API Key or OAuth": [] } ] } }, "/v1/calls/{call_id}/hangup": { "post": { "tags": [ "Calls" ], "summary": "Hangup Call", "description": "Hang up an active phone call.\n\nProgrammatically terminates an in-progress voice call. Use this\nwhen the AI agent needs to end the conversation, or to force-stop\na call that is no longer needed. The call's final transcript and\nbilling are processed automatically after hangup.", "operationId": "hangup_call", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "calls" ], "x-fern-sdk-method-name": "hangup" } }, "/v1/calls/{call_id}/transcript": { "get": { "tags": [ "Calls" ], "summary": "Get Transcript", "description": "Get the full conversation transcript for a call.\n\nReturns the complete speech-to-text transcript of the phone call,\nwith each turn labeled by role (\"human\" for the caller, \"agent\"\nfor the AI agent). The call.utterance conversation field uses user and assistant instead. Useful for reviewing what was said on the call,\nextracting information, or auditing AI agent behavior.", "operationId": "get_call_transcript", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "calls" ], "x-fern-sdk-method-name": "get_transcript" } }, "/v1/events": { "get": { "tags": [ "Events" ], "summary": "List Events", "description": "Poll for telephony events from your AI agents.\n\nReturns pending events such as call completions, transcripts, and\nfailures. Events are consumed on retrieval (one-time read) — once\npolled, they are automatically deleted from the mailbox.\n\nYour AI agent should call this endpoint periodically to receive\nnotifications about completed calls and their transcripts.\n\nFilters:\n - agent_id: only events for a specific AI agent\n - event_type: e.g. \"call.completed\", \"call.failed\"", "operationId": "poll_events", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter events by AI agent ID", "title": "Agent Id" }, "description": "Filter events by AI agent ID" }, { "name": "event_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by event type (e.g. 'call.completed', 'call.failed')", "title": "Event Type" }, "description": "Filter by event type (e.g. 'call.completed', 'call.failed')" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of events to return (1-200)", "default": 50, "title": "Limit" }, "description": "Maximum number of events to return (1-200)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "events" ], "x-fern-sdk-method-name": "poll" } }, "/v1/events/peek": { "get": { "tags": [ "Events" ], "summary": "Peek Events", "description": "Peek at pending telephony events without consuming them.\n\nReturns a preview of queued events (call completions, transcripts)\nwithout removing them from the mailbox. Useful for checking if\nthere are events to process before committing to retrieve them.", "operationId": "peek_events", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter events by AI agent ID", "title": "Agent Id" }, "description": "Filter events by AI agent ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of events to preview (1-200)", "default": 50, "title": "Limit" }, "description": "Maximum number of events to preview (1-200)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "events" ], "x-fern-sdk-method-name": "peek" } }, "/v1/messages": { "post": { "tags": [ "Messages" ], "summary": "Send Message", "description": "Send an outbound SMS message from an AI agent's phone number.", "operationId": "send_sms", "security": [ { "API Key or OAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSend" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "messages" ], "x-fern-sdk-method-name": "send" }, "get": { "tags": [ "Messages" ], "summary": "List Messages", "description": "List SMS messages for your AI agents.\n\nReturns texts received on the agent's number and stored message history. Optional filters: AI agent or conversation. Each entry includes direction, phone numbers, message body, and delivery status.", "operationId": "list_messages", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter messages by AI agent ID", "title": "Agent Id" }, "description": "Filter messages by AI agent ID" }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter messages by conversation thread ID", "title": "Conversation Id" }, "description": "Filter messages by conversation thread ID" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of messages to return (1-200)", "default": 50, "title": "Limit" }, "description": "Maximum number of messages to return (1-200)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of messages to skip for pagination", "default": 0, "title": "Offset" }, "description": "Number of messages to skip for pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "messages" ], "x-fern-sdk-method-name": "list" } }, "/v1/messages/conversations": { "get": { "tags": [ "Messages" ], "summary": "List Conversations", "description": "List SMS conversation threads for your AI agents.\n\nThreads can be filtered by AI agent and include messages received on the agent's phone number.", "operationId": "list_conversations", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "messages" ], "x-fern-sdk-method-name": "list_conversations" } }, "/v1/numbers": { "get": { "tags": [ "Numbers" ], "summary": "List Numbers", "description": "List all phone numbers provisioned on your account.\n\nReturns every phone number you've bought for your AI agents,\nincluding which agent each number is assigned to, the number's\nstatus (active/released), and country.", "operationId": "list_phone_numbers", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "numbers" ], "x-fern-sdk-method-name": "list" }, "post": { "tags": [ "Numbers" ], "summary": "Provision", "description": "Buy a US or Canadian phone number for your AI agent.\n\nBuys a real +1 number from the carrier, attaches it to the agent and\nuses an included subscription number, or charges $3.00 to the wallet. Once attached, the agent can make\noutbound calls and answers inbound calls on this number. Not idempotent:\nevery successful call buys and charges for another number.\n\nPrerequisites: an agent from create_agent with no active number (each\nagent has at most one; a second purchase returns HTTP 409), plus a remaining\nsubscription number allowance or $3.00 in the wallet\n(HTTP 402 otherwise; see get_account_balance).\n\nReturns the number's id (num_..., used by release_phone_number and as\nfrom_number_id), phone_number, country, number_type, status, cost,\nbalance_remaining and a private number card link (card_url,\ncard_image_url, card_url_expires_at). If the account has an owner email,\nthe card link is also emailed there.", "operationId": "buy_phone_number", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberProvision" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "API Key or OAuth": [] } ], "x-fern-sdk-group-name": [ "numbers" ], "x-fern-sdk-method-name": "buy" } }, "/v1/numbers/{number_id}": { "get": { "tags": [ "Numbers" ], "summary": "Get Number", "description": "Get details of a specific phone number.\n\nReturns the phone number, its assigned AI agent, provider ID,\ncountry, and current status.", "operationId": "get_phone_number", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "number_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Number Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "numbers" ], "x-fern-sdk-method-name": "get" } }, "/v1/numbers/{number_id}/reassign": { "patch": { "tags": [ "Numbers" ], "summary": "Reassign Number", "description": "Reassign a phone number to a different AI agent.\n\nMoves an existing phone number from one AI agent to another.\nThe target agent must not already have an active number assigned.\nThe phone number remains active — only the agent ownership changes.", "operationId": "reassign_number", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "number_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Number Id" } }, { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Agent Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "numbers" ], "x-fern-sdk-method-name": "reassign" } }, "/v1/numbers/{number_id}/release": { "post": { "tags": [ "Numbers" ], "summary": "Release Phone Number", "description": "Permanently release a phone number that is not in use.\n\nDestructive: unrents the number from the carrier. The number cannot be recovered, and calls and texts to it will stop. Refused while a call is in progress or a lease is still active.", "operationId": "release_phone_number", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "number_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Number Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "numbers" ], "x-fern-sdk-method-name": "release" } }, "/v1/voices": { "get": { "tags": [ "Voice" ], "summary": "Get Available Voices", "description": "List all available voice presets for AI phone agents.\n\nReturns named TTS (text-to-speech) voice presets that can be used\nwhen configuring AI agents or making phone calls. Each voice defines\nhow your AI agent sounds on the phone.\n\nYou can use a preset name (e.g. \"female-1\", \"male-1\") or pass any\nvalid Cartesia voice UUID directly as a voice_id.", "operationId": "list_available_voices", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "x-fern-sdk-group-name": [ "voice" ], "x-fern-sdk-method-name": "list", "security": [ { "API Key or OAuth": [] } ] } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhooks", "description": "List the account's per-agent webhook configuration(s).\n\nSecrets are **masked**. Pass `agent_id` to inspect a single agent's webhook.\nThe full secret is only ever shown once, on the POST that creates/replaces it.", "operationId": "get_webhook", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Inspect one agent's webhook (omit to list all)", "title": "Agent Id" }, "description": "Inspect one agent's webhook (omit to list all)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "webhooks" ], "x-fern-sdk-method-name": "list" }, "post": { "tags": [ "Webhooks" ], "summary": "Set Webhook", "description": "Create or replace an agent's webhook.\n\nThe configured URL receives ALL of that agent's event types — `call.received` (inbound answer), `call.utterance`, `call.completed`, `call.owner_task`, `call.failed`, `call.busy`, `call.no-answer`, `call.canceled`, `sms.received`, and `webhook.test` — as signed JSON POSTs. Each agent may have at most one\nwebhook; POSTing again replaces it.\n\n- `agent_id`: the agent whose events this webhook receives (required).\n- `secret`: HMAC signing secret. Omit to auto-generate.\n\nThe response returns the full `secret` **once** — store it to verify the\nsignature header on deliveries.", "operationId": "set_webhook", "security": [ { "API Key or OAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "webhooks" ], "x-fern-sdk-method-name": "set" }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Webhook", "description": "Remove an agent's webhook. No events for that agent will be delivered via\nHTTP afterwards; they remain available via GET /v1/events (the mailbox).", "operationId": "delete_webhook", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Agent whose webhook to delete", "title": "Agent Id" }, "description": "Agent whose webhook to delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "webhooks" ], "x-fern-sdk-method-name": "delete" } }, "/v1/webhooks/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test Webhook", "description": "Fire a signed `webhook.test` event to the agent's webhook.\n\nUses the exact same event bus (publish_event) that real telephony events use,\nso a successful delivery confirms the entire pipeline is wired correctly.\nReturns 404 if no webhook is configured for the agent.", "operationId": "test_webhook", "security": [ { "API Key or OAuth": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Agent whose webhook to test", "title": "Agent Id" }, "description": "Agent whose webhook to test" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-fern-sdk-group-name": [ "webhooks" ], "x-fern-sdk-method-name": "test" } } }, "components": { "schemas": { "AgentCreate": { "properties": { "name": { "type": "string", "title": "Name", "description": "Display name for the AI voice agent" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt", "description": "Default instructions for the agent's personality and behavior on ALL calls (inbound and outbound). Can be overridden per-call via POST /v1/calls." }, "initial_greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Greeting", "description": "Default opening line spoken on ALL calls (inbound and outbound), e.g. 'Hello, how can I help you today?'. Can be overridden per-call via POST /v1/calls." }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "TTS voice preset name (e.g. 'female-1', 'male-1') or Cartesia voice UUID; defaults to system voice if not set" }, "transfer_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfer Number", "description": "Ignored unless it is the owner phone. Live transfers always dial owner_phone; a different number is rejected." }, "voicemail_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemail Message", "description": "Message the AI agent leaves if the call goes to voicemail" }, "owner_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Phone", "description": "Owner's phone number in E.164 format (e.g. '+12125551234'). Calls from this number enter task mode. This is also the only number a live call can be transferred to." } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "AgentCreate" }, "AgentIdPollRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id", "description": "Session id returned by /v1/auth/agentid/start" } }, "type": "object", "required": [ "session_id" ], "title": "AgentIdPollRequest" }, "AgentIdStartRequest": { "properties": { "login_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Login Hint", "description": "Optional AgentMail inbox, sent verbatim to AgentID as login_hint. Do not lowercase. Not required." } }, "type": "object", "title": "AgentIdStartRequest" }, "AgentOut": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique agent identifier (e.g. 'agt_abc123')" }, "account_id": { "type": "string", "title": "Account Id", "description": "Account that owns this agent" }, "name": { "type": "string", "title": "Name", "description": "Display name of the AI voice agent" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt", "description": "Default system prompt for all calls (can be overridden per-call)" }, "initial_greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Greeting", "description": "Default greeting for all calls (can be overridden per-call)" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "TTS voice preset or Cartesia UUID" }, "transfer_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfer Number", "description": "Always the owner phone. Live calls transfer only here." }, "voicemail_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemail Message", "description": "Message left on voicemail" }, "owner_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Phone", "description": "Owner's phone number for task mode and the only live-call transfer destination" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the agent was created" } }, "type": "object", "required": [ "id", "account_id", "name", "created_at" ], "title": "AgentOut" }, "AgentUpdate": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New display name for the AI voice agent" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt", "description": "Updated default instructions for ALL future calls (does not affect calls already in progress)" }, "initial_greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Greeting", "description": "Updated default greeting for ALL future calls (inbound and outbound)" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "New TTS voice preset name or Cartesia voice UUID" }, "transfer_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfer Number", "description": "Must match owner_phone. A different number is rejected; setting owner_phone updates this to the same number." }, "voicemail_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemail Message", "description": "Updated voicemail message" }, "owner_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Phone", "description": "Updated owner phone in E.164. Also becomes the only live-call transfer destination." } }, "additionalProperties": false, "type": "object", "title": "AgentUpdate" }, "CallRequest": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of the AI agent making the call (e.g. 'agt_abc123')" }, "to_number": { "type": "string", "title": "To Number", "description": "Destination phone number in E.164 format (e.g. '+12125551234')" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt", "description": "Per-call system prompt override. Replaces the agent's default prompt for this call ONLY. If omitted, the agent's default system_prompt is used." }, "initial_greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Greeting", "description": "Per-call greeting override. Replaces the agent's default greeting for this call ONLY. If omitted, the agent's default initial_greeting is used." }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "Override the TTS voice for this call: preset name (e.g. 'female-1') or Cartesia UUID" }, "from_number_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Number Id", "description": "Specific phone number ID to call from; defaults to the agent's assigned number" } }, "type": "object", "required": [ "agent_id", "to_number" ], "title": "CallRequest" }, "FeedbackCategory": { "type": "string", "enum": [ "bug", "feature_request", "difficulty", "feedback" ], "title": "FeedbackCategory" }, "FeedbackCreate": { "properties": { "category": { "$ref": "#/components/schemas/FeedbackCategory", "description": "Type of feedback: 'bug' (something broken / not working), 'feature_request' (want a new capability), 'difficulty' (hard or confusing to use), or 'feedback' (general comment or praise)" }, "message": { "type": "string", "title": "Message", "description": "Detailed description of the feedback, issue, or request. For bugs, include what you expected vs. what actually happened." }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject", "description": "Short summary title for the feedback (optional)" }, "severity": { "$ref": "#/components/schemas/FeedbackSeverity", "description": "Impact level, mainly relevant for bugs: 'low', 'normal', 'high', or 'critical'", "default": "normal" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "ID of the AI agent this feedback relates to, if applicable" }, "contact_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Email", "description": "Email address for follow-up about this feedback (optional)" } }, "type": "object", "required": [ "category", "message" ], "title": "FeedbackCreate" }, "FeedbackOut": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique feedback identifier (e.g. 'fb_abc123')" }, "account_id": { "type": "string", "title": "Account Id", "description": "Account that submitted this feedback" }, "category": { "type": "string", "title": "Category", "description": "Feedback type: 'bug', 'feature_request', 'difficulty', or 'feedback'" }, "message": { "type": "string", "title": "Message", "description": "Full feedback message" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject", "description": "Short summary title" }, "severity": { "type": "string", "title": "Severity", "description": "Impact level: 'low', 'normal', 'high', or 'critical'" }, "agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Id", "description": "Related AI agent ID, if any" }, "contact_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Email", "description": "Follow-up email, if provided" }, "status": { "type": "string", "title": "Status", "description": "Current status: 'open', 'acknowledged', 'in_progress', 'resolved', or 'closed'" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the feedback was submitted" } }, "type": "object", "required": [ "id", "account_id", "category", "message", "severity", "status", "created_at" ], "title": "FeedbackOut" }, "FeedbackSeverity": { "type": "string", "enum": [ "low", "normal", "high", "critical" ], "title": "FeedbackSeverity" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "KeylessAgentUpdate": { "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt" }, "initial_greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Greeting" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "transfer_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfer Number" }, "voicemail_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemail Message" }, "owner_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Phone" } }, "type": "object", "title": "KeylessAgentUpdate", "description": "Partial agent update — only provided fields change (mirrors classic PATCH /v1/agents)." }, "KeylessBuyBody": { "properties": { "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name", "description": "Display name for the voice agent" }, "system_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Prompt", "description": "Personality/behavior instructions spoken on ALL calls" }, "initial_greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Greeting", "description": "Opening line spoken when a call connects" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "TTS voice preset (e.g. 'female-1') or Cartesia UUID" }, "transfer_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transfer Number", "description": "Must be the owner phone. Live transfers dial only owner_phone." }, "voicemail_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voicemail Message", "description": "Message left if the call goes to voicemail" }, "owner_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Phone", "description": "Owner's E.164 phone. Calls from it enter task mode, and it is the only live-call transfer destination." }, "country": { "type": "string", "title": "Country", "description": "Country code: 'US' or 'CA'", "default": "US" }, "number_type": { "type": "string", "title": "Number Type", "description": "'local' or 'tollfree'", "default": "local" }, "area_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Area Code", "description": "Preferred 3-digit US area code" } }, "type": "object", "title": "KeylessBuyBody" }, "KeylessCallBody": { "properties": { "from_number": { "type": "string", "title": "From Number", "description": "Your wallet-owned number (E.164, e.g. '+12125551234')" }, "to_number": { "type": "string", "title": "To Number", "description": "Destination phone number in E.164 format" } }, "type": "object", "required": [ "from_number", "to_number" ], "title": "KeylessCallBody" }, "KeylessCreditBody": { "properties": { "amount": { "type": "number", "title": "Amount", "description": "USD credit to buy (1.00–1000.00). 1 USDC ≈ $1.00." } }, "type": "object", "required": [ "amount" ], "title": "KeylessCreditBody" }, "KeylessEventsBody": { "properties": { "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Type" }, "limit": { "anyOf": [ { "type": "integer", "maximum": 200.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Limit" }, "lease_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lease Token" } }, "type": "object", "title": "KeylessEventsBody", "description": "Optional POST body for polling events (GET works identically)." }, "KeylessListBody": { "properties": { "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number", "description": "Filter to one owned number" }, "lease_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lease Token", "description": "lease_... token (free auth alternative)" } }, "type": "object", "title": "KeylessListBody", "description": "Optional POST body for listing numbers (GET works identically)." }, "KeylessRenewBody": { "properties": { "phone_number": { "type": "string", "title": "Phone Number", "description": "Your wallet-owned number to renew (E.164)" } }, "type": "object", "required": [ "phone_number" ], "title": "KeylessRenewBody" }, "KeylessTranscriptBody": { "properties": { "lease_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lease Token" } }, "type": "object", "title": "KeylessTranscriptBody", "description": "Optional POST body for transcripts (GET works identically)." }, "KeylessWebhookBody": { "properties": { "phone_number": { "type": "string", "title": "Phone Number", "description": "Your wallet-owned number whose agent gets the webhook" }, "url": { "type": "string", "title": "Url", "description": "HTTPS URL receiving the agent's events as signed JSON POSTs" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Secret", "description": "HMAC signing secret (auto-generated if omitted)" }, "signature_header": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signature Header", "description": "HMAC header name (default 'X-Webhook-Signature')" } }, "type": "object", "required": [ "phone_number", "url" ], "title": "KeylessWebhookBody" }, "MessageSend": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of the AI agent sending the SMS (e.g. 'agt_abc123')" }, "to_number": { "type": "string", "title": "To Number", "description": "Destination phone number in E.164 format (e.g. '+12125551234')" }, "body": { "type": "string", "title": "Body", "description": "SMS message text content" }, "media_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Url", "description": "URL of media to attach (MMS)" }, "from_number_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From Number Id", "description": "Specific phone number ID to send from; defaults to the agent's assigned number" } }, "type": "object", "required": [ "agent_id", "to_number", "body" ], "title": "MessageSend" }, "NumberProvision": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of the AI agent to assign this phone number to (e.g. 'agt_abc123')" }, "country": { "type": "string", "title": "Country", "description": "Country code for the phone number ('US' or 'CA')", "default": "US" }, "number_type": { "type": "string", "title": "Number Type", "description": "Type of phone number: 'local' or 'tollfree'", "default": "local" }, "area_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Area Code", "description": "Preferred 3-digit US area code (e.g. '212' for NYC, '415' for SF, '310' for LA)" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pattern", "description": "Legacy digit pattern match (prefer area_code instead)" } }, "type": "object", "required": [ "agent_id" ], "title": "NumberProvision" }, "OtpRequest": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "Email address to send the one-time code to. The same email identifies the account for both agents and humans." } }, "type": "object", "required": [ "email" ], "title": "OtpRequest" }, "PayDiscoveryBody": { "properties": { "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Amount", "description": "Top-up amount in USD to advertise requirements for." } }, "type": "object", "title": "PayDiscoveryBody", "description": "Optional POST body for the discovery probe (GET works identically)." }, "TopupRequest": { "properties": { "amount": { "type": "number", "exclusiveMinimum": 0.0, "title": "Amount", "description": "USD amount to top up (e.g. 5.00). 1 USDC ≈ $1.00." } }, "type": "object", "required": [ "amount" ], "title": "TopupRequest" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifyRequest": { "properties": { "email": { "type": "string", "format": "email", "title": "Email", "description": "Email address the one-time code was sent to" }, "otp": { "type": "string", "title": "Otp", "description": "One-time code received via email" } }, "type": "object", "required": [ "email", "otp" ], "title": "VerifyRequest" }, "VoiceSettingUpdate": { "properties": { "voice_id": { "type": "string", "title": "Voice Id", "description": "TTS voice preset name (e.g. 'female-1', 'male-1') or Cartesia voice UUID" } }, "type": "object", "required": [ "voice_id" ], "title": "VoiceSettingUpdate", "description": "Set account-level default voice." }, "WebhookConfig": { "properties": { "url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url", "description": "HTTPS URL that will receive this agent's events as signed JSON POSTs. Setting this replaces any existing webhook for the agent." }, "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of the agent whose events this webhook receives. Each agent may have at most one webhook." }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Secret", "description": "Optional HMAC signing secret. Auto-generated if omitted. Used to verify the signature header on delivered payloads." }, "signature_header": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signature Header", "description": "Header name for the HMAC-SHA256 signature of the raw body. Defaults to 'X-Webhook-Signature' (natively verified by Hermes, OpenClaw, and other agent platforms). Set to 'X-Hub-Signature-256' for GitHub-style verification, or any custom header name your platform expects. Omit to keep the existing value when updating." } }, "type": "object", "required": [ "url", "agent_id" ], "title": "WebhookConfig", "description": "Body for POST /v1/webhooks (create or replace an agent's webhook)." }, "WebhookCreated": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "Agent this webhook is scoped to" }, "url": { "type": "string", "title": "Url", "description": "Configured webhook URL" }, "secret": { "type": "string", "title": "Secret", "description": "Full signing secret. Save it now — it is masked on subsequent reads." }, "signature_header": { "type": "string", "title": "Signature Header", "description": "Header name used for HMAC-SHA256 signature delivery." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "When the webhook was last (re)configured" } }, "type": "object", "required": [ "agent_id", "url", "secret", "signature_header" ], "title": "WebhookCreated", "description": "Returned on POST — exposes the full secret this one time." } }, "securitySchemes": { "API Key or OAuth": { "type": "http", "description": "AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).", "scheme": "bearer", "bearerFormat": "API key (al_live_...)", "x-fern-bearer": { "name": "apiKey", "env": "AGENTLINE_API_KEY" } } } }, "security": [ { "API Key or OAuth": [] } ], "servers": [ { "url": "https://api.agentline.cloud", "description": "Production" } ] }