AgentLine Agents API

openapi: 3.2.0
info:
  title: Agentline Cloud Agents API
  version: 0.3.0
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  description: 'Operations tagged Agents across 2 of this provider''s published API definitions: agentline.cloud_openapi.json, agentline-cloud-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentline.cloud
  description: Production
tags:
- name: Agents
paths:
  /v1/agents:
    get:
      tags:
      - Agents
      summary: List Agents
      description: '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.'
      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.


        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: Must be the owner phone. Live calls transfer only to owner_phone.

        - voicemail_message: Message the agent leaves if the call goes to voicemail

        - 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
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/agents/{agent_id}:
    get:
      tags:
      - Agents
      summary: Get Agent
      description: 'Get details of a specific AI voice agent.


        Returns the agent''s full configuration including system prompt,

        voice 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.


        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.'
      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.


        Permanently removes the agent, its calls, messages, and conversations,

        and detaches any phone numbers assigned to it. Detached numbers remain

        active 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
    servers:
    - url: https://api.agentline.cloud
      description: Production
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    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
    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
    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
    AgentUpdate_2:
      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 voice: a voice_id from list_available_voices or a legacy preset name'
        speech_language:
          anyOf:
          - type: string
          - type: 'null'
          title: Speech Language
          description: BCP-47 locale the agent listens and speaks in, e.g. 'en-US', 'hi-IN'. 'auto' (or unset) keeps multilingual auto-detection. Allowed values are listed under 'languages' by list_available_voices. Send null to go back to auto-detection.
        speaking_speed:
          anyOf:
          - type: number
            maximum: 1.5
            minimum: 0.6
          - type: 'null'
          title: Speaking Speed
          description: Speaking pace multiplier from 0.6 (slower) to 1.5 (faster); 1.0 is the voice's natural pace. Send null to go back to 1.0.
        transfer_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Transfer Number
          description: Number a live call is transferred to. Only the owner phone is allowed, so send the same E.164 number as owner_phone (current or in this request); setting owner_phone updates it automatically.
        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
    AgentCreate_2:
      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: 'Voice the agent speaks with: a voice_id from list_available_voices or a legacy preset name (e.g. ''female-1''); defaults to the system voice if not set'
        speech_language:
          anyOf:
          - type: string
          - type: 'null'
          title: Speech Language
          description: BCP-47 locale the agent listens and speaks in, e.g. 'en-US', 'hi-IN'. 'auto' (or unset) keeps multilingual auto-detection. Allowed values are listed under 'languages' by list_available_voices.
        speaking_speed:
          anyOf:
          - type: number
            maximum: 1.5
            minimum: 0.6
          - type: 'null'
          title: Speaking Speed
          description: Speaking pace multiplier from 0.6 (slower) to 1.5 (faster); 1.0 is the voice's natural pace.
        transfer_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Transfer Number
          description: Number a live call is transferred to. Only the owner phone is allowed, so leave it out or send the same E.164 number as owner_phone; setting owner_phone fills it in.
        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
    AgentOut_2:
      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: Voice the agent speaks with (voice_id or legacy preset name)
        speech_language:
          anyOf:
          - type: string
          - type: 'null'
          title: Speech Language
          description: Pinned speech locale, or null for multilingual auto-detection
        speaking_speed:
          anyOf:
          - type: number
          - type: 'null'
          title: Speaking Speed
          description: Speaking pace multiplier; null means the natural pace (1.0)
        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
  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
x-refined-from:
- agentline.cloud_openapi.json
- agentline-cloud-openapi.json