Nousdata Inc. Allowlist Number API

openapi: 3.2.0
info:
  title: Kelam Phone Calls Allowlist Number 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: Allowlist_number
paths:
  /api/allowlist_number:
    post:
      operationId: allowlist_number
      summary: Allow a phone number to reach one of your inbound agents.
      tags:
      - Allowlist_number
      security:
      - siwx: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
                  maxLength: 120
                caller:
                  type: string
                  pattern: ^\+[1-9]\d{7,14}$
              required:
              - agent_id
              - caller
      responses:
        '200':
          description: Successful response
        '402':
          description: Authentication Required
components:
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X