Platform REST APIs

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.

Overview

Campaigns & Contacts

Voice Agent API

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

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

​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

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