Nousdata Inc. Create Agent API

openapi: 3.2.0
info:
  title: Kelam Phone Calls Create Agent 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: Create_agent
paths:
  /api/create_agent:
    post:
      operationId: create_agent
      summary: Provision and deploy a voice agent under your wallet, steered by your…
      tags:
      - Create_agent
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '2.00'
        protocols:
        - x402: {}
      security:
      - siwx: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$
                instructions:
                  type: string
                  minLength: 1
                  maxLength: 30000
                inbound:
                  type: boolean
                outbound:
                  type: boolean
                voice_id:
                  type: string
                  maxLength: 120
                allow_callers:
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    pattern: ^\+[1-9]\d{7,14}$
              required:
              - name
              - instructions
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_id:
                    type: string
                  inbound:
                    type: boolean
                  outbound:
                    type: boolean
                  phone_number:
                    anyOf:
                    - type: string
                    - type: 'null'
                  allowed_callers:
                    type: array
                    items:
                      type: string
                  deployed:
                    type: boolean
                  price_usd:
                    type: string
                required:
                - agent_id
                - inbound
                - outbound
                - phone_number
                - allowed_callers
                - deployed
                - price_usd
                additionalProperties: false
        '402':
          description: Authentication Required
components:
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X