Call2Me Wallet API

openapi: 3.2.0
info:
  title: Call2Me Wallet API
  description: '# Call2Me Voice AI Platform API


    Programmatic interface to build, deploy and operate voice AI agents that can place

    and receive phone calls in real time. Designed to be consumed by humans **and** by

    AI agent frameworks (function-calling LLMs, MCP servers, automation platforms like

    Composio, Pipedream, Zapier, n8n).


    ## What you can do


    - **Place outbound calls** — give an agent a phone number to dial; the AI handles

    the conversation end-to-end and returns a transcript + recording.

    - **Manage AI agents** — create personalities, attach voices, system prompts,

    knowledge bases and post-call actions.

    - **Schedule calls** — one-shot or recurring (cron-like) outbound calls.

    - **Knowledge base (RAG)** — upload documents/URLs so the agent answers from your

    data with reduced hallucination.

    - **Inbound** — provision phone numbers that route to your agents.


    ## Common LLM tool-calling use cases


    | Goal | Endpoint |

    |------|----------|

    | "Call this person and read them this script" | `POST /v1/calls` |

    | "Schedule a follow-up tomorrow at 14:00" | `POST /v1/schedules` |

    | "Get the transcript of last call" | `GET /v1/calls/{id}` |

    | "Add this PDF to the agent''s brain" | `POST /v1/knowledge-base/{id}/sources` |


    ## Authentication


    Every request requires a Bearer token issued from the dashboard:


    ```

    Authorization: Bearer c2m_sk_xxxxxxxxxxxxxxxx

    ```


    Get your API key from the API Keys page.

    Keys are scoped per-workspace and can be rotated/revoked any time.


    ## Rate Limits


    | Plan | Requests/min | Concurrent Calls |

    |------|-------------|------------------|

    | Free | 60 | 1 |

    | Pro | 600 | 10 |

    | Enterprise | Unlimited | Unlimited |


    ## SDKs & Integrations


    - Python SDK

    - Node.js SDK

    - OpenAPI 3.1 spec: `/openapi.json` (use it to generate clients or register the

    service with AI tool platforms)


    ## Support


    - Email: support@call2me.app

    - Docs: https://docs.call2me.app

    - Discord: https://discord.gg/call2me'
  version: 1.0.0
  x-logo:
    url: https://call2me.app/logo.png
    altText: Call2Me Logo
  contact:
    name: Call2Me Support
    url: https://call2me.app/support
    email: support@call2me.app
  license:
    name: Commercial — see Terms of Service
    url: https://call2me.app/terms
  termsOfService: https://call2me.app/terms
servers:
- url: https://api.call2me.app
  description: Production
- url: http://localhost:8000
  description: Local Development
security:
- BearerAuth: []
tags:
- name: Wallet
  description: Wallet balance, transaction history and top-ups. Calls, TTS and STT usage are billed per-minute against this balance.
paths:
  /v1/wallet/balance:
    get:
      tags:
      - Wallet
      summary: Get Balance
      description: 'Get current wallet balance.


        Returns:

        - balance_usd: Current balance in USD

        - has_balance: Whether user has any balance

        - can_proceed: Whether user can use services (balance >= min_balance)

        - min_balance: Minimum balance required

        - margin_percent: Current profit margin percentage'
      operationId: get_balance_v1_wallet_balance_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
  /v1/wallet/summary:
    get:
      tags:
      - Wallet
      summary: Get Summary
      description: 'Get wallet summary with statistics.


        Returns aggregated data:

        - Total topped up

        - Total spent

        - Total margin paid

        - Usage count'
      operationId: get_summary_v1_wallet_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletSummary'
  /v1/wallet/topup:
    post:
      tags:
      - Wallet
      summary: Add Funds
      description: 'Add funds to wallet. Disabled in production.

        Use the payment checkout flow (/v1/payments/checkout) instead.'
      operationId: add_funds_v1_wallet_topup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopupResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/wallet/transactions:
    get:
      tags:
      - Wallet
      summary: Get Transactions
      description: 'Get transaction history.


        Supports pagination and filtering by type.'
      operationId: get_transactions_v1_wallet_transactions_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by type: topup, usage, refund'
          title: Type
        description: 'Filter by type: topup, usage, refund'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/wallet/pricing:
    get:
      tags:
      - Wallet
      summary: Get Pricing
      description: Get current pricing configuration (authenticated).
      operationId: get_pricing_v1_wallet_pricing_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingInfo'
  /v1/wallet/usage-stats:
    get:
      tags:
      - Wallet
      summary: Get Usage Stats
      description: 'Get usage statistics for the last N days.


        Returns spending breakdown by endpoint type (LLM, STT, TTS).'
      operationId: get_usage_stats_v1_wallet_usage_stats_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          description: Number of days to analyze
          default: 30
          title: Days
        description: Number of days to analyze
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__routers__v1__wallet__UsageStats'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/wallet/estimate:
    get:
      tags:
      - Wallet
      summary: Estimate Cost
      description: 'Estimate final cost with margin applied.


        Useful for showing expected cost before an operation.


        Example:

        base_cost=0.10 with 30% margin → final_cost=0.13'
      operationId: estimate_cost_v1_wallet_estimate_get
      parameters:
      - name: base_cost
        in: query
        required: true
        schema:
          type: number
          exclusiveMinimum: 0
          description: Base cost in USD
          title: Base Cost
        description: Base cost in USD
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostEstimate'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/wallet/can-afford:
    get:
      tags:
      - Wallet
      summary: Check Affordability
      description: 'Check if user can afford an operation.


        Applies margin to estimate and checks against balance.'
      operationId: check_affordability_v1_wallet_can_afford_get
      parameters:
      - name: estimated_cost
        in: query
        required: true
        schema:
          type: number
          exclusiveMinimum: 0
          description: Estimated base cost
          title: Estimated Cost
        description: Estimated base cost
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/wallet/analytics:
    get:
      tags:
      - Wallet
      summary: Get Detailed Analytics
      description: 'Get detailed analytics for charts and visualizations.


        Returns:

        - daily: Daily usage breakdown by type (LLM, STT, TTS)

        - models: Usage breakdown by model

        - hourly: Hourly distribution (last 7 days)

        - recent: Last 50 API calls'
      operationId: get_detailed_analytics_v1_wallet_analytics_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          description: Number of days to analyze
          default: 30
          title: Days
        description: Number of days to analyze
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedAnalytics'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Transaction:
      properties:
        id:
          type: integer
          title: Id
        type:
          type: string
          title: Type
        amount_usd:
          type: number
          title: Amount Usd
        cost_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost Usd
        margin_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Margin Usd
        margin_percent:
          anyOf:
          - type: number
          - type: 'null'
          title: Margin Percent
        endpoint_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint Type
        model_used:
          anyOf:
          - type: string
          - type: 'null'
          title: Model Used
        call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Call Id
        balance_before:
          type: number
          title: Balance Before
        balance_after:
          type: number
          title: Balance After
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - id
      - type
      - amount_usd
      - balance_before
      - balance_after
      - created_at
      title: Transaction
      description: Single transaction.
    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
    DetailedAnalytics:
      properties:
        daily:
          items:
            $ref: '#/components/schemas/DailyUsagePoint'
          type: array
          title: Daily
        models:
          items:
            $ref: '#/components/schemas/ModelUsage'
          type: array
          title: Models
        hourly:
          items:
            $ref: '#/components/schemas/HourlyUsage'
          type: array
          title: Hourly
        recent:
          items:
            $ref: '#/components/schemas/RecentCall'
          type: array
          title: Recent
      type: object
      required:
      - daily
      - models
      - hourly
      - recent
      title: DetailedAnalytics
      description: Detailed analytics response.
    PricingInfo:
      properties:
        base_rate_per_min:
          type: number
          title: Base Rate Per Min
        telephony_rate_per_min:
          type: number
          title: Telephony Rate Per Min
        recording_rate_per_min:
          type: number
          title: Recording Rate Per Min
        chat_rate_per_message:
          type: number
          title: Chat Rate Per Message
        min_balance_usd:
          type: number
          title: Min Balance Usd
        signup_bonus_usd:
          type: number
          title: Signup Bonus Usd
        margin_percent:
          type: number
          title: Margin Percent
        realtime_surcharge_per_min:
          type: number
          title: Realtime Surcharge Per Min
          default: 0.25
        interpreter_surcharge_per_min:
          type: number
          title: Interpreter Surcharge Per Min
          default: 0.15
        outbound_surcharge_per_min:
          type: number
          title: Outbound Surcharge Per Min
          default: 0.03
        extension_rate_per_min:
          type: number
          title: Extension Rate Per Min
          default: 0.1
        extension_billing_enabled:
          type: boolean
          title: Extension Billing Enabled
          default: false
      type: object
      required:
      - base_rate_per_min
      - telephony_rate_per_min
      - recording_rate_per_min
      - chat_rate_per_message
      - min_balance_usd
      - signup_bonus_usd
      - margin_percent
      title: PricingInfo
      description: Current pricing configuration — single source of truth.
    RecentCall:
      properties:
        id:
          type: integer
          title: Id
        method:
          type: string
          title: Method
        path:
          type: string
          title: Path
        type:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        tokens_in:
          type: integer
          title: Tokens In
        tokens_out:
          type: integer
          title: Tokens Out
        characters:
          type: integer
          title: Characters
          default: 0
        cost_usd:
          type: number
          title: Cost Usd
        duration_ms:
          type: integer
          title: Duration Ms
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      type: object
      required:
      - id
      - method
      - path
      - type
      - model
      - tokens_in
      - tokens_out
      - cost_usd
      - duration_ms
      - created_at
      title: RecentCall
      description: Recent API call.
    DailyUsagePoint:
      properties:
        date:
          type: string
          title: Date
        llm:
          type: number
          title: Llm
          default: 0
        stt:
          type: number
          title: Stt
          default: 0
        tts:
          type: number
          title: Tts
          default: 0
        total:
          type: number
          title: Total
          default: 0
        requests:
          type: integer
          title: Requests
          default: 0
      type: object
      required:
      - date
      title: DailyUsagePoint
      description: Single day usage data.
    BalanceResponse:
      properties:
        balance_usd:
          type: number
          title: Balance Usd
        has_balance:
          type: boolean
          title: Has Balance
        can_proceed:
          type: boolean
          title: Can Proceed
        min_balance:
          type: number
          title: Min Balance
        margin_percent:
          type: number
          title: Margin Percent
      type: object
      required:
      - balance_usd
      - has_balance
      - can_proceed
      - min_balance
      - margin_percent
      title: BalanceResponse
      description: Current balance info.
    WalletSummary:
      properties:
        current_balance:
          type: number
          title: Current Balance
        total_topup:
          type: number
          title: Total Topup
        total_usage:
          type: number
          title: Total Usage
        total_margin_paid:
          type: number
          title: Total Margin Paid
        usage_count:
          type: integer
          title: Usage Count
        last_usage_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Usage At
        margin_percent:
          type: number
          title: Margin Percent
      type: object
      required:
      - current_balance
      - total_topup
      - total_usage
      - total_margin_paid
      - usage_count
      - last_usage_at
      - margin_percent
      title: WalletSummary
      description: Wallet summary with statistics.
    TopupRequest:
      properties:
        amount_usd:
          type: number
          exclusiveMinimum: 0.0
          title: Amount Usd
          description: Amount to add in USD
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Transaction description
      type: object
      required:
      - amount_usd
      title: TopupRequest
      description: Request to add funds.
    TransactionList:
      properties:
        transactions:
          items:
            $ref: '#/components/schemas/Transaction'
          type: array
          title: Transactions
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - transactions
      - total
      - limit
      - offset
      title: TransactionList
      description: Paginated transaction list.
    ModelUsage:
      properties:
        model:
          type: string
          title: Model
        type:
          type: string
          title: Type
        cost_usd:
          type: number
          title: Cost Usd
        requests:
          type: integer
          title: Requests
      type: object
      required:
      - model
      - type
      - cost_usd
      - requests
      title: ModelUsage
      description: Model usage data.
    HourlyUsage:
      properties:
        hour:
          type: integer
          title: Hour
        cost_usd:
          type: number
          title: Cost Usd
        requests:
          type: integer
          title: Requests
      type: object
      required:
      - hour
      - cost_usd
      - requests
      title: HourlyUsage
      description: Hourly usage data.
    TopupResponse:
      properties:
        success:
          type: boolean
          title: Success
        balance_before:
          type: number
          title: Balance Before
        balance_after:
          type: number
          title: Balance After
        amount_added:
          type: number
          title: Amount Added
        transaction_id:
          type: integer
          title: Transaction Id
      type: object
      required:
      - success
      - balance_before
      - balance_after
      - amount_added
      - transaction_id
      title: TopupResponse
      description: Response after adding funds.
    src__routers__v1__wallet__UsageStats:
      properties:
        period_start:
          type: string
          title: Period Start
        period_end:
          type: string
          title: Period End
        days:
          type: integer
          title: Days
        total_spent:
          type: number
          title: Total Spent
        total_cost:
          type: number
          title: Total Cost
        total_margin:
          type: number
          title: Total Margin
        transaction_count:
          type: integer
          title: Transaction Count
        breakdown:
          additionalProperties: true
          type: object
          title: Breakdown
        by_type:
          items: {}
          type: array
          title: By Type
          default: []
      type: object
      required:
      - period_start
      - period_end
      - days
      - total_spent
      - total_cost
      - total_margin
      - transaction_count
      - breakdown
      title: UsageStats
      description: Usage statistics.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CostEstimate:
      properties:
        base_cost_usd:
          type: number
          title: Base Cost Usd
        margin_usd:
          type: number
          title: Margin Usd
        margin_percent:
          type: number
          title: Margin Percent
        final_cost_usd:
          type: number
          title: Final Cost Usd
      type: object
      required:
      - base_cost_usd
      - margin_usd
      - margin_percent
      - final_cost_usd
      title: CostEstimate
      description: Cost estimate with margin.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app