AgentLine Numbers API

openapi: 3.2.0
info:
  title: Agentline Cloud Numbers API
  version: 0.3.0
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  description: 'Operations tagged Numbers 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: Numbers
paths:
  /v1/numbers:
    get:
      tags:
      - Numbers
      summary: List Numbers
      description: '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.'
      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.


        Buys a real +1 number from the carrier, attaches it to the agent and

        uses an included subscription number, or charges $3.00 to the wallet. Once attached, the agent can make

        outbound calls and answers inbound calls on this number. Not idempotent:

        every successful call buys and charges for another number.


        Prerequisites: an agent from create_agent with no active number (each

        agent has at most one; a second purchase returns HTTP 409), plus a remaining

        subscription number allowance or $3.00 in the wallet

        (HTTP 402 otherwise; see get_account_balance).


        Returns the number''s id (num_..., used by release_phone_number and as

        from_number_id), phone_number, country, number_type, status, cost,

        balance_remaining and a private number card link (card_url,

        card_image_url, card_url_expires_at). If the account has an owner email,

        the 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
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/numbers/{number_id}:
    get:
      tags:
      - Numbers
      summary: Get Number
      description: 'Get details of a specific phone number.


        Returns the phone number, its assigned AI agent, provider ID,

        country, 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
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/numbers/{number_id}/reassign:
    patch:
      tags:
      - Numbers
      summary: Reassign Number
      description: 'Reassign a phone number to a different AI agent.


        Moves an existing phone number from one AI agent to another.

        The target agent must not already have an active number assigned.

        The 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
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/numbers/{number_id}/release:
    post:
      tags:
      - Numbers
      summary: Release Phone Number
      description: 'Permanently release a phone number that is not in use.


        Destructive: 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
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/numbers/attach:
    post:
      tags:
      - Numbers
      summary: Attach Existing Number
      description: 'Manually attach a number that was bought outside this account.

        Each agent can only have ONE active number.


        Query params:

        - phone_number: E.164 format (e.g. "+12125551234")

        - agent_id: agent to attach to

        - country: "US" (default) or "CA" — both are +1, so say which'
      operationId: attach_existing_number
      security:
      - API Key or OAuth: []
      parameters:
      - name: phone_number
        in: query
        required: true
        schema:
          type: string
          title: Phone Number
      - name: agent_id
        in: query
        required: true
        schema:
          type: string
          title: Agent Id
      - name: country
        in: query
        required: false
        schema:
          type: string
          default: US
          title: Country
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.agentline.cloud
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 ('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
    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
    NumberProvision_2:
      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: '''local'' for a number in a geographic area code, or ''tollfree'' for a toll-free 8xx number'
          default: local
        area_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Area Code
          description: For local numbers, the area code the number should be in, written as 3 digits (US e.g. '212' NYC, '415' SF; Canada e.g. '416' Toronto, '604' Vancouver, '514' Montreal); other values make the purchase fail. For tollfree, a prefix such as '800' or '888' narrows the search and other values are ignored. Omit to take any available number.
        pattern:
          anyOf:
          - type: string
          - type: 'null'
          title: Pattern
          description: 'Legacy search: digits the local number must contain, e.g. ''555''. Used only for local numbers when area_code is omitted; prefer area_code.'
      type: object
      required:
      - agent_id
      title: NumberProvision
  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