Run a bot

Paths are relative to /api/workspaces/{workspaceId}.

Method	Path	Does
POST	/agents/{agentId}/run	Send a message and get the reply
GET	/agents/{agentId}/thread	Your conversation id with this bot
GET	/conversations/	Your conversations across bots, newest first
GET	/conversations/{conversationId}	One conversation with its messages

Send a message

curl -X POST https://<host>/api/workspaces/{workspaceId}/agents/{agentId}/run \
  -H "Authorization: Bearer $KATA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarise yesterday’s support tickets", "stream": false }'

With "stream": false the call waits for the full reply and returns JSON:

{ "conversationId": "3f1c…", "text": "Yesterday there were 14 tickets…" }

Without it, the response is a server-sent event stream of the run (text, tool calls, approvals) in the AG-UI format that TanStack AI’s useChat reads. The conversation id is in the x-conversation-id response header.

Field	Notes
message	The text to send
conversationId	Continue an existing conversation; omit to start a new one
stream	false for a single JSON response

Only the new message is taken from the request. The history always comes from Kata’s own copy of the conversation, which may include routine runs and notes from other bots.

Note

If the bot handed the conversation to someone else, it stays silent: the message is recorded and the reply is empty.

Conversations are private

Every endpoint here returns only conversations that belong to you — the signed-in member, or the member who created the token. Another member’s conversation is a 404. A request with no person behind it (a token whose creator has left) has no conversations, and GET /agents/{agentId}/thread returns 403.