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

# 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, receive inbound calls, and receive SMS on this number.

Each AI agent can only have ONE active phone number. Costs $2.00/month 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)



## OpenAPI

````yaml /openapi.json post /v1/numbers
openapi: 3.1.0
info:
  title: AgentLine
  description: >-
    AgentLine gives every AI agent a real US phone number and a human-like
    voice. Agents can make and receive calls 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 phone numbers and voice for AI agents. Inbound SMS can be read.
  contact:
    name: AgentLine
    url: https://agentline.cloud
  license:
    name: MIT
    url: https://opensource.org/license/mit
servers:
  - url: https://api.agentline.cloud
    description: Production
security:
  - API Key or OAuth: []
paths:
  /v1/numbers:
    post:
      tags:
        - Numbers
      summary: Provision
      description: >-
        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, receive inbound calls, and receive
        SMS on this number.


        Each AI agent can only have ONE active phone number. Costs $2.00/month
        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)
      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: []
components:
  schemas:
    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 (currently only 'US' is supported)
          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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.