Platform REST APIs - Kupe AI Documentation

All routes below are under your API host (for example https://api.kupe.in) unless noted. Authenticate with Authorization: Bearer <supabase_jwt> from the dashboard, or x-api-key: <kupe_api_key> for server integrations.

Tools — custom HTTP tools and MCP

HTTP tool definitions (CRUD)

Base path: /api/v1/tool-endpoint-defs

Method	Path	Purpose
`POST`	`""`	Create a tool definition (URL, schemas, method).
`GET`	`""`	List your tool definitions.
`GET`	`/{id}`	Get one definition.
`PUT`	`/{id}`	Update.
`DELETE`	`/{id}`	Delete.

MCP server tool definitions (CRUD)

Base path: /api/v1/tools-mcp-server-defs Same idea as HTTP tools: POST / GET / GET /{id} / PUT / DELETE for MCP-backed tools.

Attach tools to an agent

Base path: /api/v1/agents

Method	Path	Purpose
`GET`	`/{agent_id}/tools`	List tools linked to the agent.
`POST`	`/{agent_id}/tools`	Add tool mappings (body: list of tool config objects).
`PATCH`	`/{agent_id}/tools`	Replace/update tool configuration.
`DELETE`	`/{agent_id}/tools/{tool_id}`	Remove one tool mapping.

Create tools first (tool-endpoint-defs or tools-mcp-server-defs), then reference their IDs in the agent tools payload when calling POST / PATCH on /{agent_id}/tools.

Post-call analysis — rules and agent mapping

User-scoped rules (CRUD)

Base path: /api/v1/post-analysis

Method	Path	Purpose
`GET`	`/rules`	List rules.
`POST`	`/rules`	Create rule (JSON body).
`GET`	`/rules/{rule_id}`	Get one rule.
`PUT`	`/rules/{rule_id}`	Update.
`DELETE`	`/rules/{rule_id}`	Delete.
`POST`	`/rules/{rule_id}/duplicate`	Duplicate.

Map rules to an agent

Base path: /api/v1/agents/{agent_id}

Method	Path	Purpose
`POST`	`/post-analysis`	Upsert post-call analysis config for the agent (body includes `agent_id` aligned with path).
`GET`	`/post-analysis`	Get post-call analysis rows for the agent.
`GET`	`/post-analysis/attached-rules`	Rules attached to the agent.
`GET`	`/post-analysis/attached-rule-ids`	IDs only.
`PUT`	`/post-analysis/attached-rules`	Set attached rules: body `{ "rule_ids": ["uuid", ...] }`.

Outbound — batch campaigns (end-to-end API)

Base path: /api/v1/batch-call Requires the outbound feature flag on your account. Authenticate with x-api-key or Bearer on every route below (except Twilio /status-callback, which is called by the carrier).

Prerequisites

GET /api/v1/phone — list provisioned lines; note each row’s id (caller_phone_id).
GET /api/v1/agents — note your agent id, or use a workflow id instead.
In the agent system prompt, use variables like {{name}} that match variable_names on the batch.

End-to-end flow

Step	Method	Path	Purpose
1	`POST`	`/create`	Create batch: `agent_id` or `workflow_id`, `caller_phone_id`, `batch_name`, `variable_names`, `batch_size`.
2a	`POST`	`/upload-json/{batch_id}`	Add targets as JSON (`records[]` with `to_phonenumber` + variable keys).
2b	`POST`	`/upload/{batch_id}`	Or upload CSV (`multipart/form-data`, column `to_phonenumber` + variables).
2c	`POST`	`/{batch_id}/data/upsert`	Or upsert rows one-by-one / in bulk (`items[]` with optional `id` to update).
3	`GET`	`/{batch_id}/data`	Verify recipients (optional `?status=not_started`).
4	`POST`	`/start/{batch_id}`	Launch campaign — dials up to `batch_size` numbers at a time.
5	`GET`	`/{batch_id}/status`	Poll batch `status` + `status_counts` (not_started, calling, completed, failed, no_answer).
5	`GET`	`/{batch_id}/data`	Poll per-number status and `error_message`.

Batch-level status: not_started → in_progress (after launch) → completed (all rows terminal). Recipient status: not_started → calling → completed | failed | no_answer.

All routes

Method	Path	Purpose
`POST`	`/create`	Create batch (`user_id` optional — defaults to authenticated user).
`GET`	`/me`	List batches for the authenticated user.
`GET`	`/{batch_id}`	Batch metadata only.
`GET`	`/{batch_id}/status`	Metadata + aggregated status counts.
`GET`	`/{batch_id}/data`	All target numbers (optional `?status=`).
`POST`	`/{batch_id}/data/upsert`	Insert/update recipients (before launch).
`PATCH`	`/{batch_id}/variables`	Update `variable_names` (before launch).
`DELETE`	`/{batch_id}/data/{item_id}`	Remove one recipient (before launch).
`POST`	`/upload/{batch_id}`	CSV upload (`to_phonenumber` + variable columns).
`POST`	`/upload-json/{batch_id}`	JSON bulk upload.
`POST`	`/start/{batch_id}`	Launch campaign.
`DELETE`	`/{batch_id}`	Delete batch and all recipients.
`GET`	`/browse`	Paginated list (super-admin scoping query params).
`GET`	`/user/{user_id}`	List batches for a user (self or super-admin).
`POST`	`/status-callback`	Twilio status webhook (internal; no API key).

Example: create → add numbers → launch → poll

export KUPE_API_KEY="your_key"
export BASE="https://api.kupe.in"

# 1. Create batch
BATCH=$(curl -s -X POST "$BASE/api/v1/batch-call/create" \
  -H "x-api-key: $KUPE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_UUID",
    "caller_phone_id": "YOUR_PHONE_NUMBER_UUID",
    "batch_name": "API demo",
    "variable_names": ["name"],
    "batch_size": 3
  }' | jq -r '.data.id')

# 2. Add targets
curl -s -X POST "$BASE/api/v1/batch-call/upload-json/$BATCH" \
  -H "x-api-key: $KUPE_API_KEY" -H "Content-Type: application/json" \
  -d '{"records":[{"to_phonenumber":"+919876543210","name":"Ada"}]}'

# 3. Launch
curl -s -X POST "$BASE/api/v1/batch-call/start/$BATCH" \
  -H "x-api-key: $KUPE_API_KEY"

# 4. Poll progress
curl -s "$BASE/api/v1/batch-call/$BATCH/status" -H "x-api-key: $KUPE_API_KEY" | jq .
curl -s "$BASE/api/v1/batch-call/$BATCH/data?status=calling" -H "x-api-key: $KUPE_API_KEY" | jq .

Interactive request/response shapes: Voice Agent API OpenAPI tab → Batch calling (kupe-voice-agent.openapi.yaml).

Call logs — list, pagination, single session, post-call data

Base path: /api/v1/call-analytics

Query / path	Behavior
`GET /call-analytics?request_id=<id>`	Single call by `request_id`. Response includes session fields; when HIPAA-style, transcript/recording/post-call fields may be stripped.
`GET /call-analytics?page=&page_size=`	Paginated list (server-side). Use `filter` (alias) for search on request id / call type.
`GET /call-analytics` (no page)	Full list for dashboards (subject to feature flags and scope).
Super-admin scoping	Optional query params: `scope`, `organization_ids`, `owner_user_ids`, `platform_roles`, etc., as supported by your deployment.

Post-call analysis fields (when not redacted) appear on the session object, e.g. post_call_analysis_results and related keys returned by the service layer.

Export (ZIP, optional date range)

GET /call-analytics/export — supports request_id for a single downloadable export, or bulk export with start_date / end_date (YYYY-MM-DD) and email delivery for large ranges.

Billing and usage (usage, cost, credit summary)

Base path: /api/v1/billing Typical read endpoints (also available under /billing/... where the router is mounted without the /api/v1 prefix):

GET path	Purpose
`/usage-records`	Usage organized by call sessions.
`/usage/records`	Service usage records with filters (`time_filter`, `usage_type`, search, `limit`/`offset`).
`/usage/summary`	Aggregated summary for charts.
`/usage/overview`	Totals and this-month usage for the authenticated scope.
`/usage/sessions/{session_id}`	Usage and cost for one session.
`/usage/export`	Export usage (e.g. CSV by email; filters align with `/usage/records`).
`/credit-balance`	Credit balance summary — backed by the unified wallets row (`available_balance_usd`, monthly cap fields when set).

Removed from the product (do not call): self-serve pricing plans, payment checkout, Razorpay webhooks, /balance-history (legacy ledger). Historical balance movements and grants are returned from GET /api/v1/wallets/{wallet_id} (see Wallets below). Other GET /api/v1/billing/** routes your deployment may expose (e.g. forex quotes, service pricing) remain read-only catalog helpers where implemented.

API key vs session (important)

When you authenticate with x-api-key, only GET (and HEAD/OPTIONS) are allowed on /api/v1/billing/**. There is no API-key billing write surface. Wallets and earnings live under /api/v1/wallets/** and /api/v1/earnings/**. Assigning credits, caps, org business model, markup, and commission are POST operations and require a Bearer (session) token with the appropriate org or super-admin role.

Feature flags

Base path: /api/v1/feature-flags

Method	Path	Purpose
`GET`	`/me`	Boolean feature flags for the signed-in user.
`GET`	`/{user_id}`	Read another user’s flags when RBAC allows.
`PUT`	`/{user_id}`	Update boolean flags only. Per-user billing markup fields are no longer accepted here — retail markup is configured at the organization via `POST /api/v1/orgs/{org_id}/markup` (see Wallets).

Wallets (credits, grants, ledger, org business model)

Base path: /api/v1/wallets (plus org-scoped helpers under /api/v1/orgs for business model / commission / markup).

Method	Path	Purpose
`GET`	`/wallets/me`	Current user’s wallet summary (materialized balance, monthly cap usage when configured).
`GET`	`/wallets/{wallet_id}`	Wallet detail: grants, append-only ledger, upcoming expiry (access controlled by role and org scope).
`GET`	`/wallets/users`	List user wallets (super_admin).
`GET`	`/wallets/orgs`	List organization wallets (super_admin).
`GET`	`/wallets/orgs/{org_id}/members`	Member wallets in an organization (org_admin or super_admin).
`POST`	`/wallets/{wallet_id}/grants`	Assign credits (org admin transfers from org wallet; super admin creates grants as configured).
`POST`	`/wallets/{wallet_id}/cap`	Set or clear monthly spend cap (USD) on a wallet.
`POST`	`/wallets/{wallet_id}/adjust`	Super-admin-only ledger adjustment (no credit-grant row).
`POST`	`/orgs/{org_id}/business-model`	Set `org_type`: `internal`, `channel_partner`, or `distributor` (super_admin).
`POST`	`/orgs/{org_id}/commission`	Set commission percentage for the org (super_admin).
`POST`	`/orgs/{org_id}/markup`	Set markup percentage and currency for reseller pricing (org_admin of reseller org or super_admin).

Legacy organization billing routes such as /organizations/{id}/billing/assign-credits return 410 Gone; use POST /api/v1/wallets/{wallet_id}/grants instead.

Earnings (reseller markup and commission)

Base path: /api/v1/earnings For org_admin users whose organization is a channel_partner or distributor (not internal):

Method	Path	Purpose
`GET`	`/earnings/me`	Summary for the caller’s org. Query: `period` = `day` \| `week` \| `month` \| `year` \| `all` (default `month`).
`GET`	`/earnings/me/breakdown`	Time-bucketed breakdown; same `period` query.
`GET`	`/earnings/orgs/{org_id}`	Super_admin view of any org’s earnings summary; same `period` query.

API keys — multiple keys, names, revoke

Base path: /api/v1/api-keys

Method	Path	Purpose
`POST`	`""`	Create key. Body: `{ "api_key": "<secret>", "user_id": "<uuid>", , "name": "optional label" }`. Response: `{ "message", "api_key": { ... } }`.
`GET`	`/fetch/{user_id}`	List active keys for a user (same user or org-admin scope).
`POST`	`/exists`	Body `{ user_id, provider_name }` → `true` if any active key exists for that provider.
`PATCH`	`/{key_id}`	Body `{ "name": "new label" }` (empty string clears the label).
`DELETE`	`/{key_id}`	Revokes the key (soft revoke); it stops working immediately.

The dashboard API Keys page supports multiple keys, optional names on create, rename, and revoke.

Voice catalog — TTS voices

Base path: /api/v1/tts-voices

Method	Path	Purpose
`GET`	`""`	List all TTS voices.
`POST`	`""`	Create a voice row.
`GET`	`/{voice_id}`	Get by id.
`GET`	`/provider/{provider_id}`	List voices for a provider.

Use GET /api/v1/tts-voices (no trailing slash required).

For interactive request/response shapes, continue to use the Voice Agent API OpenAPI tab and kupe-voice-agent.openapi.yaml.

​Tools — custom HTTP tools and MCP

​HTTP tool definitions (CRUD)

​MCP server tool definitions (CRUD)

​Attach tools to an agent

​Post-call analysis — rules and agent mapping

​User-scoped rules (CRUD)

​Map rules to an agent

​Outbound — batch campaigns (end-to-end API)

​Prerequisites

​End-to-end flow

​All routes

​Example: create → add numbers → launch → poll

​Call logs — list, pagination, single session, post-call data

​Export (ZIP, optional date range)

​Billing and usage (usage, cost, credit summary)

​API key vs session (important)

​Feature flags

​Wallets (credits, grants, ledger, org business model)

​Earnings (reseller markup and commission)

​API keys — multiple keys, names, revoke

​Voice catalog — TTS voices