Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kupe.in/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Voice Agent API

Use this API reference tab to explore every Voice Agent endpoint with Mintlify’s Try it panel (request builder, cURL, and response samples), similar to the standard Mintlify API layout. The live API is served at https://api.kupe.in. The OpenAPI source for this tab is api-reference/kupe-voice-agent.openapi.yaml in the docs repo. Use the left sidebar (OpenAPI tag groups, including Service, Current user, Incoming calls, Call logs, Billing and usage, Wallets, Earnings, Tools and MCP, Post-call analysis, API keys, then Agent Management, Providers, Outbound calls, Knowledge base, Webhooks) to open each operation. Every page includes Try it, request parameters, and response schemas. Tag names avoid & so Mintlify can render every group reliably. For narrative tables (batches, post-analysis rules, etc.), see Platform REST APIs. When you open Try it and click Send, the playground shows the real HTTP response from the API. Static JSON for success bodies is documented in the operation description or via Schemas (not duplicated as a second “example response” in the playground, so the live result stays uncluttered).

​
Endpoints (index)

​
Service

  • GET /health — Public health check (no API key).

​
Current user

  • GET /api/v1/me — Returns user_id, email, optional phone, profile_image_url (from Supabase Auth metadata / identities when present), and auth (bearer or api_key). Requires x-api-key or Authorization: Bearer (dashboard JWT).

​
Incoming calls (PSTN mapping)

  • POST /api/v1/phone/mapping — Attach an agent or workflow to a phone_numbers row so inbound dials hit the right assistant. Use E.164 numbers (+91… India, +1… US/Canada, etc.). See the OpenAPI Incoming calls tag and Voice Agent HTTP API.

​
Agent management

  • GET /api/v1/agents — List agents (array or paginated object).
  • POST /api/v1/agents/simple — Create agent with platform defaults.
  • GET /api/v1/agents/{agent_id} — Get one agent with configs.
  • PUT /api/v1/agents/{agent_id} — Update agent.
  • DELETE /api/v1/agents/{agent_id} — Delete agent.

​
Providers

  • GET /api/v1/providers/model — LLM catalog.
  • GET /api/v1/providers/tts — TTS catalog.
  • GET /api/v1/providers/stt — STT catalog.
  • GET /api/v1/providers/vad — VAD catalog.
  • GET /api/v1/providers/all — All provider tables.
  • GET /api/v1/tts-voices — TTS voice rows (voice_name).

​
Outbound calls

  • POST /api/call/create_call — Outbound PSTN (query params, not JSON). Auth: x-api-key (recommended) or Authorization: Bearer — that user is billed and their phone/agent mappings apply (no user_id query). Response includes request_id, call_session_id, optional telephony_leg_id; telephony_provider is always pstn in JSON.

​
Knowledge base

  • POST /api/v1/files/upload — Upload file (multipart).
  • GET /api/v1/files/supported-formats — Allowed MIME types.
  • GET /api/v1/files/user/me — List files for authenticated user.
  • GET /api/v1/files/{file_id} — File metadata + signed URLs.
  • DELETE /api/v1/files/{file_id} — Delete file everywhere.
  • POST /api/v1/agent-files-mappings/create — Attach file to agent.
  • GET /api/v1/agent-files-mappings/agent/{agent_id} — List mappings for agent.
  • DELETE /api/v1/agent-files-mappings/agent/{agent_id}/file/{upload_file_id} — Detach file from agent.
  • POST /api/v1/search/semantic — Semantic RAG search.
  • POST /api/v1/search/hybrid — Hybrid RAG search.

​
Call logs

  • GET /api/v1/call-analytics — List sessions, paginate (page, page_size), or ?request_id= for one session (includes post-call analysis when allowed).
  • GET /api/v1/call-analytics/export — Export ZIP (request_id or date range).

​
Billing and usage

  • GET /api/v1/billing/usage-records — Usage by call sessions.
  • GET /api/v1/billing/usage/records — Grouped usage rows (time_filter, usage_type, search, pagination).
  • GET /api/v1/billing/usage/summary — Aggregated chart data.
  • GET /api/v1/billing/usage/overview — Totals and this-month usage for the current scope.
  • GET /api/v1/billing/usage/export — Email CSV export (time_filter, from_date/to_date, filters).
  • GET /api/v1/billing/credit-balance — Credit balance summary (reads the unified wallet materialized balance).
  • GET /api/v1/billing/usage/sessions/{session_id} — Cost/usage for one session.
Credits are assigned by admins through the Wallets APIs (no self-serve checkout or payment-gateway webhooks). Grant, cap, and ledger history live under /api/v1/wallets/** — not under /billing. With x-api-key, only GET routes under /api/v1/billing/** are allowed; billing writes are not exposed for API keys. Wallet and earnings mutations require a Bearer session.

​
Wallets (credits, grants, ledger)

  • GET /api/v1/wallets/me — Caller’s wallet summary (balance, monthly cap usage when set).
  • GET /api/v1/wallets/{wallet_id} — Wallet detail: grants, ledger, upcoming expiry (RBAC: own wallet, org scope, or super admin).
  • GET /api/v1/wallets/users — List user wallets (super_admin).
  • GET /api/v1/wallets/orgs — List organization wallets (super_admin).
  • GET /api/v1/wallets/orgs/{org_id}/members — Member wallets in an org (org_admin or super_admin).
  • POST /api/v1/wallets/{wallet_id}/grants — Assign credits (org admin debits org wallet; super admin mints).
  • POST /api/v1/wallets/{wallet_id}/cap — Set or clear monthly spend cap.
  • POST /api/v1/wallets/{wallet_id}/adjust — Super-admin balance adjustment (no grant row).
  • POST /api/v1/orgs/{org_id}/business-model — Set org business model (internal, channel_partner, distributor) — super_admin only.
  • POST /api/v1/orgs/{org_id}/commission — Set commission percentage — super_admin only.
  • POST /api/v1/orgs/{org_id}/markup — Set org markup (reseller pricing) — org_admin of reseller org or super_admin.

​
Earnings (reseller orgs)

  • GET /api/v1/earnings/me — Earnings summary for the caller’s organization when it is a channel_partner or distributor. Query period: day, week, month, year, or all (default month).
  • GET /api/v1/earnings/me/breakdown — Time-bucketed breakdown; same period query.
  • GET /api/v1/earnings/orgs/{org_id} — Earnings for any org (super_admin only); same period query.

​
Feature flags

  • GET /api/v1/feature-flags/me — Boolean product flags for the current user.
  • GET /api/v1/feature-flags/{user_id} / PUT /api/v1/feature-flags/{user_id} — Read or update flags for a user when RBAC allows. PUT accepts boolean flags only; legacy per-user billing markup fields are not supported (use org markup under Wallets).

​
Tools and MCP

  • GET/POST /api/v1/tool-endpoint-defs — HTTP tool definitions.
  • GET/PUT/DELETE /api/v1/tool-endpoint-defs/{tool_id} — One definition.
  • GET/POST /api/v1/tools-mcp-server-defs — MCP server definitions.
  • GET/PUT/DELETE /api/v1/tools-mcp-server-defs/{tool_id} — One MCP def.
  • GET/POST/PATCH /api/v1/agents/{agent_id}/tools — Agent tool mappings.
  • DELETE /api/v1/agents/{agent_id}/tools/{tool_id} — Remove mapping.

​
Post-call analysis

  • GET/POST /api/v1/post-analysis/rules — List or create rules.
  • GET/PUT/DELETE /api/v1/post-analysis/rules/{rule_id} — One rule.
  • POST /api/v1/post-analysis/rules/{rule_id}/duplicate — Duplicate.
  • GET/POST /api/v1/agents/{agent_id}/post-analysis — Read or upsert agent post-analysis config.
  • GET/PUT /api/v1/agents/{agent_id}/post-analysis/attached-rules — List or set attached rule_ids.
  • GET /api/v1/agents/{agent_id}/post-analysis/attached-rule-ids — IDs only.

​
API keys

  • POST /api/v1/api-keys — Create (optional name).
  • GET /api/v1/api-keys/fetch/{user_id} — List active keys.
  • PATCH /api/v1/api-keys/{key_id} — Rename ({ "name": "..." }).
  • DELETE /api/v1/api-keys/{key_id} — Revoke.

​
Webhooks (your server)

Documented callback shapes Kupe can POST when you configure Post analysis → HTTP tool / structured output:
  • POST webhook voiceCallCompleted
  • POST webhook voiceCallError

​
Authentication

​
Kupe API key

Most routes require: 
x-api-key: <YOUR_KUPE_API_KEY>
In the Try it panel, open Authentication, choose KupeApiKey, and paste your key. The OpenAPI spec sets a placeholder via x-default for convenience. Your key is bound to a user in Kupe. For POST /api/call/create_call, x-api-key or Bearer alone determines who is billed and whose lines are used — there is no user_id query on that route. Other routes may still require user_id in the path or body (e.g. file upload).

​
Public routes

  • GET /health — no API key.
  • POST /api/call/create_call — optional Origin allow-list applies. Authenticate with x-api-key or Bearer (user inferred from auth only).
  • POST /api/v1/search/semantic and POST /api/v1/search/hybrid — also excluded from API-key middleware; scope results with agent_id and secure at the edge if the URL is public.

​
Client field mapping

Your fieldKupe
nameagent.name
promptagent_model_config.system_prompt
call_typeInbound: phone → agent in Dashboard. Outbound: create_call + agent_id.
transcriber / model / voicetranscriber_config, agent_model_config, tts_config on create/update agent.
extracted_variablesPost-analysis structured output / HTTP tool (see Webhooks).
context_paramsNot a single global JSON body on create_call yet; pass via telephony or extend backend if needed.

​
Website URL → knowledge

There is no dedicated public REST endpoint that only accepts a website URL for voice-agent RAG. Use file upload or dashboard flows; see Knowledge base endpoints above.

​
Troubleshooting

  • 403 Forbidden: API Key does not have required scopes — Deploy the latest rbac_paths.json and RBAC middleware from milli_ai_backend, and ensure api_key_scopes rows (if any) include the paths you need.
  • 402 on outbound — billing / credits.
  • Provider IDs — Use UUIDs from Providers GET responses, or pass model_name / name strings; the backend resolves by id first, then catalog fields.

​
More reading