API endpoints
Every request goes to https://app.katexs.com/api/v1 with your API key from Settings → API keys.
Agents
List Agents
Every agent in your workspace, newest first, in the same shape Get Agent returns. Page with limit and cursor.
Parameters
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
namestring · requiredThe agent's name, 2 to 60 characters, without hidden characters or markup.instructionsstringWhat 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.greetingstringThe first thing it says on a call or in a chat.businessDescriptionstringOne line about what the business is. Facts belong in Knowledge.modelstringnullA 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.temperaturenumberHow adventurous the wording is. Clamped to 0–2.maxReplyTokensnumberThe longest a reply may be, in tokens, for chat and calls alike. Rounded and clamped to 100–800.languagesstring[]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.languagestring`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.secondLanguagestringnullRetired. Accepted so an older integration keeps working, but ignored: the agent answers in `language` alone.escalationobjectWhen the agent hands over to a person. Send either or both.captureLeadsbooleanTake a name, email or phone number from an interested customer.ownRulesbooleantrue 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.scheduleCallbacksbooleanAllow it to book a call back when asked.welcomeScreenbooleanOpen the website widget on a welcome screen.welcomeCollectLeadsbooleanAsk for the visitor's details on the welcome screen.stepsobject[]A conversation script, in order, replacing any there was. Blank steps are dropped.byokstringnullHow 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.widgetobjectThe website widget's look. Send any subset.voiceobjectHow 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.collectFieldsarraynullThe 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 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
idstring · 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"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
idstring · 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
namestringThe agent's name, 2 to 60 characters, without hidden characters or markup.instructionsstringWhat the agent is and how it behaves. Re-sent on every reply, so every character costs on every turn.greetingstringThe first thing it says on a call or in a chat. An empty string clears it.businessDescriptionstringOne line about what the business is. Facts belong in Knowledge.modelstringnullA 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.temperaturenumberHow adventurous the wording is. Clamped to 0–2.maxReplyTokensnumberThe longest a reply may be, in tokens, for chat and calls alike. Rounded and clamped to 100–800.languagesstring[]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.languagestring`auto` to reply in the customer's language, or a language the console offers by its English name, e.g. `Hindi`, `Tamil`, `English`.secondLanguagestringnullRetired. Accepted so an older integration keeps working, but ignored: the agent answers in `language` alone.escalationobjectWhen the agent hands over to a person. Send either or both.captureLeadsbooleanTake a name, email or phone number from an interested customer.ownRulesbooleantrue 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.scheduleCallbacksbooleanAllow it to book a call back when asked.welcomeScreenbooleanOpen the website widget on a welcome screen.welcomeCollectLeadsbooleanAsk for the visitor's details on the welcome screen.stepsobject[]The conversation script, in order, replacing the whole script. `[]` removes it.byokstringnullHow 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.widgetobjectThe website widget's look. Send any subset.voiceobjectHow 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.collectFieldsarraynullThe 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 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
idstring · 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 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
idstring · 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"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
idstring · 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
modelstringnull · 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 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
idstring · 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"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
idstring · 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
voicestringnullA voice id from List BYOK Voices, or null for the provider's default (which clears the settings below).speednumbernullCartesia only. How fast the voice speaks; 1 is Cartesia's own. Needs a Sonic 3 model. Does not apply to a Professional Voice Clone.volumenumbernullCartesia only. How loud the voice is; 1 is Cartesia's own. Needs a Sonic 3 model.emotionstringnullCartesia 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.modelstringnullCartesia only. The Sonic model this agent speaks on; null uses your key's model.pronunciationDictIdstringnullCartesia 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 '{ … }'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
idstring · 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
messagestring · requiredWhat the customer says. Trimmed; up to 4,000 characters.sessionstringThe `session` a previous test chat answered with, to continue that conversation. Leave it out to start a new one.modestring`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
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
idstring · path · requiredThe agent's id (`ag_…`).limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).
Body
urlstringA web page to fetch and index. Must start with `http://` or `https://`.textstringText to index, up to 200,000 characters. Trimmed.titlestringA 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 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
idstring · path · requiredThe agent's id (`ag_…`).documentIdstring · 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
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
idstring · path · requiredThe agent's id (`ag_…`).limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).
Body
namestring · 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.descriptionstring · requiredWhen the agent should call it, in a sentence (at least 10 characters). The model decides from this alone.urlstring · requiredAn `https://` address, with `{{placeholders}}` for parameters. Every placeholder needs a parameter of that name. Addresses inside private networks are refused when called.methodstringThe HTTP method; any case is accepted.parametersobject[]Up to 20 values the agent fills from the conversation. Names must be unique.bodyTemplatestringnullA JSON body with **quoted** placeholders, e.g. `{"id": "{{order_id}}"}`. It must still be valid JSON once the blanks are filled.headersobjectUp to 10 headers, name to value — typically `Authorization`. **Write-only:** sealed on arrival; only their names come back, as `headerNames`. Blank values are dropped.speakBeforestringnullOn calls, what the agent says while your API is being called.speakAfterstringnullOn 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 Action
One action. Header values never appear; only headerNames.
Parameters
idstring · path · requiredThe agent's id (`ag_…`).actionIdstring · path · requiredThe action's id (`act_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/actions/{actionId}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe agent's id (`ag_…`).actionIdstring · path · requiredThe action's id (`act_…`).
Body
namestringThe tool name the agent sees; same rules as on create.descriptionstringWhen the agent should call it (at least 10 characters).urlstringAn `https://` address with `{{placeholders}}`.methodstringThe HTTP method.parametersobject[]Replaces the whole list.bodyTemplatestringnullThe JSON body; null removes it.headersobjectLeave 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.speakBeforestringnullWhat the agent says while your API is called; null clears it.speakAfterstringnullWhat the agent says afterwards; null clears it.enabledboolean`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 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
idstring · path · requiredThe agent's id (`ag_…`).actionIdstring · path · requiredThe action's id (`act_…`).
curl -X DELETE "https://app.katexs.com/api/v1/agents/{id}/actions/{actionId}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe agent's id (`ag_…`).actionIdstring · path · requiredThe action's id (`act_…`).
Body
argumentsobjectParameter 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
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
idstring · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/tools" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe agent's id (`ag_…`).
Body
toolsobjectTool id to `true` or `false`. Switchable: `capture_lead`, `escalate_to_human`, `schedule_callback`, `call_them_now`, `send_whatsapp`, `send_sms`, `reply_by_email`.recallstringHow 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).verifyByCodebooleanConfirm a customer with a one-time WhatsApp code instead of their email.knowledgeOnCallsbooleanLet 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.handOverobjectFields 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 '{ … }'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
idstring · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/mcp-servers" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe agent's id (`ag_…`).
Body
namestring · requiredYour name for it, 2 to 200 characters.urlstring · requiredIts `https://` address. It must be publicly reachable: private and internal addresses are refused.transportstring`http` (streamable HTTP) or `sse`.authHeaderNamestringThe header to send the token in, e.g. `Authorization`. Required when `secret` is sent.secretstringThe 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 Tool Server
One tool server and its tools.
Parameters
idstring · path · requiredThe agent's id (`ag_…`).serverIdstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).serverIdstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).serverIdstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).serverIdstring · path · requiredThe tool server's id, `mcp_…`. The bare uuid is accepted too.toolIdstring · path · requiredThe tool's id on that server, `tool_…`, from the server's `tools`. The bare uuid is accepted too.
Body
enabledboolean · 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 '{ … }'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
idstring · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/connections" \
-H "Authorization: Bearer $API_KEY"Get Connection
One connection, connected or not, with the shared tool budget.
Parameters
idstring · path · requiredThe agent's id (`ag_…`).kindstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).kindstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).kindstring · 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
fieldsone ofRecords only: what to collect, `Label` or `Label | what it means`.targetobjectSpreadsheets, 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.propertiesstring[]HubSpot only: the contact properties the agent fills and searches by (at most 40). Pinning starts from a default pick; this replaces it.matchobjectnullSpreadsheets 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.variableColumnsobjectSpreadsheets and CRMs: column to campaign variable, e.g. `{ "Locality": "locality" }`. Neither may contain `=` or a line break. Replaces the saved map.modestringAll but the calendar: `tool` saves during the conversation; `parser` reads the conversation afterwards (and switches the save tool off).runAsyncbooleanGrist only: answer before the save finishes.toolsobjectTool id to `true` or `false`. Every id must be one of this connection's tools. Switching on counts against the shared `maxTools` budget.phrasesobjectTool 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 '{ … }'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
idstring · path · requiredThe agent's id (`ag_…`).kindstring · 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"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
idstring · path · requiredThe agent's id (`ag_…`).kindstring · path · requiredThe connection: `calcom` or `calendly` (calendars), `grist` or `googlesheets` (spreadsheets), `zoho`, `zoho_bigin` or `hubspot` (CRMs), `records` (kept here), `zendesk` or `salesforce` (helpdesks).docstring · queryGrist only, and required there: the document id to look in.spreadsheetstring · 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"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
idstring · 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 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
idstring · path · requiredThe agent's id (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/channels" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe agent's id (`ag_…`).
Body
tokenstring · 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 '{ … }'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
idstring · 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
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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · queryThe `nextCursor` from the previous page. Leave it out for the first page.agentstring · queryOnly this agent's calls — its `ag_…` id.statusstring · queryOnly calls in this state.referencestring · queryOnly calls placed with this `reference` — your CRM's own id for the lead. Matched exactly; up to 200 characters are read.sincestring · queryOnly calls that started at or after this date (`2026-09-17`, from midnight UTC) or instant (`2026-09-17T10:00:00Z`).untilstring · 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"
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"
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 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
idstring · 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"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
idstring · 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 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
idstring · 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.formatstring · 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 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
idstring · 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 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
idstring · 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 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
idstring · 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 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
idstring · path · requiredThe agent's `ag_…` id.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/post-call" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe agent's `ag_…` id.
Body
summariseCallsbooleanWrite a short summary after each call.recordCallsbooleanRecord each call.collectFieldsarraynullThe details to fill from every call, replacing the list. An empty list (or null) stops collecting.followUpobjectThe 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 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
idstring · 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.downloadstring · 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 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
callIdstring · path · requiredThe call's id as it appears in the signed link.expiresstring · query · requiredWhen the link stops working, in Unix seconds — from the link.sigstring · query · requiredThe link's signature — from the link.downloadstring · 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
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
channelstring · queryOnly conversations on this channel.sincestring · queryISO 8601 date and time. Keeps conversations where the customer last wrote at or after this moment.statusstring · queryOnly conversations in this state. `escalated` and `human_handling` are the threads waiting on your team.limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
idstring · path · requiredThe conversation's id (`conv_…`), as the list and the `message.received` webhook give it.sincestring · queryISO 8601 date and time. Keeps messages written after this moment.limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"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
idstring · 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"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
idstring · path · requiredThe conversation's id (`conv_…`).
Body
statusstring · 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 '{ … }'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
idstring · path · requiredThe conversation's id (`conv_…`).
Body
assigneestringnull · 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
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
tostring · 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.templatestring · requiredThe name of an approved template in your workspace. Templates are named, not given by id, so the name stays stable across edits.languagestringWhich 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.variablesstring[]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.buttonVariablesstring[]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.headerMediaUrlstringA 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.formDataobjectPre-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.idempotencyKeystringSame 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
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
tostring · 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.codestring · requiredThe code you generated, 16 characters at most after trimming.templatestringWhich approved authentication template, by name. Needed only when you have more than one.languagestringWhich approved language version, exactly as approved — `en`, `hi`. Needed only when one template name is approved in several languages.idempotencyKeystringSame 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 '{ … }'List Code Templates
Your workspace's authentication templates — drafts, those in review and approved ones — newest first.
Parameters
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
namestring · requiredLowercase letters, digits and underscores, as WhatsApp allows. Unique with `language`.languagestring · requiredA WhatsApp template language code.expiryMinutesintegerHow long the code lasts. WhatsApp shows it to the customer in their own language.securityRecommendationbooleanAdds "For your security, do not share this code."buttonstring`copy_code`: the customer taps to copy, then pastes — works everywhere. `one_tap`: hands the code straight to your Android app; needs `apps`.appsobject[]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 Code Template
One authentication template, with its review status and WhatsApp's reason when it was rejected.
Parameters
idstring · 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"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
idstring · path · requiredThe template's id — a bare uuid, as the list gives it.
Body
namestringLowercase letters, digits and underscores.languagestringA WhatsApp template language code.expiryMinutesintegerHow long the code lasts.securityRecommendationbooleanAdds "For your security, do not share this code."buttonstringHow the code gets into your app.appsobject[]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 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
idstring · 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"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
idstring · 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
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
tagstring · queryOnly contacts carrying this tag. Normalised as tags are stored — `Hot Lead` matches `hot-lead`.groupstring · queryOnly contacts in this contact group, `grp_…`.externalIdstring · queryOnly the contact with this CRM id.phonestring · queryOnly the contact on this number, with its country code, in any format a person would type it (`+91 98765 43210`, `+44 7700 900123`).limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
phonestring · 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.namestringnullTheir name.emailstringnullTheir email. Stored lower-cased.externalIdstringnullYour CRM's id for them, unique in your workspace. `GET /contacts?externalId=` finds them by it.tagsstring[]Tags, normalised as the console stores them: lower case, spaces to hyphens, duplicates dropped, 40 characters and 20 tags at most. Replaces the list.languagestringnullThe language to write to them in, by its English name as the console offers it, `auto` to match theirs, or `null`.notestringnullFree-text notes about them.consentobjectTheir word on marketing messages, recorded with the time and where it came from — what a regulator asks.fieldsobjectDetails 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 Contact
One contact, by id.
Parameters
idstring · path · requiredThe contact's id (`cust_…`).
curl -X GET "https://app.katexs.com/api/v1/contacts/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe contact's id (`cust_…`).
Body
phonestringA new number for them. Normalised as on create.namestringnullTheir name, or `null` to clear it.emailstringnullTheir email, or `null` to clear it.externalIdstringnullYour CRM's id, or `null` to clear it.tagsstring[]Replaces the whole list. Normalised as on create.languagestringnullThe language to write to them in, `auto`, or `null`.notestringnullFree-text notes, or `null` to clear them.consentobjectTheir word on marketing messages, recorded with the time and where it came from — what a regulator asks.fieldsobjectDetails 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 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
idstring · 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
List Do-Not-Call Numbers
The workspace's do-not-call list, newest first.
Parameters
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
phonestring · requiredThe number, with its country code. Spaces, dashes and brackets are ignored; a number without a country code is refused.reasonstringnullWhy, 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 Do-Not-Call Number
Whether a number is on the list, and how it got there.
Parameters
phonestring · 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"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
phonestring · 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
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
tostring · requiredThe customer's number, with or without the `+`; spaces are fine. Matched to a contact by its digits; a new number creates a contact.eventstring · 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.dataobjectValues 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.namestringThe 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
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
statusstring · queryOnly templates in this review state.categorystring · queryOnly templates of this category.limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
namestring · requiredLowercase letters, numbers and underscores only. Unique per language in your workspace.languagestringA language WhatsApp templates support, such as `en`, `en_US` or `hi`.categorystring · required`utility` for something the customer is expecting (an order or appointment update), `marketing` for promotions, `authentication` for one-time codes.bodystringThe 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.samplesstring[]One example value per body blank, in order. WhatsApp's reviewers read the template with these filled in, so every blank needs one.headerobjectnullThe line or media above the body. `null` means no header.footerstringnullOne 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.buttonsarraynullThe template's buttons, in order.authobjectAn authentication template's settings. WhatsApp writes the message itself ("*123456* is your verification code."), so these are all you choose.agentstringnullThe agent the template belongs to (`ag_…`). Leave it out for the agent on your connected WhatsApp number (or your oldest agent).submitboolean`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 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
namestring · path · requiredThe template's name: lowercase letters, numbers and underscores.languagestring · 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"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
namestring · path · requiredThe template's name: lowercase letters, numbers and underscores.languagestring · 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
namestringA new name: lowercase letters, numbers and underscores only.languagestringA new language code WhatsApp templates support, such as `en`, `en_US` or `hi`.categorystringA new category.bodystringThe new message, with `{{1}}`, `{{2}}` … for the blanks. Ignored for an authentication template.samplesstring[]One example per body blank, in order. Leave it out to keep the current examples.headerobjectnullThe line or media above the body. `null` means no header.footerstringnullThe new footer. `null` or `""` removes it.buttonsarraynullThe full new list of buttons, replacing the old one. `null` or `[]` removes them all.authobjectAn authentication template's settings. WhatsApp writes the message itself ("*123456* is your verification code."), so these are all you choose.agentMaySendbooleanLet 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 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
namestring · path · requiredThe template's name: lowercase letters, numbers and underscores.languagestring · 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"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
namestring · path · requiredThe template's name: lowercase letters, numbers and underscores.languagestring · 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
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
statusstring · queryOnly campaigns in this state. A scheduled campaign is a `draft` with `scheduledAt` set until it starts.limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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 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
idstring · 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"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
idstring · 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"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
idstring · 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"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
idstring · 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"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
idstring · 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
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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
agentstring · requiredThe agent whose sequence this is (`ag_…`). Cannot be changed later.namestring · requiredWhat you call it.exitOnReplybooleanWhether a reply from the customer takes them out.triggerTagsstring[]Tagging a contact with one of these enrols them. Normalised like contact tags.exitOnTagsstring[]Tagging someone in it with one of these takes them out.startOnstring[]Event names (Report Event) that enrol the contact. Normalised like event names: "Order Delivered" becomes `order.delivered`.stopOnstring[]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 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
sequenceIdstring · path · requiredThe sequence's id — a bare uuid.
curl -X GET "https://app.katexs.com/api/v1/sequences/{sequenceId}" \
-H "Authorization: Bearer $API_KEY"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
sequenceIdstring · path · requiredThe sequence's id — a bare uuid.
Body
namestringWhat you call it.exitOnReplybooleanWhether a reply from the customer takes them out.triggerTagsstring[]Replaces the enrolling tags.exitOnTagsstring[]Replaces the exit tags.startOnstring[]Replaces the events that enrol the contact.stopOnstring[]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 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
sequenceIdstring · path · requiredThe sequence's id — a bare uuid.
curl -X DELETE "https://app.katexs.com/api/v1/sequences/{sequenceId}" \
-H "Authorization: Bearer $API_KEY"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
sequenceIdstring · path · requiredThe sequence's id — a bare uuid.
Body
templatestring · requiredThe name of an approved WhatsApp template in your workspace. The sequence's own agent's template wins when two agents share a name.languagestringnullWhich approved language version, e.g. `en` or `hi`. Needed only when the name is approved in more than one language.delayHoursnumberHours 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 '{ … }'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
sequenceIdstring · 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"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
sequenceIdstring · 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"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
sequenceIdstring · path · requiredThe sequence's id — a bare uuid.
Body
tostring · requiredThe contact's number, with or without the `+`. Matched to an existing contact by its digits.variablesobjectValues 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
List Forms
Your workspace's WhatsApp forms, newest first, published or not.
Parameters
agentstring · queryOnly this agent's forms (`ag_…`).limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
namestring · requiredWhat you call it, unique per agent. Customers never see it — but Reply to Conversation can send a form by this name.formobject · requiredcategorystringWhatsApp's category for it. Affects reporting only.agentstringnullThe 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 Form
One form, with its questions and whether it can be sent.
Parameters
idstring · path · requiredThe form's id (`form_…`).
curl -X GET "https://app.katexs.com/api/v1/forms/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe form's id (`form_…`).
Body
namestringWhat you call it.categorystringWhatsApp's category for it.formobject
curl -X PATCH "https://app.katexs.com/api/v1/forms/{id}" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ … }'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
idstring · path · requiredThe form's id (`form_…`).
curl -X DELETE "https://app.katexs.com/api/v1/forms/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · 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
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"
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
numberstring · 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 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
numberstring · 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"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
numberstring · 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
labelstringnullA name for the number. `null` or `""` removes it.agentstringnullThe 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.callingAgentstringnullThe 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.forwardTostringnullForward 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.ringBackstringWho 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 '{ … }'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
numberstring · path · requiredThe number, in any spelling — compared on its digits (8 to 15 of them). Encode a leading `+` as `%2B`, or leave it out.confirmstring · 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"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
numberstring · 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
toWorkspacestring · 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 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"
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"
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
patternstring · queryUp to ten digits that follow the country code — an area code, such as `80` for Bengaluru or `415` for San Francisco.citystring · queryA city (India) or a state (United States), spelled exactly as List Available Cities lists it.cursorstring · 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"
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"
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
numberstring · requiredThe number in E.164 (`+14155550100`). Include the country code: a number without one is refused.providerstring · 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 '{ … }'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"
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
providerstring · path · requiredWhich carrier the account is with.
Body
accountIdstringYour account's id (its Auth ID or Account SID). Required for every carrier but `telnyx`, which ignores it.tokenstring · 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 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"
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:authKeyexotel:accountSid,apiKey,apiToken,region(inorsg)gupshup:userId,passwordinfobip:baseUrl(your own, likexxxxx.api.infobip.com),apiKeyvonage:apiKey,apiSecretfast2sms:apiKey
Body
providerstring · requiredcredentialsobject · requiredThe provider's own fields, as listed above.senderHeaderstring · requiredYour six-letter sender header, as registered on your DLT portal.dltEntityIdstring · 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 '{ … }'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"
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"
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
namestring · requiredbodystring · requireddltTemplateIdstring · requiredproviderTemplateIdstringnullcategorystring · requiredagentMaySendbooleanLet 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 '{ … }'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
idstring · path · requiredThe template's id.
Body
namestringbodystringdltTemplateIdstringproviderTemplateIdstringnullcategorystringagentMaySendboolean
curl -X PATCH "https://app.katexs.com/api/v1/sms/templates/{id}" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{ … }'Delete SMS Template
Deletes a template. An agent that sent it after its calls stops sending an SMS then. Needs a full key.
Parameters
idstring · path · requiredThe template's id.
curl -X DELETE "https://app.katexs.com/api/v1/sms/templates/{id}" \
-H "Authorization: Bearer $API_KEY"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
tostring · requiredAn Indian mobile number.templateIdstring · requiredvaluesstring[] · 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
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
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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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 Voice Clone
One cloned voice, with a preview link that works for sixty seconds — long enough to play, too short to share.
Parameters
idstring · 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"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
idstring · path · requiredThe cloned voice's id (`vc_…`), or its bare `voiceId` — both name the same voice.
Body
namestringA new name, up to 40 characters.descriptionstringnullA new note, up to 200 characters, or null to clear it.tagsstring[]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 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
idstring · 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
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 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"
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
enabledboolean`true` to run on your own keys, `false` to run on ours.scopestring`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 '{ … }'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"
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
kindstring · requiredThe job this key does: speech-to-text, LLM or voice.providerstring · 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.credentialsobject · 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 '{ … }'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
kindstring · path · requiredWhich key: `stt` (speech-to-text), `llm` or `tts` (voice).
Body
modelstringA model on the key's `models` (after the refresh, when both are sent). An OpenAI-compatible URL with no list takes any model id.refreshModelsbooleanPull 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 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
kindstring · 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"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"
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
voicestring · requiredA voice id from List BYOK Voices.agentIdstringnullAn agent (`ag_…`) whose language the line is spoken in when you send no `language`.textstringThe line to speak, up to 200 characters. Left out, a short greeting of ours.languagestringA language tag such as `hi-IN` or `en`, for the line and the voice.speednumberCartesia only. The speed to hear.volumenumberCartesia only. The volume to hear.emotionstringCartesia only. One of Cartesia's emotions (English only).modelstringCartesia only. A Sonic model other than your key's.pronunciationDictIdstringCartesia 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
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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · queryThe `nextCursor` from the previous page. Leave it out for the first page.agentstring · queryOnly this agent's endpoints (`ag_…`).
curl -X GET "https://app.katexs.com/api/v1/webhooks" \ -H "Authorization: Bearer $API_KEY"
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
agentstringThe agent whose events to send (`ag_…`). Required unless `includeCustomers` is `true`; never with it.includeCustomersbooleanDeveloper workspaces only: one endpoint for the events of every agent in every one of your customers. Send it instead of `agent`.urlstring · requiredAn `https://` URL, or an email address for a helpdesk that opens tickets by mail. Addresses inside our own network are refused.eventsstring[]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.enabledbooleanWhether 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 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
idstring · path · requiredThe endpoint's id (`wh_…`).
curl -X GET "https://app.katexs.com/api/v1/webhooks/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe endpoint's id (`wh_…`).
Body
urlstringA new `https://` URL or email address.eventsstring[]The events to send from now on. Naming every event means every event, now and as new ones are added.enabledboolean`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 Webhook
Removes the endpoint. Nothing more is sent to it, and its delivery history goes with it. A build key may do this.
Parameters
idstring · path · requiredThe endpoint's id (`wh_…`).
curl -X DELETE "https://app.katexs.com/api/v1/webhooks/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe endpoint's id (`wh_…`).
curl -X GET "https://app.katexs.com/api/v1/webhooks/{id}/deliveries" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe endpoint's id (`wh_…`).
curl -X POST "https://app.katexs.com/api/v1/webhooks/{id}/test" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe endpoint's id (`wh_…`).
Body
deliveryIdstringOne delivery (`whd_…`) to send again now.sincestringRe-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 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
daysinteger · queryDays of `daily` to return, ending today (UTC).
curl -X GET "https://app.katexs.com/api/v1/usage" \ -H "Authorization: Bearer $API_KEY"
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
daysinteger · queryA rolling window ending today (UTC). Not with `from`/`to`.fromstring · queryFirst UTC day, YYYY-MM-DD. Needs `to`.tostring · queryLast UTC day, YYYY-MM-DD. Needs `from`.
curl -X GET "https://app.katexs.com/api/v1/usage/daily" \ -H "Authorization: Bearer $API_KEY"
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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · queryThe `nextCursor` from the previous page. Leave it out for the first page.fromstring · queryFirst day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional; either end alone is allowed.tostring · queryLast day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional.formatstring · 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"
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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · queryThe `nextCursor` from the previous page. Leave it out for the first page.fromstring · queryFirst day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional; either end alone is allowed.tostring · queryLast day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional.kindstring · queryOnly rows of this kind.customerstring · queryDevelopers: only charges for this customer workspace.
curl -X GET "https://app.katexs.com/api/v1/wallet/ledger" \ -H "Authorization: Bearer $API_KEY"
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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · queryThe `nextCursor` from the previous page. Leave it out for the first page.fromstring · queryFirst day, YYYY-MM-DD, inclusive, in your workspace's time zone. Optional; either end alone is allowed.tostring · 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 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
daysinteger · queryThe rolling window.
curl -X GET "https://app.katexs.com/api/v1/calls/summary" \ -H "Authorization: Bearer $API_KEY"
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
daysinteger · queryThe rolling window. Ignored when `from`/`to` are given.fromstring · queryRange start, YYYY-MM-DD, your time zone. Needs `to`.tostring · 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 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 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
idstring · path · requiredThe agent's id.daysinteger · queryThe rolling window.rowsinteger · queryCaps `knowledgeGaps` and `topQuestions`.
curl -X GET "https://app.katexs.com/api/v1/agents/{id}/analytics" \
-H "Authorization: Bearer $API_KEY"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"
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
namestringThe new name: 2 to 80 characters (longer is refused), no web or email address, no markup or hidden characters.timezonestringAn IANA time zone, such as `Asia/Kolkata` or `Europe/London`.callRetentionDaysintegernullKeep 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
List Projects
The workspace's projects, newest first, each with how many agents are in it.
Parameters
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
namestring · 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 Project
One project, with how many agents are in it.
Parameters
idstring · path · requiredThe project's id (`proj_…`).
curl -X GET "https://app.katexs.com/api/v1/projects/{id}" \
-H "Authorization: Bearer $API_KEY"Update Project
Renames a project. A build key may do this.
Parameters
idstring · path · requiredThe project's id (`proj_…`).
Body
namestring · 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 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
idstring · path · requiredThe project's id (`proj_…`).
curl -X DELETE "https://app.katexs.com/api/v1/projects/{id}" \
-H "Authorization: Bearer $API_KEY"Teams
List Teams
The workspace's teams, newest first, each with its members' ids and the projects it can reach.
Parameters
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
namestring · 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 Team
One team, with its members' ids and the projects it can reach.
Parameters
idstring · path · requiredThe team's id (`team_…`).
curl -X GET "https://app.katexs.com/api/v1/teams/{id}" \
-H "Authorization: Bearer $API_KEY"Update Team
Renames a team. A build key may do this.
Parameters
idstring · path · requiredThe team's id (`team_…`).
Body
namestring · 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 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
idstring · path · requiredThe team's id (`team_…`).
curl -X DELETE "https://app.katexs.com/api/v1/teams/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe team's id (`team_…`).memberIdstring · 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"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
idstring · path · requiredThe team's id (`team_…`).memberIdstring · 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"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
idstring · path · requiredThe team's id (`team_…`).projectIdstring · path · requiredThe project's id (`proj_…`).
curl -X PUT "https://app.katexs.com/api/v1/teams/{id}/projects/{projectId}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe team's id (`team_…`).projectIdstring · 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
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 Member
One person in the workspace, with their role.
Parameters
idstring · path · requiredThe member's `id`, from List Members.
curl -X GET "https://app.katexs.com/api/v1/members/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe member's `id`, from List Members.
Body
rolestring · 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 '{ … }'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
idstring · 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
List Invitations
Pending invitations, newest first. The link in each is only ever in the email, never here.
Parameters
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
emailstring · requiredThe address to invite. Lower-cased.rolestringThe 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 Invitation
One invitation, whatever its status — pending, accepted or revoked.
Parameters
idstring · path · requiredThe invitation's id (`inv_…`).
curl -X GET "https://app.katexs.com/api/v1/invitations/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe invitation's id (`inv_…`).
curl -X DELETE "https://app.katexs.com/api/v1/invitations/{id}" \
-H "Authorization: Bearer $API_KEY"Notifications
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"
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
metaobjectSend `muted`, `email` or both; the other keeps its value.templatesobjectSend `muted`, `email` or both; the other keeps its value.campaignsobjectSend `muted`, `email` or both; the other keeps its value.callsobjectSend `muted`, `email` or both; the other keeps its value.inboxobjectSend `muted`, `email` or both; the other keeps its value.knowledgeobjectSend `muted`, `email` or both; the other keeps its value.billingobjectSend `muted`, `email` or both; the other keeps its value.systemobjectSend `muted`, `email` or both; the other keeps its value.membersobjectSend `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
List Saved Replies
The workspace's saved replies, newest first.
Parameters
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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"
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
shortcutstring · requiredWhat a teammate types to find it. A leading `/` is dropped; up to 40 characters after that. Unique in the workspace, ignoring case.bodystring · 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 Saved Reply
One saved reply.
Parameters
idstring · path · requiredThe saved reply's `id`.
curl -X GET "https://app.katexs.com/api/v1/saved-replies/{id}" \
-H "Authorization: Bearer $API_KEY"Update Saved Reply
Changes a saved reply's shortcut, body, or both. A build key may do this.
Parameters
idstring · path · requiredThe saved reply's `id`.
Body
shortcutstringA new shortcut. A leading `/` is dropped. Unique in the workspace, ignoring case.bodystringNew 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 Saved Reply
Deletes a saved reply. A build key may do this.
Parameters
idstring · 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
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"
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
namestring · 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 Contact Group
One group and how many contacts are in it.
Parameters
idstring · path · requiredThe group, `grp_…`.
curl -X GET "https://app.katexs.com/api/v1/contact-groups/{id}" \
-H "Authorization: Bearer $API_KEY"Rename Contact Group
Renames a group. Campaigns aimed at it keep reaching it. A build key may do this.
Parameters
idstring · path · requiredThe group, `grp_…`.
Body
namestring · 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 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
idstring · path · requiredThe group, `grp_…`.
curl -X DELETE "https://app.katexs.com/api/v1/contact-groups/{id}" \
-H "Authorization: Bearer $API_KEY"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
idstring · path · requiredThe group, `grp_…`.
Body
contactsstring[] · 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 '{ … }'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
idstring · path · requiredThe group, `grp_…`.
Body
contactsstring[] · 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
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
workflowIdstring · 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
tostring · requiredThe contact's phone number, with its country code.namestringTheir name, used for a new contact and for `{{contact.name}}`.emailstringTheir email, used for a new contact.variablesobjectUp 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 '{ … }'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
limitinteger · queryHow many items to return, 1 to 100.cursorstring · 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 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
workflowIdstring · 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"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
tostring · requiredThe contact's phone number, with its country code.eventstring · requiredThe event's name, as written in the Await block, like `payment_received`.dataobjectAnything 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 '{ … }'