Nousdata Inc. Top Up API

openapi: 3.2.0
info:
  title: Kelam Phone Calls Top Up API
  description: Real phone calls for AI agents in the most realistic human voices, at a fraction of what managed voice-AI platforms charge. Place an outbound call to accomplish a task and get the outcome + transcript back, or provision your own inbound/outbound voice agent under your wallet. From $0.05 + $0.15/min, billed to the second in USDC. No account, no telephony setup.
  version: 1.0.0
  x-guidance: 'The most realistic (human-indistinguishable) voices, at a fraction of what managed voice-AI platforms charge. Paid actions (USDC): - POST /api/place_call { "to": "<E.164>", "task": "<what to do on the call>", optional "agent_id","extract","greeting","language" } —   places an outbound call, blocks until it ends, returns { call_id, status, answered_by, duration_seconds, summary, outcome, transcript, recording_url, price_usd }.   Uses a shared caller agent unless you pass agent_id (one you created). METERED by talk time: $0.05 connect + $0.15/min, billed to the second, capped at $2.00/call; a call that never reaches anyone is free. - POST /api/create_agent { "name","instructions", optional "inbound","outbound","voice_id","allow_callers" } — provisions and deploys   a voice agent under your wallet; returns { agent_id, phone_number, inbound }. $2.00, billed once deployed. Requires wallet auth (SIWX).   IMPORTANT: an inbound agent answers a caller only after you BOTH fund it (top_up) AND allowlist that caller (allow_callers here, or allowlist_number later).   Until both are done it silently rejects every call. Pass allow_callers at create time to allowlist upfront. - POST /api/top_up { "calls": N } — buy N prepaid inbound-call credits at $0.40 each; each answered inbound call spends one. Inbound agents need credits to answer. - POST /api/build { "message", optional "session_id" } — talk to the Kelam builder to design/edit an agent in plain English. Omit session_id to start (the reply carries one); $0.40 per message. Read replies free with build_view. Free actions (wallet-authenticated via SIWX): - POST /api/allowlist_number { "agent_id","caller" } — let a phone number reach your inbound agent. - GET /api/list_agents — your created agents. GET /api/call_status?call_id=... — a call you placed. - GET /api/balance — your remaining inbound-call credits. GET /api/build_view?session_id=... — a builder session transcript. GET /api/health is a free liveness check. Agents you create are isolated per wallet; an inbound agent answers a caller only when it is BOTH funded (top_up) AND that caller is allowlisted (allow_callers / allowlist_number).'
  contact:
    name: Kelam
    url: https://kelam.sh
servers:
- url: https://call.kelam.sh
tags:
- name: Top_up
paths:
  /api/top_up:
    post:
      operationId: top_up
      summary: Fund prepaid inbound-call credits for your agents.
      tags:
      - Top_up
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '0'
          max: '4000.00'
        protocols:
        - x402: {}
      security:
      - siwx: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                calls:
                  type: integer
                  minimum: 1
                  maximum: 10000
              required:
              - calls
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  credited:
                    type: number
                  balance:
                    type: number
                  price_usd:
                    type: string
                required:
                - credited
                - balance
                - price_usd
                additionalProperties: false
        '402':
          description: Authentication Required
components:
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X