AgentLine Usage API

openapi: 3.2.0
info:
  title: AgentLine — Prepaid Phone Service for AI Agents Usage API
  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: Usage
paths:
  /v1/usage:
    get:
      tags:
      - Usage
      summary: Get Usage
      description: 'Get usage statistics for your AI telephony account.


        Returns a summary of call volume, message counts, active phone

        numbers, current balance, and estimated costs for the requested

        billing period (''current_month'' by default; also ''last_month'',

        ''all_time'', or an explicit ''YYYY-MM'').'
      operationId: get_usage_stats
      security:
      - API Key or OAuth: []
      parameters:
      - name: period
        in: query
        required: false
        schema:
          type: string
          description: 'Billing period: ''current_month'', ''last_month'', ''all_time'', or ''YYYY-MM'''
          default: current_month
          title: Period
        description: 'Billing period: ''current_month'', ''last_month'', ''all_time'', or ''YYYY-MM'''
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/usage/balance:
    get:
      tags:
      - Usage
      summary: Get Balance
      description: 'Get the current AI telephony account balance.


        Returns your available balance in USD. This balance is used to

        pay for AI agent phone calls, phone number provisioning, and inbound SMS.'
      operationId: get_usage_balance
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
  /v1/usage/transactions:
    get:
      tags:
      - Usage
      summary: Get Transactions
      description: 'Get billing transaction history for your AI telephony account.


        Returns a paginated list of all charges and credits including

        call charges, number provisioning fees, inbound SMS charges, top-ups, and refunds.

        Most recent transactions are returned first.'
      operationId: get_billing_transactions
      security:
      - API Key or OAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of transactions to return (1-200)
          default: 50
          title: Limit
        description: Maximum number of transactions to return (1-200)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of transactions to skip for pagination
          default: 0
          title: Offset
        description: Number of transactions to skip for pagination
      - name: txn_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by transaction type: ''call_charge'', ''number_provision'', ''inbound_sms_charge'', ''topup'', or ''refund'''
          title: Txn Type
        description: 'Filter by transaction type: ''call_charge'', ''number_provision'', ''inbound_sms_charge'', ''topup'', or ''refund'''
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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: '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