AgentLine x402 Keyless API

openapi: 3.2.0
info:
  title: AgentLine — Prepaid Phone Service for AI Agents x402…
  description: 'AgentLine gives AI agents real US and Canada phone numbers, inbound/outbound voice calls, AI receptionists, transcripts, two-way SMS and live phone events. Use REST or MCP without signup: recharge and save agent_token. This endpoint adds prepaid credit with Base USDC x402 or Tempo MPP. $1 minimum recharge; numbers $3/30 days; connected calls $0.12/min (first-minute minimum, then per-second); SMS $0.02 sent or received. Other endpoints use prepaid balance and do not accept payments.'
  version: 0.3.0
  contact:
    name: AgentLine Support
    email: support@agentline.cloud
    url: https://agentline.cloud
  x-guidance: 'Recharge at GET or POST /v1/billing/topup/x402/pay with optional amount ($1-$1000). Retry the 402 challenge with exactly one Base x402 or Tempo MPP credential. Without signup, save the returned agent_token and use Authorization: Bearer <agent_token> for prepaid service operations and /mcp. Number leases cost $3 for 30 days; connected calls cost $0.12/min and require $0.50 available balance. No other endpoint accepts payments. Existing signup users may send their account Bearer token with recharge to credit that account. See /.well-known/agent-payments.json for configuration, numbers, calls, events and error guidance.'
servers:
- url: https://api.agentline.cloud
tags:
- name: x402 Keyless
paths:
  /v1/x402/numbers/buy:
    post:
      tags:
      - x402 Keyless
      summary: Keyless Buy Number
      description: Buy a US or Canada number for $3 from prepaid balance, with a 30-day lease.
      operationId: x402_keyless_buy_number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeylessBuyBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/numbers:
    get:
      tags:
      - x402 Keyless
      summary: Keyless List Numbers
      description: List wallet-owned numbers using an agent token or existing lease token.
      operationId: x402_keyless_list_numbers
      parameters:
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/KeylessListBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
    post:
      tags:
      - x402 Keyless
      summary: Keyless List Numbers
      description: List wallet-owned numbers using an agent token or existing lease token.
      operationId: x402_keyless_list_numbers_post
      parameters:
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/KeylessListBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/calls:
    post:
      tags:
      - x402 Keyless
      summary: Keyless Make Call
      description: Place a call using agent access. Connected minutes debit prepaid credit.
      operationId: x402_keyless_make_call
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeylessCallBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/calls/{call_id}/transcript:
    get:
      tags:
      - x402 Keyless
      summary: Keyless Call Transcript
      description: Get a call transcript owned by your wallet (agent access token required).
      operationId: x402_keyless_call_transcript
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/KeylessTranscriptBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
    post:
      tags:
      - x402 Keyless
      summary: Keyless Call Transcript
      description: Get a call transcript owned by your wallet (agent access token required).
      operationId: x402_keyless_call_transcript_post
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          type: string
          title: Call Id
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/KeylessTranscriptBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/numbers/renew:
    post:
      tags:
      - x402 Keyless
      summary: Keyless Renew Number
      description: Extend your wallet-owned number's lease by 30 days ($3.00 from prepaid balance).
      operationId: x402_keyless_renew_number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeylessRenewBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/agents:
    get:
      tags:
      - x402 Keyless
      summary: Keyless Get Agent
      description: View your wallet's voice-agent config (agent access token; prepaid balance).
      operationId: x402_keyless_get_agent
      parameters:
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
    patch:
      tags:
      - x402 Keyless
      summary: Keyless Update Agent
      description: 'Update your wallet''s voice-agent tone/voice (agent access token; prepaid balance).


        Only provided fields change — mirrors classic PATCH /v1/agents.

        Applies to all future calls (inbound and outbound).'
      operationId: x402_keyless_update_agent
      parameters:
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeylessAgentUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
    post:
      tags:
      - x402 Keyless
      summary: Keyless Update Agent
      description: 'Update your wallet''s voice-agent tone/voice (agent access token; prepaid balance).


        Only provided fields change — mirrors classic PATCH /v1/agents.

        Applies to all future calls (inbound and outbound).'
      operationId: x402_keyless_update_agent_post
      parameters:
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeylessAgentUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/webhooks:
    get:
      tags:
      - x402 Keyless
      summary: Keyless Get Webhook
      description: View webhook config for your wallet's agent(s) — secrets masked.
      operationId: x402_keyless_get_webhook
      parameters:
      - name: phone_number
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter to one owned number
          title: Phone Number
        description: Filter to one owned number
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
    post:
      tags:
      - x402 Keyless
      summary: Keyless Set Webhook
      description: 'Create or replace the webhook for your number''s agent (agent access token; prepaid balance).


        The URL receives ALL of the agent''s events — call lifecycle,

        SMS, live utterances — as signed JSON POSTs. Full HMAC `secret`

        is returned once; it is masked on later reads.'
      operationId: x402_keyless_set_webhook
      parameters:
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeylessWebhookBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/webhooks/test:
    post:
      tags:
      - x402 Keyless
      summary: Keyless Test Webhook
      description: Fire a signed `webhook.test` event at your agent's webhook.
      operationId: x402_keyless_test_webhook
      parameters:
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeylessWebhookBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
  /v1/x402/events:
    get:
      tags:
      - x402 Keyless
      summary: Keyless Poll Events
      description: 'Poll your wallet''s telephony events (agent access token; prepaid balance).


        Consume-once mailbox like classic GET /v1/events. POST with an

        optional JSON body works identically to GET. For live calls

        prefer the websocket: `ws(s):///v1/events/ws?agent_id=&lease_token=`

        (same socket the classic flow uses; authenticated by lease_token).'
      operationId: x402_keyless_poll_events
      parameters:
      - name: phone_number
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter to one owned number's agent
          title: Phone Number
        description: Filter to one owned number's agent
      - name: event_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: e.g. 'call.completed', 'call.utterance'
          title: Event Type
        description: e.g. 'call.completed', 'call.utterance'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/KeylessEventsBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
    post:
      tags:
      - x402 Keyless
      summary: Keyless Poll Events
      description: 'Poll your wallet''s telephony events (agent access token; prepaid balance).


        Consume-once mailbox like classic GET /v1/events. POST with an

        optional JSON body works identically to GET. For live calls

        prefer the websocket: `ws(s):///v1/events/ws?agent_id=&lease_token=`

        (same socket the classic flow uses; authenticated by lease_token).'
      operationId: x402_keyless_poll_events_post
      parameters:
      - name: phone_number
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter to one owned number's agent
          title: Phone Number
        description: Filter to one owned number's agent
      - name: event_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: e.g. 'call.completed', 'call.utterance'
          title: Event Type
        description: e.g. 'call.completed', 'call.utterance'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: lease_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/KeylessEventsBody'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Agent access token required
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-billing-mode: prepaid_balance
components:
  schemas:
    KeylessListBody:
      properties:
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
          description: Filter to one owned number
        lease_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
          description: agent_... or lease_... access token
      type: object
      title: KeylessListBody
      description: Optional POST body for listing numbers (GET works identically).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    KeylessBuyBody:
      properties:
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
          description: Display name for the voice agent
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
          description: Personality/behavior instructions spoken on ALL calls
        initial_greeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Initial Greeting
          description: Opening line spoken when a call connects
        voice_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Id
          description: TTS voice preset (e.g. 'female-1') or a voice UUID
        transfer_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Transfer Number
          description: Must be the owner phone. Live transfers dial only owner_phone.
        voicemail_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Voicemail Message
          description: Message left if the call goes to voicemail
        owner_phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Owner Phone
          description: Owner's E.164 phone. Calls from it enter task mode, and it is the only live-call transfer destination.
        country:
          type: string
          title: Country
          description: 'Country code: ''US'' or ''CA'''
          default: US
        number_type:
          type: string
          title: Number Type
          description: '''local'' or ''tollfree'''
          default: local
        area_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Area Code
          description: Preferred 3-digit US or Canada area code
      type: object
      title: KeylessBuyBody
    KeylessEventsBody:
      properties:
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
        event_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Type
        limit:
          anyOf:
          - type: integer
            maximum: 200.0
            minimum: 1.0
          - type: 'null'
          title: Limit
        lease_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      type: object
      title: KeylessEventsBody
      description: Optional POST body for polling events (GET works identically).
    KeylessWebhookBody:
      properties:
        phone_number:
          type: string
          title: Phone Number
          description: Your wallet-owned number whose agent gets the webhook
        url:
          type: string
          title: Url
          description: HTTPS URL receiving the agent's events as signed JSON POSTs
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
          description: HMAC signing secret (auto-generated if omitted)
        signature_header:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature Header
          description: HMAC header name (default 'X-Webhook-Signature')
      type: object
      required:
      - phone_number
      - url
      title: KeylessWebhookBody
    KeylessCallBody:
      properties:
        from_number:
          type: string
          title: From Number
          description: Your wallet-owned number (E.164, e.g. '+12125551234')
        to_number:
          type: string
          title: To Number
          description: Destination phone number in E.164 format
        lease_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
          description: agent_... token from recharge or existing lease_... token. Calls bill prepaid credit.
      type: object
      required:
      - from_number
      - to_number
      title: KeylessCallBody
    KeylessAgentUpdate:
      properties:
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
        initial_greeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Initial Greeting
        voice_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Id
        transfer_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Transfer Number
        voicemail_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Voicemail Message
        owner_phone:
          anyOf:
          - type: string
          - type: 'null'
          title: Owner Phone
      type: object
      title: KeylessAgentUpdate
      description: Partial agent update — only provided fields change (mirrors classic PATCH /v1/agents).
    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
    KeylessTranscriptBody:
      properties:
        lease_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Lease Token
      type: object
      title: KeylessTranscriptBody
      description: Optional POST body for transcripts (GET works identically).
    KeylessRenewBody:
      properties:
        phone_number:
          type: string
          title: Phone Number
          description: Your wallet-owned number to renew (E.164)
      type: object
      required:
      - phone_number
      title: KeylessRenewBody
  securitySchemes:
    API_Key_or_OAuth:
      type: http
      description: 'Pass an API key (`Authorization: Bearer al_live_xxx`) or an OAuth access token issued via the Claude.ai / MCP connect flow. Wallet agents use the payment-issued `agent_token` with the same Bearer header, without signup.'
      scheme: bearer
x-service-info:
  name: AgentLine - AI Phone Service
  description: 'AgentLine gives AI agents real US and Canada phone numbers, inbound/outbound voice calls, AI receptionists, transcripts, two-way SMS and live phone events. Use REST or MCP without signup: recharge and save agent_token. This endpoint adds prepaid credit with Base USDC x402 or Tempo MPP. $1 minimum recharge; numbers $3/30 days; connected calls $0.12/min (first-minute minimum, then per-second); SMS $0.02 sent or received. Other endpoints use prepaid balance and do not accept payments.'
  url: https://agentline.cloud
  iconUrl: https://api.agentline.cloud/favicon.png