io.github.AgentLineHQ/agentline

list_agents

List Agents List all AI voice agents configured on your account. Returns every AI phone agent you've created, including their system prompts, voice settings, and associated phone numbers. Useful for checking which agents are ready to make or receive calls. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ```

No parameters.

create_agent

Create Agent Create a new AI voice agent for telephony. Sets up a new AI phone agent with a custom system prompt, voice, and greeting. Once created, buy a phone number and attach it to this agent so it can make and receive calls autonomously. Fields: - name: Display name for the agent - system_prompt: Instructions that define the agent's personality and behavior on calls - initial_greeting: What the AI agent says when the call connects - voice_id: TTS voice preset (e.g. "female-1") or Cartesia UUID - transfer_number: Phone number to transfer calls to (e.g. a human operator) - voicemail_message: Message the agent leaves if the call goes to voicemail ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "id": "Id", "account_id": "Account Id", "name": "Name", "created_at": "2023-01-01T00:00:00Z" } ``` **Output Schema:** ```json { "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": { "title": "System Prompt", "description": "Default system prompt for all calls (can be overridden per-call)" }, "initial_greeting": { "title": "Initial Greeting", "description": "Default greeting for all calls (can be overridden per-call)" }, "voice_id": { "title": "Voice Id", "description": "TTS voice preset or Cartesia UUID" }, "transfer_number": { "title": "Transfer Number", "description": "Phone number for call transfers" }, "voicemail_message": { "title": "Voicemail Message", "description": "Message left on voicemail" }, "owner_phone": { "title": "Owner Phone", "description": "Owner's phone number for task mode" }, "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" } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_agent

Get Agent Get details of a specific AI voice agent. Returns the agent's full configuration including system prompt, voice settings, greeting, and transfer number. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

update_agent

Update Agent Update an AI voice agent's configuration. Modify any combination of the agent's settings: system prompt, voice, greeting, transfer number, or voicemail message. Changes take effect on the next call the agent handles. Only include the fields you want to change — unset fields are preserved. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

delete_agent

Delete Agent Delete an AI voice agent. Permanently removes the agent and detaches any phone numbers assigned to it. Detached numbers remain active on your account and can be reassigned to another agent. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

list_phone_numbers

List Numbers List all phone numbers provisioned on your account. Returns every phone number you've bought for your AI agents, including which agent each number is assigned to, the number's status (active/released), and country. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ```

No parameters.

buy_phone_number

Provision Buy a US phone number for your AI agent. Searches for and purchases a real US phone number from the telephony provider, then attaches it to the specified AI agent. Once attached, the agent can make outbound calls and receive inbound calls on this number. Each AI agent can only have ONE active phone number. Costs $2.00 per number. Request body: - agent_id: str (required) — the AI agent to assign this number to - country: str (must be "US") - number_type: "local" | "tollfree" - area_code: preferred 3-digit US area code (e.g. "212" for NYC, "415" for SF) ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

list_messages

List Messages List SMS messages sent and received by your AI agents. Returns message history with optional filters by AI agent or conversation. Each entry includes direction (inbound/outbound), phone numbers, message body, and delivery status. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

make_outbound_call

Create Call Make an outbound phone call from your AI agent. Initiates a real phone call from the AI agent's phone number to the specified destination. The agent uses its configured system prompt, voice, and greeting to conduct the conversation autonomously. The AI agent handles the entire call — speech-to-text, LLM reasoning, and text-to-speech — in real time. The call transcript is saved automatically and can be retrieved via GET /v1/calls/{call_id}/transcript. Request body: - agent_id: the AI agent making the call - to_number: destination phone number in E.164 format (e.g. "+12125551234") - from_number_id: (optional) specific number to call from - system_prompt: (optional) override the agent's default prompt for this call - initial_greeting: (optional) override the agent's greeting for this call - voice_id: (optional) override the voice for this call ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

list_calls

List Calls List voice calls made by your AI agents. Returns call history with optional filters by agent or status. Each entry includes direction (inbound/outbound), duration, phone numbers, and current status. Filters: - agent_id: only calls for a specific AI agent - status: "initiated", "in-progress", "completed", or "failed" ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_call_details

Get Call Get full details of a specific voice call. Returns the call's metadata including direction, phone numbers, status, duration, AI agent configuration used, and the full conversation transcript between the AI agent and the caller. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_call_transcript

Get Transcript Get the full conversation transcript for a call. Returns the complete speech-to-text transcript of the phone call, with each turn labeled by role ("human" for the caller, "assistant" for the AI agent). Useful for reviewing what was said on the call, extracting information, or auditing AI agent behavior. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

hangup_call

Hangup Call Hang up an active phone call. Programmatically terminates an in-progress voice call. Use this when the AI agent needs to end the conversation, or to force-stop a call that is no longer needed. The call's final transcript and billing are processed automatically after hangup. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

poll_events

List Events Poll for telephony events from your AI agents. Returns pending events such as call completions, transcripts, and failures. Events are consumed on retrieval (one-time read) — once polled, they are automatically deleted from the mailbox. Your AI agent should call this endpoint periodically to receive notifications about completed calls and their transcripts. Filters: - agent_id: only events for a specific AI agent - event_type: e.g. "call.completed", "call.failed" ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

peek_events

Peek Events Peek at pending telephony events without consuming them. Returns a preview of queued events (call completions, transcripts) without removing them from the mailbox. Useful for checking if there are events to process before committing to retrieve them. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

get_account_balance

Get Balance Get your AI telephony account balance and rate card. Returns the current balance, currency, billing rates for calls and phone numbers, and how many call minutes or phone numbers the balance can cover. Use this to check affordability before making calls or buying numbers for your AI agents. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ```

No parameters.

get_expenditure_breakdown

Get Expenditure Get a detailed expenditure breakdown for AI telephony usage. Shows total spend split by category (voice calls, phone number provisioning, top-ups, refunds) with counts and averages. Useful for tracking how much your AI agents are spending on phone calls and phone numbers. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

list_available_voices

Get Available Voices List all available voice presets for AI phone agents. Returns named TTS (text-to-speech) voice presets that can be used when configuring AI agents or making phone calls. Each voice defines how your AI agent sounds on the phone. You can use a preset name (e.g. "female-1", "male-1") or pass any valid Cartesia voice UUID directly as a voice_id. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ```

No parameters.

get_account_voice

Get Account Voice Get the current account-level default voice for AI phone agents. Returns which voice is used for all AI agents under this account unless overridden at the agent level or per-call. Controls how your AI agents sound during phone conversations. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ```

No parameters.

reset_account_voice

Reset Account Voice Reset account voice to the system default. Removes the account-level voice override so all AI agents fall back to the system default voice during phone calls (unless they have their own voice_id configured). ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ```

No parameters.

set_account_voice

Update Account Voice Set the account-level default voice for AI phone agents. This becomes the default voice for ALL AI agents under this account, controlling how they sound on phone calls. Individual agents or specific calls can still override this setting. Voice resolution priority: 1. Per-call voice_id (POST /v1/calls) 2. Agent voice_id (PATCH /v1/agents/{id}) 3. Account default (this endpoint) ← you are here 4. System default (Supportive Male) Accepts: - A preset name: "female-1", "female-2", "female-3", "male-1", "male-2", "male-3" - A Cartesia voice UUID: "f786b574-daa5-4673-aa0c-cbe3e8534c02" ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

submit_feedback

Submit Feedback Submit feedback, report a bug, or request a feature. Use this endpoint to tell the AgentLine team about anything you encounter while using the platform: - **bug** — something is broken or not working as expected - **feature_request** — you wish a capability existed - **difficulty** — something was hard or confusing to use - **feedback** — general comments, suggestions, or praise Your feedback is reviewed by the team. Include as much detail as possible — for bugs, describe what you expected vs. what happened and any steps to reproduce it. You can check back on submitted feedback via GET /v1/feedback to see its status. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "id": "Id", "account_id": "Account Id", "category": "Category", "message": "Message", "severity": "Severity", "status": "Status", "created_at": "2023-01-01T00:00:00Z" } ``` **Output Schema:** ```json { "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": { "title": "Subject", "description": "Short summary title" }, "severity": { "type": "string", "title": "Severity", "description": "Impact level: 'low', 'normal', 'high', or 'critical'" }, "agent_id": { "title": "Agent Id", "description": "Related AI agent ID, if any" }, "contact_email": { "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" } ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```

list_feedback

List Feedback List feedback you have submitted. Returns your feedback history with optional filters by category (bug, feature_request, difficulty, feedback) and status (open, acknowledged, in_progress, resolved, closed). Useful for tracking progress on bugs or feature requests you reported. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Output Schema:** ```json {} ``` **422**: Validation Error Content-Type: application/json **Example Response:** ```json { "detail": [ { "loc": [], "msg": "Message", "type": "Error Type", "ctx": {} } ] } ``` **Output Schema:** ```json { "properties": { "detail": { "items": { "properties": { "loc": { "items": {}, "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" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } ```