All pages

API endpoints

Every request goes to https://app.katexs.com/api/v1 with your API key from Settings → API keys.

Agents

GET/api/v1/agents

List Agents

Every agent in your workspace, newest first, in the same shape Get Agent returns. Page with limit and cursor.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/agents" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents

Create Agent

Makes an agent exactly as the console does: a starter persona when you send no instructions, a website widget key, and (where your deployment has voice) a voice channel that answers on the web and WhatsApp. Only name is required. The plan's agent allowance, its model list and its voice tiers apply; a refused voice undoes the whole create. A build key may do this.

Body

  • name string · requiredThe agent's name, 2 to 60 characters, without hidden characters or markup.
  • instructions stringWhat the agent is and how it behaves. Left out, it gets the starter persona the console gives a blank agent. Re-sent on every reply, so every character costs on every turn.
  • greeting stringThe first thing it says on a call or in a chat.
  • businessDescription stringOne line about what the business is. Facts belong in Knowledge.
  • model stringnullA model id from List Models, or `null` for the default (Prana [Voice]) — the same as leaving it out. An empty string is a 400. If given, it is the same list the console's one model picker offers, for chat and calls alike: it must be on your plan, quick enough to answer a call (`voice: true`), within the per-minute budget a call can carry, and not one of our voice-only models (they answer calls on their own and are never an agent's model). A chat-only agent is held to the same list, as in the console.
  • temperature numberHow adventurous the wording is. Clamped to 0–2.
  • maxReplyTokens numberThe longest a reply may be, in tokens, for chat and calls alike. Rounded and clamped to 100–800.
  • languages string[]The languages the agent speaks, by their English names: `[]` is auto (reply in the customer's language), one name is that language alone, and two to four make the agent expect those languages, the first being the one it falls back to when it cannot tell. On a phone call the recogniser works out the language among them. Send `languages` or `language`, not both: `language` sets one language and clears this list. A name the console does not offer, a repeat, or more than four is refused with a 400.
  • language string`auto` to reply in the customer's language, or a language the console offers by its English name: English, Hindi, Assamese, Bengali, Bodo, Dogri, French, German, Gujarati, Indonesian, Italian, Japanese, Kannada, Kashmiri, Konkani, Korean, Maithili, Malayalam, Manipuri, Marathi, Nepali, Odia, Polish, Portuguese, Punjabi, Russian, Sanskrit, Santali, Sindhi, Spanish, Swahili, Tamil, Telugu, Thai, Turkish, Urdu or Vietnamese.
  • secondLanguage stringnullRetired. Accepted so an older integration keeps working, but ignored: the agent answers in `language` alone.
  • escalation objectWhen the agent hands over to a person. Send either or both.
  • captureLeads booleanTake a name, email or phone number from an interested customer.
  • ownRules booleantrue leaves out the platform's own lead, hand-over and call-back sentences, for a business that writes those rules in its instructions. Left out: the sentence about asking for details (or that the business does not collect them), the hand-over rule (or that nobody can be handed to, and that nobody should promise a follow-up) and the "cannot book a call back" sentence. Kept whatever you send: the boundary, the AI disclosure, the reply language, the date, your own instructions, and how a call is put through to a person.
  • scheduleCallbacks booleanAllow it to book a call back when asked.
  • welcomeScreen booleanOpen the website widget on a welcome screen.
  • welcomeCollectLeads booleanAsk for the visitor's details on the welcome screen.
  • steps object[]A conversation script, in order, replacing any there was. Blank steps are dropped.
  • byok stringnullHow this agent uses the workspace's own provider keys (Bring your own keys). `null` (or `workspace`) follows the workspace: its default scope applies when it brings its own keys. `off` never does: our voices and models at our normal pricing, whatever the workspace does, and the model is not held to the voice-only-BYOK model list. `all`, `voice`, `llm` or `llm_voice` runs this agent on that scope's keys whatever the workspace default is; refused with `409` naming the missing key unless the workspace holds verified keys for every kind that scope needs. If a key goes later, the agent falls back to the workspace's scope at the next call. Omit the field to leave it unchanged; saved BYOK model and voice choices are kept but not used while it is `off`. Read back as `workspace` when it follows the workspace.
  • widget objectThe website widget's look. Send any subset.
  • voice objectHow the agent handles calls. Send any subset. Where an agent has no voice channel yet, sending any of these creates one — switched OFF, so setting only a voice or a message never starts it taking calls; send `answersCalls: true` to switch it on.
  • collectFields arraynullThe details to fill in from the transcript after every call; they arrive as `fields` in each call's results. A call that sends its own `extract` uses that instead.
curl -X POST "https://app.katexs.com/api/v1/agents" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/agents/{id}

Get Agent

One agent: its instructions, model, languages, script, widget, call settings and the details it collects from calls. Which engine speaks its voice or runs its model is never part of the answer.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/agents/{id}

Update Agent

Changes any subset of the fields Create Agent takes and answers with the whole agent. Fields you leave out are untouched, and unknown fields are ignored — but a body that names no field this API knows is refused. A model or voice is checked against your plan only when it changes, and a refused voice refuses the whole patch before anything is written. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.

Body

  • name stringThe agent's name, 2 to 60 characters, without hidden characters or markup.
  • instructions stringWhat the agent is and how it behaves. Re-sent on every reply, so every character costs on every turn.
  • greeting stringThe first thing it says on a call or in a chat. An empty string clears it.
  • businessDescription stringOne line about what the business is. Facts belong in Knowledge.
  • model stringnullA model id from List Models, or `null` to put the agent back on the default model (Prana [Voice]) — the way back to the defaults; the plan and call rules below still apply to it. An empty string is a 400. Checked only when it changes, against the console's one model picker for chat and calls alike: on your plan, quick enough to answer a call (`voice: true`), within the per-minute budget a call can carry, and not one of our voice-only models. A chat-only agent is held to the same list, as in the console.
  • temperature numberHow adventurous the wording is. Clamped to 0–2.
  • maxReplyTokens numberThe longest a reply may be, in tokens, for chat and calls alike. Rounded and clamped to 100–800.
  • languages string[]The languages the agent speaks, by their English names: `[]` is auto (reply in the customer's language), one name is that language alone, and two to four make the agent expect those languages, the first being the one it falls back to when it cannot tell. On a phone call the recogniser works out the language among them. Send `languages` or `language`, not both: `language` sets one language and clears this list. A name the console does not offer, a repeat, or more than four is refused with a 400.
  • language string`auto` to reply in the customer's language, or a language the console offers by its English name, e.g. `Hindi`, `Tamil`, `English`.
  • secondLanguage stringnullRetired. Accepted so an older integration keeps working, but ignored: the agent answers in `language` alone.
  • escalation objectWhen the agent hands over to a person. Send either or both.
  • captureLeads booleanTake a name, email or phone number from an interested customer.
  • ownRules booleantrue leaves out the platform's own lead, hand-over and call-back sentences, for a business that writes those rules in its instructions. Left out: the sentence about asking for details (or that the business does not collect them), the hand-over rule (or that nobody can be handed to, and that nobody should promise a follow-up) and the "cannot book a call back" sentence. Kept whatever you send: the boundary, the AI disclosure, the reply language, the date, your own instructions, and how a call is put through to a person.
  • scheduleCallbacks booleanAllow it to book a call back when asked.
  • welcomeScreen booleanOpen the website widget on a welcome screen.
  • welcomeCollectLeads booleanAsk for the visitor's details on the welcome screen.
  • steps object[]The conversation script, in order, replacing the whole script. `[]` removes it.
  • byok stringnullHow this agent uses the workspace's own provider keys (Bring your own keys). `null` (or `workspace`) follows the workspace: its default scope applies when it brings its own keys. `off` never does: our voices and models at our normal pricing, whatever the workspace does, and the model is not held to the voice-only-BYOK model list. `all`, `voice`, `llm` or `llm_voice` runs this agent on that scope's keys whatever the workspace default is; refused with `409` naming the missing key unless the workspace holds verified keys for every kind that scope needs. If a key goes later, the agent falls back to the workspace's scope at the next call. Omit the field to leave it unchanged; saved BYOK model and voice choices are kept but not used while it is `off`. Read back as `workspace` when it follows the workspace.
  • widget objectThe website widget's look. Send any subset.
  • voice objectHow the agent handles calls. Send any subset. Where an agent has no voice channel yet, sending any of these creates one — switched OFF, so setting only a voice or a message never starts it taking calls; send `answersCalls: true` to switch it on.
  • collectFields arraynullThe details to fill in after every call, replacing the list. `[]` or null stops collecting; records already taken are kept.
curl -X PATCH "https://app.katexs.com/api/v1/agents/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/agents/{id}

Delete Agent

Deletes the agent and everything under it: its conversations, knowledge, actions and channels. It cannot be undone. A build key may do this.

Refused with 409 agent_on_live_call while the agent is on a call (ringing or connected): deleting it then would lose that call's recording, transcript, analysis and usage. Delete it after the call ends.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.
curl -X DELETE "https://app.katexs.com/api/v1/agents/{id}" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/agents/{id}/byok-model

Get Agent BYOK Model

On a workspace that brings its own keys: the model this agent runs on your own LLM key. model is the agent's own choice (null when it runs the key's model), and stale names an earlier choice your key no longer reaches, which the key's model answers in place of. Refused with 409 when the workspace is not using its own keys, or when this agent is set to byok: "off" (it then runs on our models, and a choice you set is not available to read until you put it back on the workspace's keys).

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/byok-model" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/agents/{id}/byok-model

Set Agent BYOK Model

Chooses which model of your own LLM key this agent runs. It must be one the key reaches — listed under byok.models by List Models — or null to run the key's own model (the one set under Settings → Your keys). The next reply uses it. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.

Body

  • model stringnull · requiredA model your LLM key reaches (List Models, `byok.models`), or null for the key's own model.
curl -X PUT "https://app.katexs.com/api/v1/agents/{id}/byok-model" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/agents/{id}/byok-voice

Get Agent BYOK Voice

On a workspace that brings its own keys: the voice this agent speaks with on your own voice provider. voice is null for the provider's default voice. A choice belongs to the provider it was made on; after you switch your voice key to another provider, stale holds the old choice and calls speak the new provider's default until you choose again. On a Cartesia key the response also holds how the voice sounds: speed, volume, emotion, agentModel (this agent's own Sonic model; model is always your key's) and pronunciationDictId, each null while unset. Refused with 409 when the workspace is not using its own voice key (it brings no keys, or only its language model), or when this agent is set to byok: "off" (it then speaks in our voices).

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/byok-voice" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/agents/{id}/byok-voice

Set Agent BYOK Voice

Chooses the voice this agent speaks with on your own voice provider: an id from List BYOK Voices, checked against the provider's list for your key, or null for the provider's default. On Cartesia an id that is not on the list yet, such as a voice cloned a moment ago, is checked with Cartesia directly and accepted if your key owns it. The agent needs a voice channel first. A build key may do this.

On a Cartesia key you can also set how this agent's voice sounds: speed (0.6 to 1.5), volume (0.5 to 2.0), emotion (one of Cartesia's values; English only), model (sonic-3.6, sonic-3.6-2026-08-27, sonic-3.5, sonic-3 or sonic-2 for this agent alone; sonic-3.6 follows Cartesia's latest stable snapshot, the dated one never changes) and pronunciationDictId (a dictionary id from your Cartesia account). Every field is optional and the request only changes what it names: a key left out stays as it is, null goes back to the default, a value sets it. So { "voice": "…" } alone changes the voice and keeps the settings; { "voice": null } goes back to the provider's default voice and clears them. The settings belong to a voice of the agent's own: sending one before a voice is chosen, or with voice: null, is refused. speed, volume and emotion need a Sonic 3 model, and speed does not apply to a Cartesia Professional Voice Clone. A refused field answers 400 with code: validation_failed and field naming it.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.

Body

  • voice stringnullA voice id from List BYOK Voices, or null for the provider's default (which clears the settings below).
  • speed numbernullCartesia only. How fast the voice speaks; 1 is Cartesia's own. Needs a Sonic 3 model. Does not apply to a Professional Voice Clone.
  • volume numbernullCartesia only. How loud the voice is; 1 is Cartesia's own. Needs a Sonic 3 model.
  • emotion stringnullCartesia only. One of Cartesia's emotions, for example `neutral`, `calm`, `content`, `sad`, `angry`, `scared`, `happy`, `excited`. Works in English only. Needs a Sonic 3 model.
  • model stringnullCartesia only. The Sonic model this agent speaks on; null uses your key's model.
  • pronunciationDictId stringnullCartesia only. The id Cartesia gave a pronunciation dictionary in your account; null for none.
curl -X PUT "https://app.katexs.com/api/v1/agents/{id}/byok-voice" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
POST/api/v1/agents/{id}/test-chat

Test Chat

Talks to your real agent through its website chat — the same prompt, model, knowledge, actions, limits and billing as the console's Playground — and answers with its reply and every tool it used. It runs as a sandbox: anything that would phone, message, email or send a code to a person, or change a calendar booking, is switched off and the agent says what it would have done instead; your own actions still run for real, and every request they make carries an X-Test-Chat: true header (and {{test.chat}} fills as true) so your endpoint can answer without writing anything. The conversation appears in your inbox; send session back to continue it. It always runs the agent as saved: there is no separate draft, so a change you save is live at once. To try a change first, create a second agent with it (Create Agent) and test that one. A reply costs what a chat reply costs: on an agent using its own language-model key, the flat ₹0.02 own-key reply price. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`), as List Agents returns it. Another workspace's agent is the same `404` as one that never existed.

Body

  • message string · requiredWhat the customer says. Trimmed; up to 4,000 characters.
  • session stringThe `session` a previous test chat answered with, to continue that conversation. Leave it out to start a new one.
  • mode string`chat` talks to the agent as a website visitor. `call` runs the turn with the agent's **call** prompt: its call rules (or the built-in ones), the speaking rules, the model its calls use (the Voice page's, or your own key's) and, on your own Gemini key, the thinking level a call uses, with no cards or buttons. It shows the words a caller will be given, not the audio, and not the call's own tools (transferring, hanging up). Needs calling set up on the agent (`409` otherwise).
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/test-chat" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Knowledge

GET/api/v1/agents/{id}/knowledge

List Knowledge Documents

The agent's documents, newest first, with whether each is ready to be cited. Files uploaded in the console are listed here too.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/knowledge" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/knowledge

Add Knowledge Document

Adds a web page (url) or pasted text to what the agent knows. A page is fetched and indexed before this answers, so a slow site is a slow request; passages says how much was indexed. A page that cannot be read is answered 422 with the reason and the failed document it left behind, which you can delete. Files are uploaded in the console. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).

Body

  • url stringA web page to fetch and index. Must start with `http://` or `https://`.
  • text stringText to index, up to 200,000 characters. Trimmed.
  • title stringA title for `text`; cut to 200 characters. Left out, it is `Pasted text`. Ignored with `url`, whose title comes from the page.
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/knowledge" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/agents/{id}/knowledge/{documentId}

Delete Knowledge Document

Removes the document and every passage indexed from it; the agent stops citing it at once. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • documentId string · path · requiredThe document's id (`doc_…`), from List Knowledge Documents.
curl -X DELETE "https://app.katexs.com/api/v1/agents/{id}/knowledge/{documentId}" \
  -H "Authorization: Bearer $API_KEY"

Actions

GET/api/v1/agents/{id}/actions

List Actions

The agent's actions — calls to your own HTTPS API that it may make mid-conversation — newest first. Header values never appear; only headerNames.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/actions" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/actions

Create Action

Give the agent a call to your own API, with placeholders it fills from what the customer said. Dotted placeholders are filled by the platform, never the model: {{call.id}} (the id GET /calls lists), {{call.from}}, {{call.to}}, {{call.direction}} (empty outside a call), {{conversation.id}}, {{contact.id}}, {{contact.phone}}, {{agent.id}}, {{workspace.id}} and {{test.chat}} (true during a test chat, empty otherwise) — in the path, query, body or a header value, never the host; an unknown one is refused. Every call also sends X-Call-Id, X-Conversation-Id, X-Agent-Id and X-Workspace-Id when known, and X-Test-Chat: true during a test chat (POST /agents/{id}/test-chat), where the call values are empty and X-Call-Id is absent — so your endpoint can answer without writing anything. A new action is always off: test it with POST …/test, then PATCH enabled: true — sending enabled here is refused. Header values are sealed on arrival and never returned. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).

Body

  • name string · requiredThe tool name the agent sees: 3 to 40 characters, lower case letters, numbers and underscores, starting with a letter. It cannot be one of the agent's built-in tools, and must be unique on this agent.
  • description string · requiredWhen the agent should call it, in a sentence (at least 10 characters). The model decides from this alone.
  • url string · requiredAn `https://` address, with `{{placeholders}}` for parameters. Every placeholder needs a parameter of that name. Addresses inside private networks are refused when called.
  • method stringThe HTTP method; any case is accepted.
  • parameters object[]Up to 20 values the agent fills from the conversation. Names must be unique.
  • bodyTemplate stringnullA JSON body with **quoted** placeholders, e.g. `{"id": "{{order_id}}"}`. It must still be valid JSON once the blanks are filled.
  • headers objectUp to 10 headers, name to value — typically `Authorization`. **Write-only:** sealed on arrival; only their names come back, as `headerNames`. Blank values are dropped.
  • speakBefore stringnullOn calls, what the agent says while your API is being called.
  • speakAfter stringnullOn calls, what the agent says while it turns your answer into a reply.
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/actions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/agents/{id}/actions/{actionId}

Get Action

One action. Header values never appear; only headerNames.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • actionId string · path · requiredThe action's id (`act_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/actions/{actionId}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/agents/{id}/actions/{actionId}

Update Action

Change any field, or switch it on or off with enabled. The action is validated as it will be saved, so a new url is checked against the parameters already there. Leaving headers out keeps the saved credential; sending any replaces the whole set. enabled: true makes it callable from every conversation at once. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • actionId string · path · requiredThe action's id (`act_…`).

Body

  • name stringThe tool name the agent sees; same rules as on create.
  • description stringWhen the agent should call it (at least 10 characters).
  • url stringAn `https://` address with `{{placeholders}}`.
  • method stringThe HTTP method.
  • parameters object[]Replaces the whole list.
  • bodyTemplate stringnullThe JSON body; null removes it.
  • headers objectLeave it out (or send `{}`) to keep the saved headers. Sending any **replaces the whole set**, so include every header the call needs. There is no way to remove all headers short of deleting the action.
  • speakBefore stringnullWhat the agent says while your API is called; null clears it.
  • speakAfter stringnullWhat the agent says afterwards; null clears it.
  • enabled boolean`true` puts the action within reach of every conversation the agent has; `false` takes it away.
curl -X PATCH "https://app.katexs.com/api/v1/agents/{id}/actions/{actionId}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/agents/{id}/actions/{actionId}

Delete Action

Remove the action and its sealed headers. The agent stops being able to call it at once. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • actionId string · path · requiredThe action's id (`act_…`).
curl -X DELETE "https://app.katexs.com/api/v1/agents/{id}/actions/{actionId}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/actions/{actionId}/test

Test Action

Make the call once, for real, through the same address checks and credentials the agent uses — and it works while the action is still off, which is the point. A test has no conversation, so only {{agent.id}} and {{workspace.id}} fill; the rest are empty. A failed call is still 200, with ok: false. On a POST, PUT, PATCH or DELETE action the test does the write. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • actionId string · path · requiredThe action's id (`act_…`).

Body

  • arguments objectParameter name to value — what the agent would have filled in.
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/actions/{actionId}/test" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Tools

GET/api/v1/agents/{id}/tools

List Built-in Tools

The agent's built-in tools — the Actions page's switches — with the recall, verification and hand-over settings. The three tools that reach a customer on another channel also say whether they are ready (on, and what they need exists) and what they needs.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/tools" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/agents/{id}/tools

Update Built-in Tools

Switch built-in tools on or off and set recall, code verification and the hand-over. search_knowledge is not a switch and web search cannot be switched on; both are refused. Changes apply in order and stop at the first refusal, keeping what came before. Needs a full key. — it can arm tools that call or message customers.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).

Body

  • tools objectTool id to `true` or `false`. Switchable: `capture_lead`, `escalate_to_human`, `schedule_callback`, `call_them_now`, `send_whatsapp`, `send_sms`, `reply_by_email`.
  • recall stringHow much of a recognised customer's history the agent may use: `trusted` (all of it), `two_tier` (the default) or `verified` (only once they are confirmed).
  • verifyByCode booleanConfirm a customer with a one-time WhatsApp code instead of their email.
  • knowledgeOnCalls booleanLet the agent search its knowledge during calls (on by default). Off, a call answers from its instructions alone and skips the search; chat is not affected.
  • handOver objectFields you leave out keep their saved value.
curl -X PATCH "https://app.katexs.com/api/v1/agents/{id}/tools" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/agents/{id}/mcp-servers

List Tool Servers

Every tool server the agent is connected to, oldest first, each with its tools. All come in one page. Tokens never appear; hasSecret says one is held.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/mcp-servers" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/mcp-servers

Connect Tool Server

Connect an MCP tool server that takes a token (or none). It is asked for its tools at once and every tool arrives off — switch each on with PATCH …/tools/{toolId}. A server that cannot be reached is still saved and answers 201 with status: "failed" and the reason in message, so you can fix it and sync. A server that signs in through a browser must be connected in the console. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).

Body

  • name string · requiredYour name for it, 2 to 200 characters.
  • url string · requiredIts `https://` address. It must be publicly reachable: private and internal addresses are refused.
  • transport string`http` (streamable HTTP) or `sse`.
  • authHeaderName stringThe header to send the token in, e.g. `Authorization`. Required when `secret` is sent.
  • secret stringThe header's value, e.g. `Bearer …`. **Write-only:** sealed on arrival; responses say only `hasSecret`.
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/mcp-servers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/agents/{id}/mcp-servers/{serverId}

Get Tool Server

One tool server and its tools.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • serverId string · path · requiredThe tool server's id, `mcp_…`. The bare uuid is accepted too.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/mcp-servers/{serverId}" \
  -H "Authorization: Bearer $API_KEY"
DELETE/api/v1/agents/{id}/mcp-servers/{serverId}

Disconnect Tool Server

Disconnect the server; its tools leave the agent at once and its token is deleted. This works for servers connected in the console too. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • serverId string · path · requiredThe tool server's id, `mcp_…`. The bare uuid is accepted too.
curl -X DELETE "https://app.katexs.com/api/v1/agents/{id}/mcp-servers/{serverId}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/mcp-servers/{serverId}/sync

Sync Tool Server

Ask the server what it offers, again — the console's Refresh, and the closest thing to a test. New tools arrive off; tools it no longer lists leave the agent. A store connection has a fixed list and is refused. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • serverId string · path · requiredThe tool server's id, `mcp_…`. The bare uuid is accepted too.
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/mcp-servers/{serverId}/sync" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/agents/{id}/mcp-servers/{serverId}/tools/{toolId}

Update Tool Server Tool

Switch one of a server's tools on or off. On, it is callable from every conversation the agent has. Answers with the server and all its tools. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • serverId string · path · requiredThe tool server's id, `mcp_…`. The bare uuid is accepted too.
  • toolId string · path · requiredThe tool's id on that server, `tool_…`, from the server's `tools`. The bare uuid is accepted too.

Body

  • enabled boolean · required`true` lets the agent call this tool in every conversation; `false` takes it away.
curl -X PATCH "https://app.katexs.com/api/v1/agents/{id}/mcp-servers/{serverId}/tools/{toolId}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/agents/{id}/connections

List Connections

Every account the agent can work in, connected or not — a calendar, two spreadsheets, two CRMs, records kept here and two helpdesks — each with its state, what it is pinned to and its tools. toolsInUse / maxTools is the one budget every connection's switches share. Credentials never appear.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/connections" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/agents/{id}/connections/{kind}

Get Connection

One connection, connected or not, with the shared tool budget.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • kind string · path · requiredThe connection: `calcom` or `calendly` (calendars), `grist` or `googlesheets` (spreadsheets), `zoho`, `zoho_bigin` or `hubspot` (CRMs), `records` (kept here), `zendesk` or `salesforce` (helpdesks).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/connections/{kind}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/connections/{kind}

Connect Account

Connect (or re-key) an account. Every key, token and secret is sealed and never returned. Connecting grants nothing: tools start off and are switched with PATCH tools. googlesheets, zoho, zoho_bigin, hubspot and calendly sign in on the provider's own consent screen — connect them once in the console (this answers 409), then configure them here. A helpdesk connect opens one test ticket or case and answers with inbound once; a records connect that makes the first link answers with link.passcode once. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • kind string · path · requiredThe connection: `calcom` or `calendly` (calendars), `grist` or `googlesheets` (spreadsheets), `zoho`, `zoho_bigin` or `hubspot` (CRMs), `records` (kept here), `zendesk` or `salesforce` (helpdesks).
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/connections/{kind}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/agents/{id}/connections/{kind}

Configure Connection

Pin a connection to its target, say how a lead's row is found, choose when it saves, and switch its tools. The account must be connected first (records excepted). Changes apply in a fixed order and stop at the first refusal, keeping what came before it. Helpdesks have nothing to configure. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • kind string · path · requiredThe connection: `calcom` or `calendly` (calendars), `grist` or `googlesheets` (spreadsheets), `zoho`, `zoho_bigin` or `hubspot` (CRMs), `records` (kept here), `zendesk` or `salesforce` (helpdesks).

Body

  • fields one ofRecords only: what to collect, `Label` or `Label | what it means`.
  • target objectSpreadsheets, CRMs and Calendly: pins it and reads the target's real columns. Grist needs `doc` and `table`; Google Sheets `spreadsheet` and `sheet`; Zoho CRM, Bigin and HubSpot `module` (HubSpot's is `contacts`); Calendly `eventTypes`, the meeting types the agent may book. Use `GET …/options` to see the choices.
  • properties string[]HubSpot only: the contact properties the agent fills and searches by (at most 40). Pinning starts from a default pick; this replaces it.
  • match objectnullSpreadsheets and CRMs: fill the lead's existing row found by this column instead of adding one. Null (or `column: null`) adds a row per conversation.
  • variableColumns objectSpreadsheets and CRMs: column to campaign variable, e.g. `{ "Locality": "locality" }`. Neither may contain `=` or a line break. Replaces the saved map.
  • mode stringAll but the calendar: `tool` saves during the conversation; `parser` reads the conversation afterwards (and switches the save tool off).
  • runAsync booleanGrist only: answer before the save finishes.
  • tools objectTool id to `true` or `false`. Every id must be one of this connection's tools. Switching on counts against the shared `maxTools` budget.
  • phrases objectTool id to `{ before, after }`: what the agent says on a call while the tool runs. Up to 8 lines, each under 60 characters.
curl -X PATCH "https://app.katexs.com/api/v1/agents/{id}/connections/{kind}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/agents/{id}/connections/{kind}

Disconnect Account

Disconnect the account; its tools leave the agent and its credential is deleted. A browser sign-in still pending is cancelled too. What already happened in the account (meetings booked, rows written) is untouched, and records already collected are kept. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • kind string · path · requiredThe connection: `calcom` or `calendly` (calendars), `grist` or `googlesheets` (spreadsheets), `zoho`, `zoho_bigin` or `hubspot` (CRMs), `records` (kept here), `zendesk` or `salesforce` (helpdesks).
curl -X DELETE "https://app.katexs.com/api/v1/agents/{id}/connections/{kind}" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/agents/{id}/connections/{kind}/options

List Connection Options

What a connected account can reach, read live each time, so you can choose a target for PATCH …/connections/{kind}: a Grist document's tables and columns (?doc=), a spreadsheet's sheets (?spreadsheet=), the modules a Zoho account can write to, HubSpot's one module (contacts), or a Calendly account's meeting types. Other kinds have nothing to choose.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
  • kind string · path · requiredThe connection: `calcom` or `calendly` (calendars), `grist` or `googlesheets` (spreadsheets), `zoho`, `zoho_bigin` or `hubspot` (CRMs), `records` (kept here), `zendesk` or `salesforce` (helpdesks).
  • doc string · queryGrist only, and required there: the document id to look in.
  • spreadsheet string · queryGoogle Sheets only, and required there: the spreadsheet id or its link.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/connections/{kind}/options" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/connections/records/link

Replace Records Link

Make a new link to read the records the agent collects, with a new passcode — shown in this response and never again. The old link stops working at once, which is also how a link shared too widely is revoked. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/connections/records/link" \
  -H "Authorization: Bearer $API_KEY"

Channels

GET/api/v1/agents/{id}/channels

Get Agent Channels

Where the agent answers, as the Channels page shows it: the widget key, the WhatsApp number and its health, the Telegram bot and the voice line. No token or secret is ever part of the answer. The widget's look and the call settings are changed with Update Agent (widget, voice).

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/channels" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/agents/{id}/channels/telegram

Connect Telegram Bot

Connects a Telegram bot to the agent with the token @BotFather gave you: the token is checked with Telegram, stored encrypted and never shown again, and Telegram is told where to deliver messages. Telegram needs a paid plan, and a bot can belong to one agent only. Telegram calls back on the address this request arrived on, so call the public API address. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).

Body

  • token string · requiredThe bot token @BotFather sent you. Stored encrypted; never returned.
curl -X POST "https://app.katexs.com/api/v1/agents/{id}/channels/telegram" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/agents/{id}/channels/telegram

Disconnect Telegram Bot

Disconnects the agent's Telegram bot (a 404 when none is connected) and tells Telegram to stop delivering to us. Its conversations stay in your inbox, and the bot itself still exists in Telegram — delete it in @BotFather if you want it gone. A build key may do this.

Parameters

  • id string · path · requiredThe agent's id (`ag_…`).
curl -X DELETE "https://app.katexs.com/api/v1/agents/{id}/channels/telegram" \
  -H "Authorization: Bearer $API_KEY"

Calls

GET/api/v1/calls

List Calls

Every call your workspace made or took — inbound, website, WhatsApp, a campaign's or one you placed — newest first, without transcripts or recordings. Each item's id opens the call with Get Call. A call booked for later appears here only once it has rung; read a booked call by the sch_… id Place Call gave you.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
  • agent string · queryOnly this agent's calls — its `ag_…` id.
  • status string · queryOnly calls in this state.
  • reference string · queryOnly calls placed with this `reference` — your CRM's own id for the lead. Matched exactly; up to 200 characters are read.
  • since string · queryOnly calls that started at or after this date (`2026-09-17`, from midnight UTC) or instant (`2026-09-17T10:00:00Z`).
  • until string · queryOnly calls that started at or before this date or instant. A bare date (`2026-10-06`) includes that whole day, UTC; give an offset (`2026-10-06T23:59:59+05:30`) for a different day boundary.
curl -X GET "https://app.katexs.com/api/v1/calls" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/calls

Place Call

Your agent rings a customer, opens with your purpose (spoken aloud, so 300 characters or fewer), then holds a normal conversation. A number that is not a contact yet becomes one with the name and source you send; someone who opted out or is on your do-not-call list is refused. Outside the calling hours you set with callingHours (any hour of any day when you set none), in the customer's own time, or with scheduledAt, the call is queued and answers status: "scheduled" with a sch_… id; otherwise it rings now with an out_… id. Each call is billed from your balance, refused with 402 when it cannot pay, held to your plan's concurrent lines and 60 requests a minute; what it learned arrives as call.analysed or from Get Call. Needs a full key.

curl -X POST "https://app.katexs.com/api/v1/calls" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/calls/batch

Place Batch Calls

Rings up to 200 people with one request. Every option Place Call takes may be set once for the batch and again on an entry, the entry winning (an entry's variables sit on top of the batch's); purpose and agent are the batch's. Every entry is queued and paced inside your plan's lines and balance — none rings inline — and each gets its own sch_… id that reports through call.analysed and Get Call. A bad entry is listed under refused and does not stop the rest. Needs a full key.

curl -X POST "https://app.katexs.com/api/v1/calls/batch" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/calls/{id}

Get Call

One call and everything it learned: status, timings, how it ended, the summary, the collected fields, the transcript, a signed recording link and the call's quality figures (reply times, silences, interruptions, model errors). It is exactly the object call.analysed delivers, so a missed delivery can be read back here; analysedAt null means the summary and fields are not final yet. Any id List Calls hands out works — out_… and sch_… for calls you placed, the call reference for any other.

Parameters

  • id string · path · requiredThe call's `id` as Place Call or List Calls gave it: `out_…` or `sch_…` for a call you placed, the call reference for any other.
curl -X GET "https://app.katexs.com/api/v1/calls/{id}" \
  -H "Authorization: Bearer $API_KEY"
DELETE/api/v1/calls/{id}

Cancel Call

Calls off a call you placed through the API (out_… or sch_…). A call still waiting to ring — booked, queued for its hours, or a retry — is cancelled and answers 200 with its report, status: "cancelled". A call ringing or connected is ended on the line and answers 202 with the report as it stands; its ending arrives a moment later with call.analysed, and no retry follows. A call that has already ended answers 409. Needs a full key.

Parameters

  • id string · path · requiredThe call's `id` as Place Call or List Calls gave it: `out_…` or `sch_…` for a call you placed, the call reference for any other.
curl -X DELETE "https://app.katexs.com/api/v1/calls/{id}" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/calls/{id}/transcript

Get Call Transcript

What was said on one call, oldest first: this call's spoken turns only, internal notes left out — the same words call.analysed delivers. ?format=txt returns a plain-text file to save (call-{id}.txt, one [mm:ss] Who: what line per turn). A turn's offset is when it was written down, not where it falls in the audio, so it suits ordering and rough position but not subtitles.

Parameters

  • id string · path · requiredThe call's `id` as Place Call or List Calls gave it: `out_…` or `sch_…` for a call you placed, the call reference for any other.
  • format string · query`json` (the default) for the turns as JSON, `txt` for a plain-text attachment.
curl -X GET "https://app.katexs.com/api/v1/calls/{id}/transcript" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/calls/{id}/timeline

Get Call Timeline

Where the time went in each turn of one call. Every time is in milliseconds from the moment the caller stopped speaking, so a turn reads as a row of steps: the recogniser's wait and the caller's final words, Ear's check, the turn being decided, the model being asked, the first words of the answer leaving the model, the first sound of any kind, and the answer being heard. split adds up the pieces a team works on: the wait before the turn was decided, the recogniser, Ear's check, the model's first sentence and the voice.

answerAudioMs is the time to the first word of the ACTUAL answer. quality.responseMs stops at the first sound of any kind, so a thinking line that plays first ends it; here firstAudioKind says what spoke first (answer, filler or other) and answerAudioEstimated is true when a filler spoke first and the answer's start is worked out from the audio queued behind it rather than heard directly. A step that did not happen on a turn is null, never zero. A negative modelAskedMs is real: with earlyAnswers the model is asked before the turn is decided.

timeline is null for a call that has none: a call from before this existed, or one on a call type that does not record it. It holds times only, no words, so it stays when a call's content is deleted. Any id List Calls hands out works.

Parameters

  • id string · path · requiredThe call's `id` as Place Call or List Calls gave it: `out_…` or `sch_…` for a call you placed, the call reference for any other.
curl -X GET "https://app.katexs.com/api/v1/calls/{id}/timeline" \
  -H "Authorization: Bearer $API_KEY"

Post-call

GET/api/v1/calls/{id}/analysis

Get Call Analysis

What one call came to, without the transcript: the outcome as the console's call log shows it ("Answered", "Line busy", "Answering machine"), the summary and the collected fields. outcome is null until the call has ended; analysedAt null means the summary and fields may still arrive, and call.analysed is sent the moment they do. Any id List Calls hands out works.

Parameters

  • id string · path · requiredThe call's `id` as Place Call or List Calls gave it: `out_…` or `sch_…` for a call you placed, the call reference for any other.
curl -X GET "https://app.katexs.com/api/v1/calls/{id}/analysis" \
  -H "Authorization: Bearer $API_KEY"
DELETE/api/v1/calls/{id}/content

Delete Call Content

Deletes ONE call's recording and transcript, and keeps its billing record. Gone: the recording (ours, the phone provider's copy of a call on a number we rent, and any copy made for model training), this call's own turns in its conversation (other calls and chats with the same person stay), its summary, its collected fields, and the summary handed on with a warm hand-off. Kept: the call itself — when it happened, who it was with, how long it lasted, what it cost and billing. Afterwards Get Call answers with recording: null, an empty transcript, contentDeleted: true and contentDeletedAt. A recording that cannot be deleted at that moment is queued and retried every night until it is gone, and counted in recordingsPending. For a call you placed that was retried, every attempt's content goes. This cannot be undone.

This is not Cancel Call: DELETE /calls/{id} still calls a call off. Safe to repeat — again answers 200 with the first deletion's time. Needs a full key; a developer reaches a customer's call with X-Workspace.

Parameters

  • id string · path · requiredThe call's `id` as Place Call or List Calls gave it: `out_…` or `sch_…` for a call you placed, the call reference for any other.
curl -X DELETE "https://app.katexs.com/api/v1/calls/{id}/content" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/agents/{id}/post-call

Get Post-call Settings

What an agent does after each call: whether it summarises and records calls, how long your plan keeps a recording, and the details it collects. These are the agent's own settings — the same values Get Agent shows under voice and collectFields — and followUp, the WhatsApp and/or SMS the agent sends the caller when a call ends.

Parameters

  • id string · path · requiredThe agent's `ag_…` id.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/post-call" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/agents/{id}/post-call

Update Post-call Settings

Changes what an agent does after each call; send only what you are changing. collectFields replaces the whole list, and an empty list stops collecting (details already collected are kept). Any other key is refused — the rest of the agent belongs to Update Agent. followUp sets the WhatsApp and/or SMS sent to the caller when a call ends, and is partial: what it leaves out keeps what is saved. A WhatsApp template must be an approved Utility one; an SMS needs a connected SMS provider. Answers with the settings as they now stand. A build key may do this, except followUp: it messages customers, so it needs a full key.

Parameters

  • id string · path · requiredThe agent's `ag_…` id.

Body

  • summariseCalls booleanWrite a short summary after each call.
  • recordCalls booleanRecord each call.
  • collectFields arraynullThe details to fill from every call, replacing the list. An empty list (or null) stops collecting.
  • followUp objectThe message sent to the caller when a call ends. Partial: anything left out keeps what is saved. Set a channel with its list (`whatsappTemplates`, `smsTemplates`, up to 3 each, sent in order; an empty list stops it) or with the single field (`whatsapp`, `sms`), which replaces the list with that one template, or null to stop it. Not both for one channel.
curl -X PATCH "https://app.katexs.com/api/v1/agents/{id}/post-call" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Recordings

GET/api/v1/calls/{id}/recording

Get Call Recording

One call's audio as MP3, streamed — it plays inline, or with download=1 saves as call-{id}.mp3. Range requests are honoured so a player can seek, and nothing is cached. A recording lands about a minute after the call ends (404 with Retry-After until then) and is deleted when your plan's retention runs out (410): 30 days on Free and pay-as-you-go, 49 on Pro, 75 on Scale, 365 on Enterprise. Any id List Calls hands out works.

Parameters

  • id string · path · requiredThe call's `id` as Place Call or List Calls gave it: `out_…` or `sch_…` for a call you placed, the call reference for any other.
  • download string · query`1` to save the file (an attachment) rather than play it inline.
curl -X GET "https://app.katexs.com/api/v1/calls/{id}/recording" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/recordings/{callId}

Get Recording By Signed Link

The signed link a call report hands out as recording.url, for a CRM user to click: it needs no API key, because the signature is the permission. Use the URL exactly as the report gives it; add &download=1 to save rather than play. The link stops working at its expiresAt, which is when your plan deletes the recording. A forged link and an unknown call get the same 404. Answers are plain text, not JSON.

Parameters

  • callId string · path · requiredThe call's id as it appears in the signed link.
  • expires string · query · requiredWhen the link stops working, in Unix seconds — from the link.
  • sig string · query · requiredThe link's signature — from the link.
  • download string · query`1` to save the file (an attachment) rather than play it inline.
curl -X GET "https://app.katexs.com/api/v1/recordings/{callId}" \
  -H "Authorization: Bearer $API_KEY"

Conversations

GET/api/v1/conversations

List Conversations

Your workspace's conversations, newest first. since keeps only those a customer has written in at or after that moment — the way to find what a missed message.received webhook would have told you, including a conversation whose very first message you never heard about. Go back a few minutes from the last event you handled, since messages that arrive together can be delivered out of order.

Parameters

  • channel string · queryOnly conversations on this channel.
  • since string · queryISO 8601 date and time. Keeps conversations where the customer last wrote at or after this moment.
  • status string · queryOnly conversations in this state. `escalated` and `human_handling` are the threads waiting on your team.
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/conversations" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/conversations/{id}/messages

List Conversation Messages

One conversation's messages, newest first: the customer's, your agent's, and replies a teammate sent from the inbox (author: "teammate"). Your team's internal notes are left out. Photos, voice notes, videos and documents a customer sent come back as links valid for eight hours — download what you need to keep.

Parameters

  • id string · path · requiredThe conversation's id (`conv_…`), as the list and the `message.received` webhook give it.
  • since string · queryISO 8601 date and time. Keeps messages written after this moment.
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/conversations/{id}/messages" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/conversations/{id}/reply

Reply to Conversation

Your own agent platform answers a WhatsApp customer — the other half of the message.received webhook. Send exactly one of text, media, template or form; text, media and forms need the customer's 24-hour window open, a template does not. Only works on a number with Connect External Agent/CRM turned on, and not while a teammate has taken the conversation over. Each message is charged like any WhatsApp message from that number. Needs a full key.

Parameters

  • id string · path · requiredThe conversation's id (`conv_…`) — the `conversationId` in the `message.received` delivery.
curl -X POST "https://app.katexs.com/api/v1/conversations/{id}/reply" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/conversations/{id}/status

Update Conversation Status

The inbox's three moves: resolved marks it done and fires the conversation.resolved webhook, active hands it back to the agent, and human_handling takes it over so the agent stays quiet until it is handed back. An internal note records which API key made the change; the customer never sees it. changed: false means it was already in that state, and nothing was written or announced. The shared inbox needs a paid plan. A build key may do this.

Parameters

  • id string · path · requiredThe conversation's id (`conv_…`).

Body

  • status string · required`resolved`: mark it done (fires `conversation.resolved`). `active`: hand it back to the agent. `human_handling`: take it over — the agent stays quiet until it is handed back.
curl -X POST "https://app.katexs.com/api/v1/conversations/{id}/status" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
POST/api/v1/conversations/{id}/assign

Assign Conversation

Make a conversation a teammate's job, by their email — or null to put it back in the pool. The teammate is notified when it really moves to them. Assigning does not silence the agent; taking it over with Update Conversation Status does. List your teammates with GET /members. The shared inbox needs a paid plan. A build key may do this.

Parameters

  • id string · path · requiredThe conversation's id (`conv_…`).

Body

  • assignee stringnull · requiredA teammate's email address (any case), or `null` to unassign.
curl -X POST "https://app.katexs.com/api/v1/conversations/{id}/assign" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Messages

POST/api/v1/messages

Send Message

Sends one approved template to one number and records it in that customer's conversation. Marketing templates are refused for a customer who opted out; utility and authentication templates are not, since an order confirmation is not something a customer opts out of. Each send is charged like any WhatsApp template from your number, and the Free plan stops at its included messages. At most 60 sends a minute per workspace; send an Idempotency-Key so a retry never sends twice. Needs a full key.

Body

  • to string · requiredThe customer's number. Include the `+` and the country code (a leading `00` works too); spaces are fine. A number without its country code is refused: nothing is assumed to be Indian or anywhere else.
  • template string · requiredThe name of an approved template in your workspace. Templates are named, not given by id, so the name stays stable across edits.
  • language stringWhich approved language version to send, exactly as approved — `en`, `hi`, `en_US`. Leave it out for the oldest approved version, so adding a language in the console never changes what a working integration sends.
  • variables string[]Values for the body's `{{1}}`, `{{2}}` … in order. Numbers are sent as text. For an authentication template, the code goes here once — it is copied into the copy-code button for you.
  • buttonVariables string[]The value for a link button's placeholder. Separate from `variables` because WhatsApp addresses the button on its own. Leave it out on an authentication template.
  • headerMediaUrl stringA public link to the picture, video or document for a template with a media header. WhatsApp needs one on every send; leave it out and the template's own stored file is used.
  • formData objectPre-fills a WhatsApp form the template's button opens. Only fields the form marked pre-fillable reach the screen; other keys are ignored rather than refused. Values are sent as text.
  • idempotencyKey stringSame as the `Idempotency-Key` header, for clients that cannot set headers. The header wins when both are sent.
curl -X POST "https://app.katexs.com/api/v1/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

One-time codes

POST/api/v1/codes

Send One-Time Code

Sends a code you generated to a WhatsApp number, using your approved authentication template — the code goes into the message and the copy-code button. We do not generate, store, expire or check the code; that stays yours. One number may be sent at most 5 codes in 10 minutes, and the workspace at most 120 sends a minute (codes keep the top of the budget it shares with Send Message). Each code is charged at WhatsApp's authentication rate, which is far higher for numbers abroad. Needs a full key.

Body

  • to string · requiredThe number to send the code to. Include the `+` and the country code (a leading `00` works too); spaces are fine. A number without its country code is refused: nothing is assumed to be Indian or anywhere else.
  • code string · requiredThe code you generated, 16 characters at most after trimming.
  • template stringWhich approved authentication template, by name. Needed only when you have more than one.
  • language stringWhich approved language version, exactly as approved — `en`, `hi`. Needed only when one template name is approved in several languages.
  • idempotencyKey stringSame as the `Idempotency-Key` header, for clients that cannot set headers. The header wins when both are sent.
curl -X POST "https://app.katexs.com/api/v1/codes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/codes/templates

List Code Templates

Your workspace's authentication templates — drafts, those in review and approved ones — newest first.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/codes/templates" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/codes/templates

Create Code Template

Saves an authentication template as a draft. WhatsApp writes the words; you choose how long the code lasts, whether to add "For your security, do not share this code.", and the button — copy_code (works everywhere) or one_tap (hands the code to your Android app, which needs apps). Nothing is sent to WhatsApp until Submit Code Template. A build key may do this.

Body

  • name string · requiredLowercase letters, digits and underscores, as WhatsApp allows. Unique with `language`.
  • language string · requiredA WhatsApp template language code.
  • expiryMinutes integerHow long the code lasts. WhatsApp shows it to the customer in their own language.
  • securityRecommendation booleanAdds "For your security, do not share this code."
  • button string`copy_code`: the customer taps to copy, then pastes — works everywhere. `one_tap`: hands the code straight to your Android app; needs `apps`.
  • apps object[]Required for `one_tap`: the Android apps the code may be handed to. Ignored for `copy_code`.
curl -X POST "https://app.katexs.com/api/v1/codes/templates" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/codes/templates/{id}

Get Code Template

One authentication template, with its review status and WhatsApp's reason when it was rejected.

Parameters

  • id string · path · requiredThe template's id — a bare uuid, as the list gives it.
curl -X GET "https://app.katexs.com/api/v1/codes/templates/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/codes/templates/{id}

Update Code Template

Changes any of a draft's fields; the ones you leave out keep their values. Once a template has been submitted, WhatsApp has the text and it can no longer be edited — make a new one instead. A build key may do this.

Parameters

  • id string · path · requiredThe template's id — a bare uuid, as the list gives it.

Body

  • name stringLowercase letters, digits and underscores.
  • language stringA WhatsApp template language code.
  • expiryMinutes integerHow long the code lasts.
  • securityRecommendation booleanAdds "For your security, do not share this code."
  • button stringHow the code gets into your app.
  • apps object[]The Android apps a `one_tap` code is handed to. Replaces the list.
curl -X PATCH "https://app.katexs.com/api/v1/codes/templates/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/codes/templates/{id}

Delete Code Template

Deletes the template — at WhatsApp first when it was submitted, then here. WhatsApp keeps a deleted template's name reserved for 30 days, so a replacement needs a different name. Codes stop sending at once if this was your only approved one. A build key may do this.

Parameters

  • id string · path · requiredThe template's id — a bare uuid, as the list gives it.
curl -X DELETE "https://app.katexs.com/api/v1/codes/templates/{id}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/codes/templates/{id}/submit

Submit Code Template

Sends a draft to WhatsApp for review, on your workspace's own WhatsApp Business Account — so a connected number is needed first. The status moves to pending only when WhatsApp took it. Review usually takes minutes; a template.* webhook and Get Code Template tell you how it went. A build key may do this.

Parameters

  • id string · path · requiredThe template's id — a bare uuid, as the list gives it.
curl -X POST "https://app.katexs.com/api/v1/codes/templates/{id}/submit" \
  -H "Authorization: Bearer $API_KEY"

Contacts

GET/api/v1/contacts

List Contacts

Contacts with a phone number, newest first. Filter by tag, by your CRM's id, or by phone to look one person up. Contacts folded into another by a merge are left out.

Parameters

  • tag string · queryOnly contacts carrying this tag. Normalised as tags are stored — `Hot Lead` matches `hot-lead`.
  • group string · queryOnly contacts in this contact group, `grp_…`.
  • externalId string · queryOnly the contact with this CRM id.
  • phone string · queryOnly the contact on this number, with its country code, in any format a person would type it (`+91 98765 43210`, `+44 7700 900123`).
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/contacts" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/contacts

Create Contact

Creates a contact — or, when someone is already on that number, updates that person instead, so a CRM that syncs the same lead twice never doubles your list. Answers 201 for a new contact and 200 for one it updated. Creating a contact is not consent: only consent.status: "granted" with a source is. A build key may do this.

Body

  • phone string · requiredTheir number, with its country code (`+44 7700 900123`, `+91 98765 43210`); spaces are fine. A number without its country code is refused. The number is the contact's identity: a second create on it updates the first.
  • name stringnullTheir name.
  • email stringnullTheir email. Stored lower-cased.
  • externalId stringnullYour CRM's id for them, unique in your workspace. `GET /contacts?externalId=` finds them by it.
  • tags string[]Tags, normalised as the console stores them: lower case, spaces to hyphens, duplicates dropped, 40 characters and 20 tags at most. Replaces the list.
  • language stringnullThe language to write to them in, by its English name as the console offers it, `auto` to match theirs, or `null`.
  • note stringnullFree-text notes about them.
  • consent objectTheir word on marketing messages, recorded with the time and where it came from — what a regulator asks.
  • fields objectDetails to set on the contact, by name (`Visit Date` is stored as `visit_date`). Merged into what they already have; `null` or an empty string clears one. At most 30, each up to 300 characters.
curl -X POST "https://app.katexs.com/api/v1/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/contacts/{id}

Get Contact

One contact, by id.

Parameters

  • id string · path · requiredThe contact's id (`cust_…`).
curl -X GET "https://app.katexs.com/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/contacts/{id}

Update Contact

Changes any of the fields Create Contact takes, consent included; fields you leave out keep their values, and null clears a field. tags replaces the whole list. A contact whose consent is withdrawn is never sent marketing, enrolled in a sequence or put in a campaign. A build key may do this.

Parameters

  • id string · path · requiredThe contact's id (`cust_…`).

Body

  • phone stringA new number for them. Normalised as on create.
  • name stringnullTheir name, or `null` to clear it.
  • email stringnullTheir email, or `null` to clear it.
  • externalId stringnullYour CRM's id, or `null` to clear it.
  • tags string[]Replaces the whole list. Normalised as on create.
  • language stringnullThe language to write to them in, `auto`, or `null`.
  • note stringnullFree-text notes, or `null` to clear them.
  • consent objectTheir word on marketing messages, recorded with the time and where it came from — what a regulator asks.
  • fields objectDetails to set on the contact, by name (`Visit Date` is stored as `visit_date`). Merged into what they already have; `null` or an empty string clears one. At most 30, each up to 300 characters.
curl -X PATCH "https://app.katexs.com/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/contacts/{id}

Delete Contact

Erases the contact: their conversations and transcripts, their calls, any queued call and their campaign rows go with them, and so does any duplicate that was merged into them. This cannot be undone. Use it for a person's request to be forgotten; to stop messaging someone, set their consent to withdrawn instead. A build key may do this.

Recordings are erased too. The audio of their calls is deleted before the call rows go: a recording we store is deleted right away, the phone provider's copy of a call on a number we rent is deleted through your workspace's own account with them, and any copy made for model training is deleted. A file that cannot be deleted at that moment is queued and retried every night until it is gone; the contact is erased regardless, and the response says how many are still queued in recordingsPending.

Knowing when it is finished. Subscribe a webhook to contact.erased: it is sent once the erasure is complete — straight away when this answers 204, or from the nightly retry once the last queued recording is gone — with only the contact's id and when it was erased.

What is not erased. Do-not-call entries are kept deliberately, so the person is not called again. Webhook payloads we already sent are purged on their own schedule after 7 days. Copies in your own systems, and in your vendors', are yours to delete.

Parameters

  • id string · path · requiredThe contact's id (`cust_…`).
curl -X DELETE "https://app.katexs.com/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $API_KEY"

Do not call

GET/api/v1/do-not-call

List Do-Not-Call Numbers

The workspace's do-not-call list, newest first.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/do-not-call" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/do-not-call

Add Do-Not-Call Number

Puts a number on the list; from then on no outbound call rings it. Adding a number already there changes nothing and answers 200 with the entry as it was. A build key may do this — it only ever stops calls.

Body

  • phone string · requiredThe number, with its country code. Spaces, dashes and brackets are ignored; a number without a country code is refused.
  • reason stringnullWhy, in your own words — kept for whoever later wonders whether to remove it. 200 characters at most.
curl -X POST "https://app.katexs.com/api/v1/do-not-call" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/do-not-call/{phone}

Get Do-Not-Call Number

Whether a number is on the list, and how it got there.

Parameters

  • phone string · path · requiredThe number with its country code, digits only or with a leading `+` (`%2B` in a URL).
curl -X GET "https://app.katexs.com/api/v1/do-not-call/{phone}" \
  -H "Authorization: Bearer $API_KEY"
DELETE/api/v1/do-not-call/{phone}

Remove Do-Not-Call Number

Takes a number off the list, so it can be called again. Needs a full key. If the person asked on a call not to be called (source: call), be sure they have since agreed before removing it.

Parameters

  • phone string · path · requiredThe number with its country code, digits only or with a leading `+` (`%2B` in a URL).
curl -X DELETE "https://app.katexs.com/api/v1/do-not-call/{phone}" \
  -H "Authorization: Bearer $API_KEY"

Events

POST/api/v1/events

Report Event

Tells us something happened to a customer. Every sequence or tag rule subscribed to that event name runs: sequences that stop on it end first, then tags are added or removed, then sequences that start on it enrol the contact (unless they opted out, and only into an active sequence). The contact is created if the number is new. Nothing subscribed is still a 200, with matched: false — you can send events before anyone has set up what they do. Only send events for people who agreed to hear from you: an event that starts a sequence is taken as their opt-in. Needs a full key.

Body

  • to string · requiredThe customer's number, with or without the `+`; spaces are fine. Matched to a contact by its digits; a new number creates a contact.
  • event string · requiredWhat happened, as a name. Normalised and echoed back — lower case, anything but letters, digits, `.`, `-` and `_` becomes a dot, 60 characters at most — so "Order Delivered" is stored as `order.delivered`. Subscribe to the name that comes back.
  • data objectValues to carry into the sequences this starts, for their templates to use — an order number, a courier. At most 20; each name 1–60 characters (a longer one is refused); values are text, numbers or true/false, stored as text and cut at 300 characters. An object or list as a value is refused.
  • name stringThe customer's name, if you have it. Used for a contact this call creates, or one with no name yet. Cut at 120 characters.
curl -X POST "https://app.katexs.com/api/v1/events" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Templates

GET/api/v1/templates

List Templates

Lists your workspace's WhatsApp templates, newest first, with what a send needs from each: how many body values (variableCount), how many link-button values (buttonVariableCount) and whether the header needs a media link (headerKind). Only approved templates can be sent.

Parameters

  • status string · queryOnly templates in this review state.
  • category string · queryOnly templates of this category.
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/templates" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/templates

Create Template

Saves a WhatsApp template as a draft, after the console's own checks of WhatsApp's rules for the body, header, footer, buttons and an authentication template's code. Review is a separate, deliberate step — Submit Template, or submit: true here — because once a name is approved it can never be reused for different words; if that submission is refused, the draft is kept and message says why. Limited-time offers, carousels and buttons that open a WhatsApp form are made in the console. Needs a full key.

Body

  • name string · requiredLowercase letters, numbers and underscores only. Unique per language in your workspace.
  • language stringA language WhatsApp templates support, such as `en`, `en_US` or `hi`.
  • category string · required`utility` for something the customer is expecting (an order or appointment update), `marketing` for promotions, `authentication` for one-time codes.
  • body stringThe message, with blanks numbered `{{1}}`, `{{2}}` … in order. A blank cannot be at the very start or end, two cannot sit next to each other, and there must be enough words around them. Required unless `category` is `authentication`, where WhatsApp writes the body.
  • samples string[]One example value per body blank, in order. WhatsApp's reviewers read the template with these filled in, so every blank needs one.
  • header objectnullThe line or media above the body. `null` means no header.
  • footer stringnullOne line of small print, with no blanks. A marketing template needs a way to opt out — "Reply STOP to opt out" here, or a quick-reply button.
  • buttons arraynullThe template's buttons, in order.
  • auth objectAn authentication template's settings. WhatsApp writes the message itself ("*123456* is your verification code."), so these are all you choose.
  • agent stringnullThe agent the template belongs to (`ag_…`). Leave it out for the agent on your connected WhatsApp number (or your oldest agent).
  • submit boolean`true` also sends it to WhatsApp for review, as Submit Template does. If that is refused, the draft is kept and `message` says why.
curl -X POST "https://app.katexs.com/api/v1/templates" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/templates/{name}

Get Template

Returns one WhatsApp template by name, with its parts — header text, footer, buttons — and, when WhatsApp refused it, the reason in reviewNote. Poll it after Submit Template to follow the review: status moves from pending to approved or rejected. Pass language when the name exists in more than one.

Parameters

  • name string · path · requiredThe template's name: lowercase letters, numbers and underscores.
  • language string · queryThe template's language code. Needed only when the name exists in more than one language; without it such a name is a `409` that lists them.
curl -X GET "https://app.katexs.com/api/v1/templates/{name}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/templates/{name}

Update Template

Edits a draft template. Send only the fields that change; the result is checked against the same rules as Create Template. Once a template has been sent for review WhatsApp has its text, so it can no longer be edited — create a new template instead. Changing name or language renames it. A build key may do this. The one exception is agentMaySend (whether an agent may send the template in a call or chat): it goes alone and needs a full key.

Parameters

  • name string · path · requiredThe template's name: lowercase letters, numbers and underscores.
  • language string · queryThe template's language code. Needed only when the name exists in more than one language; without it such a name is a `409` that lists them.

Body

  • name stringA new name: lowercase letters, numbers and underscores only.
  • language stringA new language code WhatsApp templates support, such as `en`, `en_US` or `hi`.
  • category stringA new category.
  • body stringThe new message, with `{{1}}`, `{{2}}` … for the blanks. Ignored for an authentication template.
  • samples string[]One example per body blank, in order. Leave it out to keep the current examples.
  • header objectnullThe line or media above the body. `null` means no header.
  • footer stringnullThe new footer. `null` or `""` removes it.
  • buttons arraynullThe full new list of buttons, replacing the old one. `null` or `[]` removes them all.
  • auth objectAn authentication template's settings. WhatsApp writes the message itself ("*123456* is your verification code."), so these are all you choose.
  • agentMaySend booleanLet an agent send this template during a call or chat, or stop it. Send it **alone**, not with other fields; it applies to every language of the name, only a Utility template whose link buttons are fixed can be allowed, and it needs a **full** key because it decides what an agent may message customers with.
curl -X PATCH "https://app.katexs.com/api/v1/templates/{name}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/templates/{name}

Delete Template

Deletes a WhatsApp template. One that was sent for review is deleted from WhatsApp first — only that language — and from your workspace only once that works, so a refusal leaves everything as it was. This cannot be undone, and WhatsApp may keep a deleted name reserved for a while, so it may not be reusable straight away. Needs a full key.

Parameters

  • name string · path · requiredThe template's name: lowercase letters, numbers and underscores.
  • language string · queryThe template's language code. Needed only when the name exists in more than one language; without it such a name is a `409` that lists them.
curl -X DELETE "https://app.katexs.com/api/v1/templates/{name}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/templates/{name}/submit

Submit Template

Sends a draft template to your own WhatsApp Business Account for review, after the same last checks as the console's Submit. The template moves to pending only if WhatsApp accepted it. Review usually takes minutes, occasionally days; follow it with Get Template, whose status becomes approved or rejected (with the reason in reviewNote). A workspace with no connected WhatsApp number has no account to submit to. Needs a full key.

Parameters

  • name string · path · requiredThe template's name: lowercase letters, numbers and underscores.
  • language string · queryThe template's language code. Needed only when the name exists in more than one language; without it such a name is a `409` that lists them.
curl -X POST "https://app.katexs.com/api/v1/templates/{name}/submit" \
  -H "Authorization: Bearer $API_KEY"

Campaigns

GET/api/v1/campaigns

List Campaigns

Lists your workspace's broadcasts and calling campaigns, newest first, each with its live counts: recipients, sent, delivered, read, replied, failed and skipped. Filter by status to watch only the ones that are sending.

Parameters

  • status string · queryOnly campaigns in this state. A scheduled campaign is a `draft` with `scheduledAt` set until it starts.
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/campaigns" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/campaigns

Create Campaign

Creates a WhatsApp broadcast (kind: "whatsapp") or a calling campaign (kind: "voice") as a draft, with the same checks as the console's builder: WhatsApp connected and the template approved with every blank filled, or for calls an agent with a number that answers phone calls and is licensed for this kind of call. The audience is built from your contacts right away, by consent; people who asked not to be contacted are always left out. Send launch: true to start it at once, or scheduledAt to start it later; a launch that is refused (no paid plan, not enough balance) still leaves the draft and says why in message, and an audience of nobody is never launched. Needs a full key.

curl -X POST "https://app.katexs.com/api/v1/campaigns" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/campaigns/{id}

Get Campaign

Returns one broadcast or calling campaign with its current state and counts. Poll it while a campaign is sending to follow its progress; finishedAt is set when it ends or is cancelled, and lastError says why a campaign stopped, when it did.

Parameters

  • id string · path · requiredThe campaign's id (`cmp_…`), as Create Campaign and List Campaigns return it.
curl -X GET "https://app.katexs.com/api/v1/campaigns/{id}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/campaigns/{id}/launch

Launch Campaign

Starts a draft, as the console's Send or Start button does, re-running its checks at the moment they matter: your plan must include campaigns, a calling campaign's agent must still have a number that answers phone calls (and, for promotional calls, is licensed for them), and your balance must cover the send. If the balance covers only part of it, the campaign starts and message says how far it goes; the rest stays queued until you top up. Messages go out in the background; calls are paced by your free call lines. A campaign already sending answers 200 and is left alone, and a scheduled draft launched here starts now instead of waiting. Needs a full key.

Parameters

  • id string · path · requiredThe campaign's id (`cmp_…`), as Create Campaign and List Campaigns return it.
curl -X POST "https://app.katexs.com/api/v1/campaigns/{id}/launch" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/campaigns/{id}/pause

Pause Campaign

Stops a sending campaign from sending any more. Messages already handed to WhatsApp, and calls already placed, still complete. Resume Campaign picks up where it stopped, without messaging anyone twice. Only a sending campaign can be paused. A build key may do this, since it only ever stops sends.

Parameters

  • id string · path · requiredThe campaign's id (`cmp_…`), as Create Campaign and List Campaigns return it.
curl -X POST "https://app.katexs.com/api/v1/campaigns/{id}/pause" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/campaigns/{id}/resume

Resume Campaign

Sends a paused campaign again, to everyone it has not reached yet; nobody is messaged or called twice. It clears lastError, and what it sends is charged as usual. Only a paused campaign can be resumed; a draft is started with Launch Campaign. Needs a full key.

Parameters

  • id string · path · requiredThe campaign's id (`cmp_…`), as Create Campaign and List Campaigns return it.
curl -X POST "https://app.katexs.com/api/v1/campaigns/{id}/resume" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/campaigns/{id}/cancel

Cancel Campaign

Stops a draft, sending or paused campaign for good and sets finishedAt. Messages already handed to WhatsApp, and calls already placed, still complete. This cannot be undone, and it is also how you get rid of a draft you do not want: campaigns cannot be edited or deleted, so cancel it and create a new one. A build key may do this, since it only ever stops sends.

Parameters

  • id string · path · requiredThe campaign's id (`cmp_…`), as Create Campaign and List Campaigns return it.
curl -X POST "https://app.katexs.com/api/v1/campaigns/{id}/cancel" \
  -H "Authorization: Bearer $API_KEY"

Sequences

GET/api/v1/sequences

List Sequences

Your workspace's sequences, newest first. Deleted (archived) ones are left out. Get Sequence adds the steps, events and how many people are in each.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/sequences" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/sequences

Create Sequence

Creates a sequence as a draft: it sends nothing until you add a step with Add Sequence Step and turn it on with Activate Sequence. Tags are stored lower-case and hyphenated, and event names lower-case with dots, as the console stores them. A build key may do this.

Body

  • agent string · requiredThe agent whose sequence this is (`ag_…`). Cannot be changed later.
  • name string · requiredWhat you call it.
  • exitOnReply booleanWhether a reply from the customer takes them out.
  • triggerTags string[]Tagging a contact with one of these enrols them. Normalised like contact tags.
  • exitOnTags string[]Tagging someone in it with one of these takes them out.
  • startOn string[]Event names (Report Event) that enrol the contact. Normalised like event names: "Order Delivered" becomes `order.delivered`.
  • stopOn string[]Event names that take them out. An event cannot be in both lists.
curl -X POST "https://app.katexs.com/api/v1/sequences" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/sequences/{sequenceId}

Get Sequence

One sequence with its steps in order, the events that start and stop it, and how many people are in it, finished it or left it.

Parameters

  • sequenceId string · path · requiredThe sequence's id — a bare uuid.
curl -X GET "https://app.katexs.com/api/v1/sequences/{sequenceId}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/sequences/{sequenceId}

Update Sequence

Changes any of name, exitOnReply, triggerTags, exitOnTags, startOn and stopOn. A list you send replaces the old one; a list you leave out is kept. Works while the sequence runs, and applies to the people already in it — add a stop tag and they stop when they get it. Steps cannot be changed here. A build key may do this.

Parameters

  • sequenceId string · path · requiredThe sequence's id — a bare uuid.

Body

  • name stringWhat you call it.
  • exitOnReply booleanWhether a reply from the customer takes them out.
  • triggerTags string[]Replaces the enrolling tags.
  • exitOnTags string[]Replaces the exit tags.
  • startOn string[]Replaces the events that enrol the contact.
  • stopOn string[]Replaces the events that take them out. Checked against `startOn` as stored when you send only one side.
curl -X PATCH "https://app.katexs.com/api/v1/sequences/{sequenceId}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/sequences/{sequenceId}

Delete Sequence

Archives the sequence, which is how the console deletes one: it sends nothing more and leaves every list, while the record of who was sent what stays. There is no undo. A build key may do this.

Parameters

  • sequenceId string · path · requiredThe sequence's id — a bare uuid.
curl -X DELETE "https://app.katexs.com/api/v1/sequences/{sequenceId}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/sequences/{sequenceId}/steps

Add Sequence Step

Appends a message at the end of the sequence: an approved template, sent delayHours after the step before (or after the person joined, for the first step). Steps cannot be edited, reordered or removed — someone partway through a live sequence would skip a message or get one twice — so to change the messages, delete the sequence and make another. A build key may do this.

Parameters

  • sequenceId string · path · requiredThe sequence's id — a bare uuid.

Body

  • template string · requiredThe name of an approved WhatsApp template in your workspace. The sequence's own agent's template wins when two agents share a name.
  • language stringnullWhich approved language version, e.g. `en` or `hi`. Needed only when the name is approved in more than one language.
  • delayHours numberHours after the step before — or after joining, for the first step. Up to 2,160 (ninety days); rounded to a whole hour.
curl -X POST "https://app.katexs.com/api/v1/sequences/{sequenceId}/steps" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
POST/api/v1/sequences/{sequenceId}/activate

Activate Sequence

Turns a draft or paused sequence on: messages that fall due start going out, and its tags and events start enrolling people. Refused for a sequence with no steps, which would take people in and send nothing. Needs a full key.

Parameters

  • sequenceId string · path · requiredThe sequence's id — a bare uuid.
curl -X POST "https://app.katexs.com/api/v1/sequences/{sequenceId}/activate" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/sequences/{sequenceId}/pause

Pause Sequence

Pauses an active sequence: nothing more is sent until it is activated again. The people in it keep their place. A build key may do this.

Parameters

  • sequenceId string · path · requiredThe sequence's id — a bare uuid.
curl -X POST "https://app.katexs.com/api/v1/sequences/{sequenceId}/pause" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/sequences/{sequenceId}/enrolments

Enrol in Sequence

Puts one existing contact into a sequence, with values its messages can use — an order number your system knows and the console does not. The person must already be a contact; this never creates one. enrolled: false is a 200, not an error: they are already in it, the number is not a contact, they opted out, or the sequence has no first message yet. Prefer Report Event unless your system must choose the sequence itself, since this puts a sequence id in your code. Only enrol people who agreed to hear from you. Needs a full key.

Parameters

  • sequenceId string · path · requiredThe sequence's id — a bare uuid.

Body

  • to string · requiredThe contact's number, with or without the `+`. Matched to an existing contact by its digits.
  • variables objectValues the sequence's messages can use. At most 20; each name 1–60 characters (a longer one is refused); values are text, numbers or true/false, stored as text and cut at 300 characters. An object or list as a value is refused.
curl -X POST "https://app.katexs.com/api/v1/sequences/{sequenceId}/enrolments" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Forms

GET/api/v1/forms

List Forms

Your workspace's WhatsApp forms, newest first, published or not.

Parameters

  • agent string · queryOnly this agent's forms (`ag_…`).
  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/forms" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/forms

Create Form

Saves a form, unpublished — it cannot be sent until Publish Form succeeds. Up to 8 questions; field names are what each answer comes back under. Without agent, the form goes to the agent holding your WhatsApp number, else your oldest agent. No connected number is needed to build one. A build key may do this.

Body

  • name string · requiredWhat you call it, unique per agent. Customers never see it — but Reply to Conversation can send a form by this name.
  • form object · required
  • category stringWhatsApp's category for it. Affects reporting only.
  • agent stringnullThe agent it belongs to (`ag_…`). Leave it out for the agent holding your WhatsApp number, else your oldest agent. Cannot be changed later.
curl -X POST "https://app.katexs.com/api/v1/forms" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/forms/{id}

Get Form

One form, with its questions and whether it can be sent.

Parameters

  • id string · path · requiredThe form's id (`form_…`).
curl -X GET "https://app.katexs.com/api/v1/forms/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/forms/{id}

Update Form

Changes any of name, category and form (form is replaced whole). Any change unpublishes the form, as saving does in the console — the published copy still asks the old questions — so publish it again before sending it. A build key may do this.

Parameters

  • id string · path · requiredThe form's id (`form_…`).

Body

  • name stringWhat you call it.
  • category stringWhatsApp's category for it.
  • form object
curl -X PATCH "https://app.katexs.com/api/v1/forms/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/forms/{id}

Delete Form

Deletes the form; it can no longer be sent. Answers already collected stay, marked as from a removed form. A build key may do this.

Parameters

  • id string · path · requiredThe form's id (`form_…`).
curl -X DELETE "https://app.katexs.com/api/v1/forms/{id}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/forms/{id}/publish

Publish Form

Publishes the form to your workspace's own WhatsApp Business Account, which makes it sendable. Needs a connected WhatsApp number whose connection was finished. If WhatsApp refuses (most often because the business is not verified yet), the form stays saved and you can publish again later; a failed republish leaves the live version on the air. Needs a full key.

Parameters

  • id string · path · requiredThe form's id (`form_…`).
curl -X POST "https://app.katexs.com/api/v1/forms/{id}/publish" \
  -H "Authorization: Bearer $API_KEY"

Phone numbers

GET/api/v1/phone-numbers

List Phone Numbers

Every number this workspace can call from or be called on — rented and brought — with the agent that answers each. Not paged. label is always null here for a brought number; Get Phone Number reads it.

curl -X GET "https://app.katexs.com/api/v1/phone-numbers" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/phone-numbers

Rent Phone Number

Rents a number from Search Available Phone Numbers. This costs money: the first month's rent (the monthlyPrice the search showed) is charged from your balance at once, and again every month on the same day until you release the number. Every refusal happens before anything is bought or charged. An Indian number also needs your business details sent and approved first (Send Business Details, or the console's Phone Numbers page). The number arrives answered by nobody — Update Phone Number points it at an agent. Send an Idempotency-Key so a retry cannot rent twice: a repeat returns the first answer with Idempotent-Replayed: true, and a request that failed lets the same key try again. Needs a full key.

Body

  • number string · requiredA number from Search Available Phone Numbers, in any spelling.
curl -X POST "https://app.katexs.com/api/v1/phone-numbers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/phone-numbers/{number}

Get Phone Number

One number this workspace holds: who answers it, who calls out on it, and its name. A number held by another workspace is 404, the same as one that does not exist.

Parameters

  • number string · path · requiredThe number, in any spelling — compared on its digits (8 to 15 of them). Encode a leading `+` as `%2B`, or leave it out.
curl -X GET "https://app.katexs.com/api/v1/phone-numbers/{number}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/phone-numbers/{number}

Update Phone Number

Points a number at an agent, lends it to one for calling out, names it, forwards its calls, or chooses who answers a ring-back — any of the five. agent makes the number that agent's line (it stops being any other agent's; the agent must have voice switched on); callingAgent lets an agent call out on it without answering it (a brought number needs its carrier account's keys saved first); forwardTo sends every call to another phone, and works whether or not an agent answers the number (in the console: Numbers page, the number's menu, Forward calls); ringBack: last_caller sends a person ringing the number back to the agent that last called them from it. They are applied in the order label, agent, callingAgent, forwardTo, ringBack, and a refusal stops there with the earlier changes kept. Needs a full key.

Parameters

  • number string · path · requiredThe number, in any spelling — compared on its digits (8 to 15 of them). Encode a leading `+` as `%2B`, or leave it out.

Body

  • label stringnullA name for the number. `null` or `""` removes it.
  • agent stringnullThe agent that answers the number (`ag_…`): it becomes that agent's line and stops being any other's. The agent must have voice switched on. `null` makes nothing answer it.
  • callingAgent stringnullThe agent that calls out on the number without answering it (`ag_…`) — campaigns spread their calls over an agent's numbers. `null` takes it back. Where the number answers is unchanged.
  • forwardTo stringnullForward every call to this number to this phone (E.164, like `+919812345678`) without the agent answering — a fallback for when the agent is not working. It rings for 30 seconds. If nobody picks up, a caller on a number from us, Plivo or Twilio hears that nobody could take the call; a caller on a number brought from Telnyx gets no spoken message — the line rings out or returns busy, then ends. A call that is picked up is cut off at its limit: on a number rented here, when the balance can no longer pay for it and never later than 20 minutes (the platform's maximum call length); on a number you brought, after 30 minutes. Premium-rate, shared-cost, toll-free, satellite and some high-cost international destinations are refused (`forward_destination_not_allowed`, 422). It works whether or not an agent answers the number: with an agent, the forward replaces it; with none (never attached, deleted, or its voice switched off) the forward answers the call itself, so the number never goes quiet. A workspace that cannot pay for a call, or has no free call line, does not forward - the caller hears that the number is not answering. Billed like a call put through to a person: every connected minute on a number rented here (at the voice plan of the agent attached to the number, or the Premium plan when no agent is; under your own keys, the flat own-key price of that set), nothing on a number you brought. A forwarded call is not recorded. Cannot be this number or another number on the platform. `null` stops forwarding.
  • ringBack stringWho answers a person ringing this number back: `inbound` (the agent that answers the number) or `last_caller` (the agent that called them from this number in the last 30 days, else the usual answer). Lets several agents share one number and still get their own ring-backs.
curl -X PATCH "https://app.katexs.com/api/v1/phone-numbers/{number}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/phone-numbers/{number}

Release Phone Number

Gives a number up; either way it stops being any agent's line and leaves every agent's calling pool. A brought number is simply forgotten: it stays yours on your own carrier account, and calls to it are declined until you repoint it. A rented number is released, permanently: it goes back to the pool, anybody may rent it next, and this month's rent is not refunded — so it is refused unless you add ?confirm=release. Needs a full key.

Parameters

  • number string · path · requiredThe number, in any spelling — compared on its digits (8 to 15 of them). Encode a leading `+` as `%2B`, or leave it out.
  • confirm string · queryRequired to release a rented number: `release`. Ignored for a brought number.
curl -X DELETE "https://app.katexs.com/api/v1/phone-numbers/{number}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/phone-numbers/{number}/move

Move Phone Number

In the console, developers do this from the Numbers page: open the number's menu and choose Move to another workspace….

Moves a number, keeping its digits, from the workspace the request runs in to another workspace of the same developer: the developer's own, or any of its customers. Send it from the developer's own workspace, or as the customer that holds the number with X-Workspace; a key made for one customer cannot. The number leaves every agent and calling pool where it was and arrives answered by nobody — point it with PATCH /phone-numbers/{number} (as the target workspace) once it is there.

Rent continues from the next period on the target. The month already paid is not charged again, and inside one developer both workspaces bill the developer, so no money moves.

An Indian number is held in the name of the business using it: the target workspace's business details must be approved first (PUT /phone-numbers/business-details as that workspace), and the move re-registers the number to that business.

A brought number (on your own carrier account) moves only when both workspaces have that same account's keys saved. Refused while the number is on a call. Safe to retry: repeating a move that already succeeded to the same workspace answers the same 200 (for a day). Needs a full key.

Parameters

  • number string · path · requiredThe number, in any spelling — compared on its digits (8 to 15 of them). Encode a leading `+` as `%2B`, or leave it out.

Body

  • toWorkspace string · requiredThe `org_…` id of the workspace to move it to: the developer's own, or one of its customers.
curl -X POST "https://app.katexs.com/api/v1/phone-numbers/{number}/move" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/phone-numbers/business-details

Get Business Details

Where this workspace's business details stand. India issues a number only to a business it has approved, in the business's own name, so there is one application per workspace — a platform with a workspace per customer sends and reads each customer's own (with the X-Workspace header). Returns { "status": "none" } until details are sent. canRent is true once the details are approved (accepted) — the point from which an Indian number can be rented. reviewNote appears when the application was rejected and says what to correct. businessName is null if the application's name could not be read just now. The document itself is never returned. Any key can read this; the status is checked live, so it is current. Checks usually finish in minutes.

curl -X GET "https://app.katexs.com/api/v1/phone-numbers/business-details" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/phone-numbers/business-details

Send Business Details

Sends the business's details for approval, as multipart/form-data: the legal name, whether it is registered for GST, and one document — the GST certificate if it is, otherwise its Certificate of Incorporation or its Udyam certificate (say which in documentKind; incorporation is assumed). PDF, JPG or PNG, at most 5 MB, filename at most 99 characters. This is the Business details form in the console, run by the same code. The details go to India's numbering authority in the business's name, so this needs a full key. There is one live application per workspace: sending while one is being checked, or after it was approved, is 409; sending after a rejected one corrects that application in place (200), and a first or expired one creates a new application (201). Approval usually takes a few minutes — read it with Get Business Details, then rent the number. Needs a paid plan.

curl -X PUT "https://app.katexs.com/api/v1/phone-numbers/business-details" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/phone-numbers/available

Search Available Phone Numbers

Local numbers you can rent in your workspace's region (Indian numbers for a workspace billed in India, United States numbers for one billed anywhere else), each with its monthly rent at your plan's rate in your balance's currency. Numbers somebody already holds are left out, so a page (up to twenty) can hold fewer and still have more after it: pass nextCursor back as cursor. Needs a paid plan.

Parameters

  • pattern string · queryUp to ten digits that follow the country code — an area code, such as `80` for Bengaluru or `415` for San Francisco.
  • city string · queryA city (India) or a state (United States), spelled exactly as List Available Cities lists it.
  • cursor string · queryThe `nextCursor` from the page before. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/phone-numbers/available" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/phone-numbers/available/cities

List Available Cities

The cities (India) or states (United States) Search Available Phone Numbers accepts as city, with how many numbers each has. Use these spellings exactly: "Bangalore" finds numbers where "Bengaluru" finds none, and a state is its full name ("California"). Empty on the Free plan or when the stock cannot be reached. Not paged.

curl -X GET "https://app.katexs.com/api/v1/phone-numbers/available/cities" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/phone-numbers/import

Import Phone Number

Brings a number you own on your own carrier account. It stays on your account and you keep paying your carrier for it; we never bill it. For carriers that sign their calls with your account's secret, save the account's keys first (Save Carrier Account) — we also use them to check the number is really on that account. setup says what is left to do: where the number must send its calls, and whether we pointed it there ourselves. Bringing the same number again is not an error; it corrects provider. The number arrives answered by nobody — Update Phone Number points it at an agent. Needs a paid plan and a full key.

Body

  • number string · requiredThe number in E.164 (`+14155550100`). Include the country code: a number without one is refused.
  • provider string · requiredA carrier a brought number can be on — whose network your own account is with.
curl -X POST "https://app.katexs.com/api/v1/phone-numbers/import" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/phone-numbers/carrier-accounts

List Carrier Accounts

Your own carrier accounts we hold verified keys for — the accounts your brought numbers live on — each by the last four characters of its account id, never any part of the secret. A carrier missing from the list has no keys saved: its brought numbers can answer calls (where the carrier allows) but not call out. Not paged.

curl -X GET "https://app.katexs.com/api/v1/phone-numbers/carrier-accounts" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/phone-numbers/carrier-accounts/{provider}

Save Carrier Account

Saves the keys of your own account with a carrier, which lets its brought numbers be confirmed, answered and called out from. The keys are checked with the carrier before anything is stored, stored sealed, and never returned. One account per carrier: switching to a different account while numbers are still brought on the first is refused. telnyx takes its API key as token alone. Needs a full key — a carrier credential can spend money on your account.

Parameters

  • provider string · path · requiredWhich carrier the account is with.

Body

  • accountId stringYour account's id (its Auth ID or Account SID). Required for every carrier but `telnyx`, which ignores it.
  • token string · requiredThe account's secret: its auth token, or for `telnyx` its API key.
curl -X PUT "https://app.katexs.com/api/v1/phone-numbers/carrier-accounts/{provider}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

SMS

GET/api/v1/sms/provider

Get SMS Provider

The workspace's SMS provider, sender header and DLT entity id. Secrets are never returned: secretsSaved names the ones held.

curl -X GET "https://app.katexs.com/api/v1/sms/provider" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/sms/provider

Connect SMS Provider

Connects your SMS provider, or replaces the one connected. A secret you leave out keeps the one saved, for the same provider; switching provider needs every field. The connection's status goes back to untested until Send Test SMS succeeds. Needs a full key.

What each provider asks for in credentials:

  • msg91: authKey
  • exotel: accountSid, apiKey, apiToken, region (in or sg)
  • gupshup: userId, password
  • infobip: baseUrl (your own, like xxxxx.api.infobip.com), apiKey
  • vonage: apiKey, apiSecret
  • fast2sms: apiKey

Body

  • provider string · required
  • credentials object · requiredThe provider's own fields, as listed above.
  • senderHeader string · requiredYour six-letter sender header, as registered on your DLT portal.
  • dltEntityId string · requiredYour Principal Entity ID from your DLT portal (digits only).
curl -X PUT "https://app.katexs.com/api/v1/sms/provider" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/sms/provider

Disconnect SMS Provider

Forgets the provider and its credentials, and switches send_sms off on every agent. Your templates are kept. Needs a full key.

curl -X DELETE "https://app.katexs.com/api/v1/sms/provider" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/sms/templates

List SMS Templates

The workspace's DLT templates, by name.

curl -X GET "https://app.katexs.com/api/v1/sms/templates" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/sms/templates

Add SMS Template

Adds a template exactly as it was approved on your DLT portal, with {#var#} wherever the text changes. Each {#var#} takes at most 30 characters when sent. Promotional templates are not accepted: an agent may only send transactional or service messages. MSG91 and Fast2SMS send by their own template id, so with them providerTemplateId is required. Needs a full key.

Body

  • name string · required
  • body string · required
  • dltTemplateId string · required
  • providerTemplateId stringnull
  • category string · required
  • agentMaySend booleanLet an agent send it during a call or chat. Default `false`.
curl -X POST "https://app.katexs.com/api/v1/sms/templates" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
PATCH/api/v1/sms/templates/{id}

Update SMS Template

Changes any of a template's fields; what you leave out stays. If an agent sends this template after its calls, a body with a different number of {#var#} is refused until that agent's follow-up is changed. Needs a full key.

Parameters

  • id string · path · requiredThe template's id.

Body

  • name string
  • body string
  • dltTemplateId string
  • providerTemplateId stringnull
  • category string
  • agentMaySend boolean
curl -X PATCH "https://app.katexs.com/api/v1/sms/templates/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/sms/templates/{id}

Delete SMS Template

Deletes a template. An agent that sent it after its calls stops sending an SMS then. Needs a full key.

Parameters

  • id string · path · requiredThe template's id.
curl -X DELETE "https://app.katexs.com/api/v1/sms/templates/{id}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/sms/test

Send Test SMS

Sends one template to one Indian mobile number through your provider — a real SMS, billed by your provider — to prove the provider, header and DLT ids work together. Success sets the connection's status to working; a provider's refusal sets it to failing with the reason. Needs a full key.

Body

  • to string · requiredAn Indian mobile number.
  • templateId string · required
  • values string[] · requiredOne per `{#var#}`, in order.
curl -X POST "https://app.katexs.com/api/v1/sms/test" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Voices

GET/api/v1/voices

List Voices

Every voice your agents may speak with, in the picker's order: premium, then Studio. tier is the price band a call is billed at: premium or studio. Standard voices were retired on 23 October 2026 and are no longer listed. Studio voices — the shared Studio catalogue and your own clones (mine: true) and, in a developer's customer workspace, the developer's clones (sharedFromDeveloper: true) — are listed only on the Pro plan and above, so every id here is one you can set. Every voice speaks every supported language; the agent's language decides which.

curl -X GET "https://app.katexs.com/api/v1/voices" \
  -H "Authorization: Bearer $API_KEY"

Voice clones

GET/api/v1/voice-clones

List Voice Clones

Your workspace's cloned voices, newest first, with a short-lived link to each one's preview and the consent it was made under.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/voice-clones" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/voice-clones

Create Voice Clone

Clones a voice from a 5–30 second recording, sent as multipart/form-data with the audio as sample. Both consent fields must be true — the two promises the console shows — or nothing is stored or sent anywhere; the refusal carries the two sentences so you can show your own user the same words. Cloning is on the Pro plan and above, up to your plan's number of voices (10 on Pro, 20 on Scale). Needs a full key.

curl -X POST "https://app.katexs.com/api/v1/voice-clones" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/voice-clones/{id}

Get Voice Clone

One cloned voice, with a preview link that works for sixty seconds — long enough to play, too short to share.

Parameters

  • id string · path · requiredThe cloned voice's id (`vc_…`), or its bare `voiceId` — both name the same voice.
curl -X GET "https://app.katexs.com/api/v1/voice-clones/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/voice-clones/{id}

Update Voice Clone

Renames, re-describes or re-tags a cloned voice. Its language, recording and consent are what it was made from and cannot be changed; sending any other field is refused. A build key may do this.

Parameters

  • id string · path · requiredThe cloned voice's id (`vc_…`), or its bare `voiceId` — both name the same voice.

Body

  • name stringA new name, up to 40 characters.
  • description stringnullA new note, up to 200 characters, or null to clear it.
  • tags string[]The new labels, replacing the old. Lower-cased, de-duplicated, eight at most.
curl -X PATCH "https://app.katexs.com/api/v1/voice-clones/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/voice-clones/{id}

Delete Voice Clone

Forgets the voice everywhere — the voice, its recording and its preview — and moves every agent that spoke with it to a Premium voice; movedAgents says how many. It cannot be undone. Needs a full key.

Parameters

  • id string · path · requiredThe cloned voice's id (`vc_…`), or its bare `voiceId` — both name the same voice.
curl -X DELETE "https://app.katexs.com/api/v1/voice-clones/{id}" \
  -H "Authorization: Bearer $API_KEY"

Models

GET/api/v1/models

List Models

Every model an agent may answer with, by the name the console shows. available says whether your plan may pick it — the rest are listed so you can see what an upgrade adds — and voice whether it is quick enough to answer a call (an agent's model must be). On a workspace that brings its own keys there is also byok: your LLM provider, your key's own model and every model the key reaches, which is what agents run on while your own keys are on. voiceOnlyByok marks the models a call may run on while you bring only your own voice. callTier and callPricePerMinuteMicro are the per-minute call price the console shows beside each model, for your workspace, in currency micro-units. callTier is always premium: since standard voices were retired (23 October 2026) every call bills at the premium rate, or the studio rate with a studio voice, and the model never changes it. These cover the model only, with a premium voice. On a workspace using its own keys, a call bills at the BYOK per-minute rate whatever the model (all three keys, or voice key only — see Bring your own keys), so these prices apply only to an agent whose byok is "off". Typical latency is not published.

curl -X GET "https://app.katexs.com/api/v1/models" \
  -H "Authorization: Bearer $API_KEY"

Bring your own keys

GET/api/v1/byok

Get BYOK Status

Whether your workspace runs on its own keys, whose keys are in use (own, or developer for a customer using its developer's), which keys you bring (scope: all three, only your voice, only your language model, or your language model and your voice), whether your keys for that scope are complete enough to switch on, and each key, masked to its last four characters.

curl -X GET "https://app.katexs.com/api/v1/byok" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/byok

Turn BYOK On or Off

Switches your workspace onto your own keys, or back onto ours, and/or chooses what you bring (scope). Scope all needs all three keys — speech-to-text, LLM and voice — added, verified and each with a model chosen; scope voice needs only the voice key, and speech-to-text, the LLM and telephony stay ours; scope llm needs only the LLM key, and speech-to-text and the voice stay ours (calls are billed on the normal voice plan, whatever your model); scope llm_voice needs the LLM key and the voice key, and our speech recogniser stays (a call is a flat ₹1/min like all). scope is the default for your agents: any agent may follow it, be switched off, or choose another scope your keys allow (Update Agent byok). Any plan may turn it on. On a developer's workspace, turning it off turns it off for every customer using your keys, and a customer inherits your scope. Needs a full key.

Body

  • enabled boolean`true` to run on your own keys, `false` to run on ours.
  • scope string`all` — all three of your keys; `voice` — only your voice key; `llm` — only your language-model key (we keep the speech recogniser and the voice, and calls stay on the normal voice plan); `llm_voice` — your language-model key and your voice key (we keep the speech recogniser; a flat ₹1/min). Changing it while on needs the new scope's keys complete.
curl -X PATCH "https://app.katexs.com/api/v1/byok" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/byok/credentials

List BYOK Keys

Your workspace's own provider keys, one per job, masked to their last four characters, with the model each runs and every model its provider offered it.

curl -X GET "https://app.katexs.com/api/v1/byok/credentials" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/byok/credentials

Add BYOK Key

Adds or replaces your key for one job. The key is checked with the provider before anything is stored — a key the provider rejects is not saved — then stored encrypted and only ever shown by its last four characters. The provider's model list is pulled at the same time. Without credentials.model, a speech key starts on the provider's usual model and an LLM key on its usual one where it has one; replacing a key with one for the same provider keeps the model already chosen. Needs a full key.

Body

  • kind string · requiredThe job this key does: speech-to-text, LLM or voice.
  • provider string · requiredWho does the job. Speech-to-text: `deepgram`, `assemblyai`, `soniox`, `speechmatics`, `gladia`, `sarvam`, `elevenlabs`, `cartesia`, `openai`, `groq`, `mistral`, `azure`. LLM: `openai`, `anthropic`, `google`, `groq`, `mistral`, `sarvam`, `deepseek`, `xai`, `together`, `fireworks`, `cerebras`, `openrouter`, `openai_compatible`. Voice: `deepgram`, `elevenlabs`, `cartesia`, `openai`, `sarvam`, `soniox`, `mistral`, `azure`, `rime`, `inworld`, `murf`, `speechify`. A provider that does not do the job is refused with the list that does.
  • credentials object · requiredThe provider's fields. Every provider takes `apiKey` and an optional `model`; `azure` also takes `region` and optionally `endpoint`; `openai_compatible` also takes `baseUrl`. Any other field is refused.
curl -X PUT "https://app.katexs.com/api/v1/byok/credentials" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
PATCH/api/v1/byok/credentials/{kind}

Update BYOK Key Model

Changes the model a stored key runs without sending the key again. model must be on the key's models; for a model the provider launched after you added the key, send refreshModels: true — alone, or with the new model, which is then checked against the fresh list. While BYOK is on, a refreshed list that drops the chosen model is refused. Needs a full key.

Parameters

  • kind string · path · requiredWhich key: `stt` (speech-to-text), `llm` or `tts` (voice).

Body

  • model stringA model on the key's `models` (after the refresh, when both are sent). An OpenAI-compatible URL with no list takes any model id.
  • refreshModels booleanPull the provider's model list for this key again.
curl -X PATCH "https://app.katexs.com/api/v1/byok/credentials/{kind}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/byok/credentials/{kind}

Delete BYOK Key

Removes your key for one job. Refused while BYOK is on, since a workspace on its own keys always has all three — turn BYOK off first, or replace the key with Add BYOK Key. Needs a full key.

Parameters

  • kind string · path · requiredWhich key: `stt` (speech-to-text), `llm` or `tts` (voice).
curl -X DELETE "https://app.katexs.com/api/v1/byok/credentials/{kind}" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/byok/voices

List BYOK Voices

The voices your own voice provider offers your key — what Set Agent BYOK Voice accepts. sample is a clip the provider hosts, free to play, when it has one. On Cartesia the list starts with your own cloned voices, then the whole library (up to 2,000 voices); if Cartesia is slow to answer the list can come back short: complete is then false, it is not cached, and you should ask again. A per-call overrides.voice is checked the same way as an agent's voice: if it is not on the list we ask the provider about that one voice directly, so a voice missing from a short list is still accepted. Refused with 409 when the workspace is not using its own keys; its voices are then List Voices. These are the voices of the agents that use your keys: an agent set to byok: "off" (Update Agent) speaks in our voices from List Voices, at our normal pricing, while your other agents stay on your keys.

curl -X GET "https://app.katexs.com/api/v1/byok/voices" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/byok/voices/preview

Preview BYOK Voice

Speaks one short line in a voice of your own voice provider, on your key, and answers with the audio itself. Your provider charges you for the characters, so text is capped at 200; without it the voice says a short greeting of ours in language, or the agent's language when you name an agent. Soniox has no preview: it speaks only on a live call. On a Cartesia key, speed, volume, emotion, model and pronunciationDictId are spoken too, so a setting is heard before it is saved (they work as in Set Agent BYOK Voice; the agent's saved settings are not read). Needs a full key.

Body

  • voice string · requiredA voice id from List BYOK Voices.
  • agentId stringnullAn agent (`ag_…`) whose language the line is spoken in when you send no `language`.
  • text stringThe line to speak, up to 200 characters. Left out, a short greeting of ours.
  • language stringA language tag such as `hi-IN` or `en`, for the line and the voice.
  • speed numberCartesia only. The speed to hear.
  • volume numberCartesia only. The volume to hear.
  • emotion stringCartesia only. One of Cartesia's emotions (English only).
  • model stringCartesia only. A Sonic model other than your key's.
  • pronunciationDictId stringCartesia only. A pronunciation dictionary of your account.
curl -X POST "https://app.katexs.com/api/v1/byok/voices/preview" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Webhooks

GET/api/v1/webhooks

List Webhooks

The workspace's webhook endpoints, newest first — those added by API and those added in the console alike — each with its delivery state. Filter to one agent's with agent.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
  • agent string · queryOnly this agent's endpoints (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/webhooks

Create Webhook

Adds an endpoint for one agent's events — or, from a developer workspace, with includeCustomers: true, one endpoint for every agent in every one of your customers, each delivery's data carrying the workspaceId it is about. The response carries signingSecret once: store it to verify x-webhook-signature on every delivery, because it is never shown again. url is an https:// address or an email address (a helpdesk that opens tickets by mail gets one email per event); addresses inside our own network are refused. A build key may do this.

Body

  • agent stringThe agent whose events to send (`ag_…`). Required unless `includeCustomers` is `true`; never with it.
  • includeCustomers booleanDeveloper workspaces only: one endpoint for the events of every agent in every one of your customers. Send it instead of `agent`.
  • url string · requiredAn `https://` URL, or an email address for a helpdesk that opens tickets by mail. Addresses inside our own network are refused.
  • events string[]Which events to send. Leave it out for every event, now and as new ones are added (the endpoint then reads `["*"]`); naming all of them means the same.
  • enabled booleanWhether to start sending at once.
curl -X POST "https://app.katexs.com/api/v1/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/webhooks/{id}

Get Webhook

One endpoint, with its delivery state: how many deliveries in a row have failed, and the last status, error and time. Never the signing secret.

Parameters

  • id string · path · requiredThe endpoint's id (`wh_…`).
curl -X GET "https://app.katexs.com/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/webhooks/{id}

Update Webhook

Changes an endpoint's url, events or enabled; fields you leave out are kept. Switching an endpoint back on (enabled: true) forgives its past failures, so after an outage: fix the receiver, catch up from the API on what it missed, then PATCH { "enabled": true }. The agent an endpoint belongs to cannot be changed. A build key may do this.

Parameters

  • id string · path · requiredThe endpoint's id (`wh_…`).

Body

  • url stringA new `https://` URL or email address.
  • events string[]The events to send from now on. Naming every event means every event, now and as new ones are added.
  • enabled boolean`false` stops sending; `true` starts again and forgives past failures.
curl -X PATCH "https://app.katexs.com/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/webhooks/{id}

Delete Webhook

Removes the endpoint. Nothing more is sent to it, and its delivery history goes with it. A build key may do this.

Parameters

  • id string · path · requiredThe endpoint's id (`wh_…`).
curl -X DELETE "https://app.katexs.com/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/webhooks/{id}/deliveries

List Webhook Deliveries

The endpoint's recent deliveries, newest first — one row per event, however many attempts it took; 7 days (or the last 50, whichever is more) are kept. status and error are from the latest attempt, 0 when your endpoint could not be reached. attempts counts them, and nextRetryAt says when the next automatic one is due (null once delivered or out of retries). Test sends are listed as test with no eventId. Payloads are not returned: they carry your customers' details. Returns at most 50 rows and has no cursor: nextCursor is always null. A delivery counts toward switching the endpoint off only when it used up all six attempts: five such events in a row switch it off, and since each takes about 8½ hours to give up, a dead endpoint can take up to about two days to be switched off.

Parameters

  • id string · path · requiredThe endpoint's id (`wh_…`).
curl -X GET "https://app.katexs.com/api/v1/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/webhooks/{id}/test

Test Webhook

Sends one sample lead.captured event to the endpoint — its data marked "test": true, with obviously fake details — the same way a real event goes: signed JSON, Slack's own message format for a Slack URL, or a ticket email for an email address. It is recorded in the delivery history as test, and a failed test counts towards the five failures in a row that switch an endpoint off. The answer says whether it arrived; a failure to deliver is still a 200 here. A build key may do this.

Parameters

  • id string · path · requiredThe endpoint's id (`wh_…`).
curl -X POST "https://app.katexs.com/api/v1/webhooks/{id}/test" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/webhooks/{id}/redeliver

Redeliver Webhook Events

Sends events to this endpoint again — the same body, event id and sentAt they first had, with x-webhook-attempt one higher. Either { "deliveryId": "whd_…" } for one delivery, sent now (the answer says whether it arrived; if it fails it joins the retry schedule), or { "since": "<ISO time>" } for every delivery that has not succeeded since then — at most 7 days back, when payloads are dropped — queued and sent within a minute (202 { queued }). The endpoint must be switched on. A build key may do this: it reaches only your own endpoint.

Parameters

  • id string · path · requiredThe endpoint's id (`wh_…`).

Body

  • deliveryId stringOne delivery (`whd_…`) to send again now.
  • since stringRe-send every delivery that has not succeeded since this time; at most 7 days back.
curl -X POST "https://app.katexs.com/api/v1/webhooks/{id}/redeliver" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Usage

GET/api/v1/usage

Get Usage

Your plan, this calendar month's (UTC) replies against its allowance, the wallet, and replies per UTC day for the last days — the figures on the console's Usage page. Any key may call this, a read-only key included.

Parameters

  • days integer · queryDays of `daily` to return, ending today (UTC).
curl -X GET "https://app.katexs.com/api/v1/usage" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/usage/daily

Get Daily Usage

Replies, calls and call minutes for every UTC day in the window — the Usage page's chart, quiet days as zeros. Give a rolling days, or a from/to range of up to 366 days reaching back at most 730 days; a to past today is cut to today. Any key may call this, a read-only key included.

Parameters

  • days integer · queryA rolling window ending today (UTC). Not with `from`/`to`.
  • from string · queryFirst UTC day, YYYY-MM-DD. Needs `to`.
  • to string · queryLast UTC day, YYYY-MM-DD. Needs `from`.
curl -X GET "https://app.katexs.com/api/v1/usage/daily" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/usage/calls

List Call Log

The Usage page's call log: every call made or taken, newest first, with how it ended and what it was charged. format=csv returns the console's export instead — the same calls, up to 10,000, as a calls.csv attachment (columns Started, Direction, Surface, Agent, Number, From, Outcome, Status, Seconds, Cost, then Summary, then one column for each detail the agent collected, named as your agent names it, in the order they first appear: up to 20; a call that did not collect one has an empty cell); limit and cursor do not apply to it. GET /calls is the integration view of the same calls; this is the billing view. Any key may call this, a read-only key included.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
  • from string · queryFirst day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional; either end alone is allowed.
  • to string · queryLast day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional.
  • format string · query`json` (a page) or `csv` (the export, as an attachment).
curl -X GET "https://app.katexs.com/api/v1/usage/calls" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/wallet/ledger

List Wallet Ledger

The balance history — every top-up, reply, call, WhatsApp message, number rental, refund and adjustment, newest first, with the balance after each (Settings → Billing → History). A developer's charges for its customers land on its own ledger, each naming the customer; customer narrows to one (read with your own key, no X-Workspace header). Reads only: money is added in the console. Any key may call this, a read-only key included.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
  • from string · queryFirst day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional; either end alone is allowed.
  • to string · queryLast day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional.
  • kind string · queryOnly rows of this kind.
  • customer string · queryDevelopers: only charges for this customer workspace.
curl -X GET "https://app.katexs.com/api/v1/wallet/ledger" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/invoices

List Invoices

One invoice for every payment taken, newest first — the rows under Settings → Billing → History → Invoices. Amounts are integer minor units (paise, cents) of currency, as issued — not micro-units. from/to filter on the issue date. Any key may call this, a read-only key included.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
  • from string · queryFirst day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional; either end alone is allowed.
  • to string · queryLast day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional.
curl -X GET "https://app.katexs.com/api/v1/invoices" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/calls/summary

Get Calls Summary

Call totals for the last days — calls, inbound, outbound, answered, missed, failed, seconds, what they cost, by surface — and a series by hour (days=1) or by day, bucketed in your workspace's time zone. The dashboard's calls figures. Any key may call this, a read-only key included.

Parameters

  • days integer · queryThe rolling window.
curl -X GET "https://app.katexs.com/api/v1/calls/summary" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/whatsapp/summary

Get WhatsApp Summary

WhatsApp messages sent and received, how many were delivered, read or failed (with failure codes), a series, and what they cost you — the WhatsApp dashboard's figures. Either a rolling days or a from/to range (inclusive, up to 366 days), in your workspace's time zone; from/to wins when both are given. Any key may call this, a read-only key included.

Parameters

  • days integer · queryThe rolling window. Ignored when `from`/`to` are given.
  • from string · queryRange start, YYYY-MM-DD, your time zone. Needs `to`.
  • to string · queryRange end, YYYY-MM-DD, inclusive. Needs `from`.
curl -X GET "https://app.katexs.com/api/v1/whatsapp/summary" \
  -H "Authorization: Bearer $API_KEY"

Analytics

GET/api/v1/dashboard

Get Dashboard

The console Dashboard's figures for the whole workspace: how many agents, numbers, knowledge documents, campaigns, keys, members, contacts and leads; conversations unread and waiting on a person; calls in the last 30 days; and the balance as the account card shows it. The period charts are GET /calls/summary and GET /whatsapp/summary. Any key may call this, a read-only key included.

curl -X GET "https://app.katexs.com/api/v1/dashboard" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/agents/{id}/analytics

Get Agent Analytics

What the agent's Analytics page shows: totals, conversations/replies/leads per day, conversations by hour and by channel, the questions it could not answer and the questions asked most. Windows are rolling days; hours and days are UTC. resolved and escalated count conversations by their current status. Any key may call this, a read-only key included.

Parameters

  • id string · path · requiredThe agent's id.
  • days integer · queryThe rolling window.
  • rows integer · queryCaps `knowledgeGaps` and `topQuestions`.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/analytics" \
  -H "Authorization: Bearer $API_KEY"

Workspace

GET/api/v1/workspace

Get Workspace

The workspace's id, name, console address (slug), time zone and when it was made. Plan and billing are not settings and are not here.

curl -X GET "https://app.katexs.com/api/v1/workspace" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/workspace

Update Workspace

Renames the workspace, changes its time zone, or sets how many days calls are kept (callRetentionDays) — any of them. The name appears in invitation emails, so it follows the rules for a person's name: 2 to 80 characters (a longer one is refused with a 400), no web or email address, no markup. Every date in the console is shown in the time zone. The slug never changes. Needs a full key.

Body

  • name stringThe new name: 2 to 80 characters (longer is refused), no web or email address, no markup or hidden characters.
  • timezone stringAn IANA time zone, such as `Asia/Kolkata` or `Europe/London`.
  • callRetentionDays integernullKeep calls' recordings and transcripts for this many days, from 1 to your plan's `planRetentionDays` (a longer number is refused with a 400 naming your plan's maximum). From the next night, older calls lose their recording and transcript; their billing record stays. `null` goes back to your plan's window for recordings and keeps transcripts.
curl -X PATCH "https://app.katexs.com/api/v1/workspace" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Projects

GET/api/v1/projects

List Projects

The workspace's projects, newest first, each with how many agents are in it.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/projects" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/projects

Create Project

Adds a project. Every workspace starts with its default project; a second one needs a plan with teams and projects, and is refused with 402 otherwise. A build key may do this.

Body

  • name string · requiredThe project's name, up to 200 characters, without markup or hidden characters. Trimmed.
curl -X POST "https://app.katexs.com/api/v1/projects" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/projects/{id}

Get Project

One project, with how many agents are in it.

Parameters

  • id string · path · requiredThe project's id (`proj_…`).
curl -X GET "https://app.katexs.com/api/v1/projects/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/projects/{id}

Update Project

Renames a project. A build key may do this.

Parameters

  • id string · path · requiredThe project's id (`proj_…`).

Body

  • name string · requiredThe project's name, up to 200 characters, without markup or hidden characters. Trimmed.
curl -X PATCH "https://app.katexs.com/api/v1/projects/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/projects/{id}

Delete Project

Deletes a project and its team grants. Refused for the default project, and while any agent is still in the project — move them first. A build key may do this.

Parameters

  • id string · path · requiredThe project's id (`proj_…`).
curl -X DELETE "https://app.katexs.com/api/v1/projects/{id}" \
  -H "Authorization: Bearer $API_KEY"

Teams

GET/api/v1/teams

List Teams

The workspace's teams, newest first, each with its members' ids and the projects it can reach.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/teams" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/teams

Create Team

Adds an empty team; put members in it and grant it projects with the team's sub-resources. Teams need a plan with teams and projects, and are refused with 402 otherwise. A build key may do this.

Body

  • name string · requiredThe team's name, up to 200 characters, without markup or hidden characters. Trimmed.
curl -X POST "https://app.katexs.com/api/v1/teams" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/teams/{id}

Get Team

One team, with its members' ids and the projects it can reach.

Parameters

  • id string · path · requiredThe team's id (`team_…`).
curl -X GET "https://app.katexs.com/api/v1/teams/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/teams/{id}

Update Team

Renames a team. A build key may do this.

Parameters

  • id string · path · requiredThe team's id (`team_…`).

Body

  • name string · requiredThe team's name, up to 200 characters, without markup or hidden characters. Trimmed.
curl -X PATCH "https://app.katexs.com/api/v1/teams/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/teams/{id}

Delete Team

Deletes a team and its grants. A project only this team could reach opens to the whole workspace. The people stay in the workspace. A build key may do this.

Parameters

  • id string · path · requiredThe team's id (`team_…`).
curl -X DELETE "https://app.katexs.com/api/v1/teams/{id}" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/teams/{id}/members/{memberId}

Add Team Member

Puts a member of the workspace in the team, so they can reach the team's projects. Repeating it changes nothing. Answers with the team. A build key may do this.

Parameters

  • id string · path · requiredThe team's id (`team_…`).
  • memberId string · path · requiredThe member's `id`, from List Members.
curl -X PUT "https://app.katexs.com/api/v1/teams/{id}/members/{memberId}" \
  -H "Authorization: Bearer $API_KEY"
DELETE/api/v1/teams/{id}/members/{memberId}

Remove Team Member

Takes a member out of the team; they stay in the workspace. Taking out somebody who is not in the team changes nothing. Answers with the team. A build key may do this.

Parameters

  • id string · path · requiredThe team's id (`team_…`).
  • memberId string · path · requiredThe member's `id`, from List Members.
curl -X DELETE "https://app.katexs.com/api/v1/teams/{id}/members/{memberId}" \
  -H "Authorization: Bearer $API_KEY"
PUT/api/v1/teams/{id}/projects/{projectId}

Grant Team Project

Lets the team reach a project. A project's first grant restricts it: from then on only the teams granted it (plus owners and admins) can see its agents. Repeating it changes nothing. Answers with the team. A build key may do this.

Parameters

  • id string · path · requiredThe team's id (`team_…`).
  • projectId string · path · requiredThe project's id (`proj_…`).
curl -X PUT "https://app.katexs.com/api/v1/teams/{id}/projects/{projectId}" \
  -H "Authorization: Bearer $API_KEY"
DELETE/api/v1/teams/{id}/projects/{projectId}

Revoke Team Project

Takes a project out of the team's reach. When that was the project's last grant, the project opens to the whole workspace again. Answers with the team. A build key may do this.

Parameters

  • id string · path · requiredThe team's id (`team_…`).
  • projectId string · path · requiredThe project's id (`proj_…`).
curl -X DELETE "https://app.katexs.com/api/v1/teams/{id}/projects/{projectId}" \
  -H "Authorization: Bearer $API_KEY"

Members

GET/api/v1/members

List Members

Everybody in the workspace, with their role — so a conversation can be assigned by email, or a role changed or a person removed by id. Not paged: every member is in one answer, and nextCursor is always null. Pending invitations are listed by List Invitations.

curl -X GET "https://app.katexs.com/api/v1/members" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/members/{id}

Get Member

One person in the workspace, with their role.

Parameters

  • id string · path · requiredThe member's `id`, from List Members.
curl -X GET "https://app.katexs.com/api/v1/members/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/members/{id}

Update Member

Changes a member's role to admin or member. A key cannot make anybody an owner — do that in the console, signed in as one — and the workspace's last owner cannot be demoted. Needs a full key.

Parameters

  • id string · path · requiredThe member's `id`, from List Members.

Body

  • role string · requiredThe new role. `owner` is refused with `403`: make owners in the console.
curl -X PATCH "https://app.katexs.com/api/v1/members/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/members/{id}

Remove Member

Removes a person from the workspace. Conversations assigned to them go back to the unassigned pool. The workspace's last owner cannot be removed. Needs a full key.

Parameters

  • id string · path · requiredThe member's `id`, from List Members.
curl -X DELETE "https://app.katexs.com/api/v1/members/{id}" \
  -H "Authorization: Bearer $API_KEY"

Invitations

GET/api/v1/invitations

List Invitations

Pending invitations, newest first. The link in each is only ever in the email, never here.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/invitations" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/invitations

Create Invitation

Invites somebody to the workspace and emails them a link that works for 14 days (the email goes out just after the answer). Inviting an address that already has a pending invitation sends it again with a fresh 14 days and its new role, and answers 200 instead of 201. Every seat counts — the people in the workspace plus pending invitations. Addresses at reserved test domains (example.com, .test, …) get the invitation but no email. Needs a full key.

Body

  • email string · requiredThe address to invite. Lower-cased.
  • role stringThe role they will have. `owner` is refused with `403`: invite owners from the console.
curl -X POST "https://app.katexs.com/api/v1/invitations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/invitations/{id}

Get Invitation

One invitation, whatever its status — pending, accepted or revoked.

Parameters

  • id string · path · requiredThe invitation's id (`inv_…`).
curl -X GET "https://app.katexs.com/api/v1/invitations/{id}" \
  -H "Authorization: Bearer $API_KEY"
DELETE/api/v1/invitations/{id}

Revoke Invitation

Revokes a pending invitation: its link stops working and its seat is freed. An invitation that was accepted or already revoked is 404. Needs a full key.

Parameters

  • id string · path · requiredThe invitation's id (`inv_…`).
curl -X DELETE "https://app.katexs.com/api/v1/invitations/{id}" \
  -H "Authorization: Bearer $API_KEY"

Notifications

GET/api/v1/notification-preferences

Get Notification Preferences

Every notification category, with whether it is muted and what of it is emailed. A category never changed is shown, not muted and not emailed. Not paged: nextCursor is always null.

curl -X GET "https://app.katexs.com/api/v1/notification-preferences" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/notification-preferences

Update Notification Preferences

Changes any categories at once, keyed by category: muted hides it from the feed and the bell (a critical notice shows regardless), email chooses what is emailed. A field you leave out keeps its value. Emails go only through the email sender connected in the console's notification settings; until one is connected nothing is emailed, whatever this says, and that connection is not available by API. Answers with every category. A build key may do this.

Body

  • meta objectSend `muted`, `email` or both; the other keeps its value.
  • templates objectSend `muted`, `email` or both; the other keeps its value.
  • campaigns objectSend `muted`, `email` or both; the other keeps its value.
  • calls objectSend `muted`, `email` or both; the other keeps its value.
  • inbox objectSend `muted`, `email` or both; the other keeps its value.
  • knowledge objectSend `muted`, `email` or both; the other keeps its value.
  • billing objectSend `muted`, `email` or both; the other keeps its value.
  • system objectSend `muted`, `email` or both; the other keeps its value.
  • members objectSend `muted`, `email` or both; the other keeps its value.
curl -X PATCH "https://app.katexs.com/api/v1/notification-preferences" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Saved replies

GET/api/v1/saved-replies

List Saved Replies

The workspace's saved replies, newest first.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/saved-replies" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/saved-replies

Create Saved Reply

Adds a saved reply, offered in the inbox composer as /shortcut. A leading / on the shortcut is dropped. A shortcut already used — in any capitalisation — is 409. A build key may do this.

Body

  • shortcut string · requiredWhat a teammate types to find it. A leading `/` is dropped; up to 40 characters after that. Unique in the workspace, ignoring case.
  • body string · requiredWhat the reply says, up to 2,000 characters. Trimmed.
curl -X POST "https://app.katexs.com/api/v1/saved-replies" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/saved-replies/{id}

Get Saved Reply

One saved reply.

Parameters

  • id string · path · requiredThe saved reply's `id`.
curl -X GET "https://app.katexs.com/api/v1/saved-replies/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/saved-replies/{id}

Update Saved Reply

Changes a saved reply's shortcut, body, or both. A build key may do this.

Parameters

  • id string · path · requiredThe saved reply's `id`.

Body

  • shortcut stringA new shortcut. A leading `/` is dropped. Unique in the workspace, ignoring case.
  • body stringNew text, up to 2,000 characters.
curl -X PATCH "https://app.katexs.com/api/v1/saved-replies/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/saved-replies/{id}

Delete Saved Reply

Deletes a saved reply. A build key may do this.

Parameters

  • id string · path · requiredThe saved reply's `id`.
curl -X DELETE "https://app.katexs.com/api/v1/saved-replies/{id}" \
  -H "Authorization: Bearer $API_KEY"

Contact groups

GET/api/v1/contact-groups

List Contact Groups

Every group in the workspace, by name, each with how many contacts are in it. Returned whole: nextCursor is always null.

curl -X GET "https://app.katexs.com/api/v1/contact-groups" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/contact-groups

Create Contact Group

Creates an empty group. Names are unique in the workspace whatever the capitals; a second one answers 409. A build key may do this.

Body

  • name string · requiredSpaces are trimmed and collapsed.
curl -X POST "https://app.katexs.com/api/v1/contact-groups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/contact-groups/{id}

Get Contact Group

One group and how many contacts are in it.

Parameters

  • id string · path · requiredThe group, `grp_…`.
curl -X GET "https://app.katexs.com/api/v1/contact-groups/{id}" \
  -H "Authorization: Bearer $API_KEY"
PATCH/api/v1/contact-groups/{id}

Rename Contact Group

Renames a group. Campaigns aimed at it keep reaching it. A build key may do this.

Parameters

  • id string · path · requiredThe group, `grp_…`.

Body

  • name string · requiredSpaces are trimmed and collapsed.
curl -X PATCH "https://app.katexs.com/api/v1/contact-groups/{id}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/contact-groups/{id}

Delete Contact Group

Deletes the group and its memberships. Its contacts stay. A campaign not yet sent that was aimed at it no longer reaches anybody through it. A build key may do this.

Parameters

  • id string · path · requiredThe group, `grp_…`.
curl -X DELETE "https://app.katexs.com/api/v1/contact-groups/{id}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/contact-groups/{id}/members

Add Contacts To Group

Adds up to 1,000 contacts to the group. Contacts already in it are left as they are (added counts only the new ones). Every id must be a contact in this workspace, or nothing is added and the answer is 404 naming them. A build key may do this.

Parameters

  • id string · path · requiredThe group, `grp_…`.

Body

  • contacts string[] · requiredContact ids, `cust_…`.
curl -X POST "https://app.katexs.com/api/v1/contact-groups/{id}/members" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
DELETE/api/v1/contact-groups/{id}/members

Remove Contacts From Group

Takes up to 1,000 contacts out of the group. The contacts stay; ids not in the group are ignored (removed counts the ones taken out). A build key may do this.

Parameters

  • id string · path · requiredThe group, `grp_…`.

Body

  • contacts string[] · requiredContact ids, `cust_…`.
curl -X DELETE "https://app.katexs.com/api/v1/contact-groups/{id}/members" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Workflows

POST/api/v1/workflows/{workflowId}/runs

Start a Workflow Run

Starts one contact through a workflow whose published Start when is Your system asks. A number this workspace has never seen gets a contact made for it, so a brand-new lead from your CRM can go straight in. variables are this run's own values: a blank written {{contact.order}} fills from variables.order. started: false is a 200, not an error: the contact is already going through it, or the workflow's settings do not let them go through it again. Calls and messages the workflow sends are billed as usual. Needs a full key.

Parameters

  • workflowId string · path · requiredThe workflow's id (`wf_…`). With Start when set to *Your system asks*, the builder shows this endpoint with the id, ready to copy. A bare uuid also works.

Body

  • to string · requiredThe contact's phone number, with its country code.
  • name stringTheir name, used for a new contact and for `{{contact.name}}`.
  • email stringTheir email, used for a new contact.
  • variables objectUp to 20 values for this run (text, numbers or true/false; names up to 60 characters, values up to 300). Not `name`, `email` or `phone`: send those as fields.
curl -X POST "https://app.katexs.com/api/v1/workflows/{workflowId}/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'
GET/api/v1/workflows

List Workflows

The workspace's workflows, newest first, with each one's id — what Start a Workflow Run takes — its status, the version new runs start on, and what starts it. Read-only: workflows are built and published in the console. Any key.

Parameters

  • limit integer · queryHow many items to return, 1 to 100.
  • cursor string · queryThe `nextCursor` from the previous page. Leave it out for the first page.
curl -X GET "https://app.katexs.com/api/v1/workflows" \
  -H "Authorization: Bearer $API_KEY"
GET/api/v1/workflows/{workflowId}

Get a Workflow

One workflow: what starts it and its blocks, as PUBLISHED (the draft only for a workflow never published), and — when your system starts it — the address to send runs to. Any key.

Parameters

  • workflowId string · path · requiredThe workflow's id (`wf_…`); a bare uuid also works.
curl -X GET "https://app.katexs.com/api/v1/workflows/{workflowId}" \
  -H "Authorization: Bearer $API_KEY"
POST/api/v1/workflows/events

Send a Workflow Event

Tells your workflows that something happened to a contact, such as a payment landing or a booking being made. Every run of that contact whose Await block waits for Your system sends an event with this name moves on through its Arrived path at the next check; only events sent after the run began waiting count. The contact is found by phone number. Needs a full key.

Body

  • to string · requiredThe contact's phone number, with its country code.
  • event string · requiredThe event's name, as written in the Await block, like `payment_received`.
  • data objectAnything you want kept with the event (up to 4,000 characters).
curl -X POST "https://app.katexs.com/api/v1/workflows/events" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'