> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Outbound Call



## OpenAPI

````yaml /latest.yml POST /agents/calls
openapi: 3.0.1
info:
  title: Cartesia API
  version: 0.0.1
servers:
  - url: https://api.cartesia.ai
    description: Production
security: []
paths:
  /agents/calls:
    post:
      tags:
        - Agents
      summary: Create Outbound Call
      operationId: agents_create-outbound-call
      parameters:
        - $ref: '#/components/parameters/CartesiaVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentOutboundCallRequest'
      responses:
        '200':
          description: Outbound call requests accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentOutboundCallResponse'
        '400':
          description: >-
            Invalid request body, missing required fields, invalid metadata,
            invalid `ringing_timeout_seconds`, unsupported telephony provider,
            or a phone number configuration that cannot place outbound calls.
        '403':
          description: >-
            The phone number does not belong to the same organization as the
            agent.
        '404':
          description: Agent, phone number, or deployment not found.
        '500':
          description: >-
            Outbound calling is temporarily unavailable, or provider setup
            failed.
      security:
        - APIKeyAuth: []
components:
  parameters:
    CartesiaVersionHeader:
      name: Cartesia-Version
      in: header
      description: API version header.
      required: true
      schema:
        type: string
        format: date
        example: '2026-03-01'
        enum:
          - '2026-03-01'
  schemas:
    AgentOutboundCallRequest:
      title: AgentOutboundCallRequest
      type: object
      description: Request body for starting outbound calls from an agent phone number.
      properties:
        from_number_id:
          type: string
          description: >-
            Phone number ID to place calls from. The attached provider handles
            outbound calling for this number.
        agent_id:
          type: string
          description: Agent that handles the outbound calls.
        outbound_calls:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AgentOutboundCallItem'
          description: Per-call destination and metadata configuration.
        ringing_timeout_seconds:
          type: integer
          minimum: 5
          maximum: 80
          description: >-
            Seconds to wait for the callee to answer before giving up. Omit to
            use  the default (60 seconds).
        max_call_duration_minutes:
          type: integer
          description: Optional maximum call duration in minutes.
      required:
        - from_number_id
        - agent_id
        - outbound_calls
    AgentOutboundCallResponse:
      title: AgentOutboundCallResponse
      type: object
      properties:
        calls:
          type: array
          items:
            $ref: '#/components/schemas/AgentOutboundCallItemResponse'
      required:
        - calls
    AgentOutboundCallItem:
      title: AgentOutboundCallItem
      type: object
      description: Destination and metadata for one outbound call.
      properties:
        to_number:
          type: string
          description: >-
            Destination phone number for this outbound call, in E.164 format
            (e.g., `+14155559876`).
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: Custom metadata passed to the agent code deployment.
      required:
        - to_number
    AgentOutboundCallItemResponse:
      title: AgentOutboundCallItemResponse
      type: object
      properties:
        number:
          type: string
          description: >-
            Destination phone number for this outbound call, in E.164 format
            (e.g., `+14155559876`).
        agent_call_id:
          type: string
          description: Agent call ID for tracking logs, audio, and status.
        error:
          nullable: true
          description: >-
            Error for this destination when the provider could not start the
            call.
          type: object
          additionalProperties: true
      required:
        - number
        - agent_call_id
  securitySchemes:
    APIKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Cartesia API key (`sk_car_...`). Get one at
        [play.cartesia.ai/keys](https://play.cartesia.ai/keys).

````