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.
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.
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. |
/api/v1/tools-mcp-server-defs
Same idea as HTTP tools: POST / GET / GET /{id} / PUT / DELETE for MCP-backed tools.
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. |
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 — batches, numbers, campaign launch
Base path: /api/v1/batch-call
| Method | Path | Purpose |
|---|
POST | /create | Create a batch (agent/workflow, variable names, batch name, etc.). |
POST | /upload/{batch_id} | Upload CSV with to_phonenumber and variable columns. |
POST | /{batch_id}/data/upsert | Add or update rows via JSON (numbers + variables). |
GET | /{batch_id}/data | List batch rows (optional ?status= filter). |
GET | /browse | Browse batches (filters/query as implemented by the API). |
GET | /user/{user_id} | List batches for a user. |
GET | /{batch_id} | Get batch metadata. |
POST | /start/{batch_id} | Launch campaign — start dialing for queued numbers. |
POST | /status-callback | Provider status webhook (configured with your telephony provider). |
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_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). |
/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). |
/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. |
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. |
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.
