Agents
An agent is a bot. Paths are relative to /api/workspaces/{workspaceId}.
| Method | Path | Does |
|---|---|---|
GET |
/agents/ |
List bots, most recently active first |
POST |
/agents/ |
Create a bot |
GET |
/agents/{agentId} |
Read one bot |
PATCH |
/agents/{agentId} |
Update fields you send |
DELETE |
/agents/{agentId} |
Delete the bot and its conversations |
POST |
/agents/{agentId}/takeover |
Take over a departed member’s private bot |
Create a bot
Section titled “Create a bot”curl -X POST https://<host>/api/workspaces/{workspaceId}/agents/ \ -H "Authorization: Bearer $KATA_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Blog Pulse", "title": "Reviews the site every day", "instructions": "You are the daily reviewer for our blog...", "skillAuthoring": "own" }'| Field | Required | Notes |
|---|---|---|
name |
yes | |
title |
no | One-line description shown under the name |
instructions |
no | The bot’s system prompt |
model |
no | Defaults to auto; see below |
skillAuthoring |
no | workspace (default), own or off — see Skills |
avatar |
no | A face as shape/color, e.g. squircle/#0a84ff; omitted, one is derived |
visibility |
no | workspace or private; see below |
Returns 201 with the created bot, including its id.
Update a bot
Section titled “Update a bot”PATCH accepts any of the fields above, plus:
pinned: true | false— pin to the top of the list (pinning un-archives).archived: true | false— archive or restore (archiving un-pins).avatar: ""— clear the chosen face.
Deleting a bot leaves workspace skills and tools in place; the bot only held links to them.
Models
Section titled “Models”model is auto or one of:
openai/gpt-6-luna,openai/gpt-6-sol,openai/gpt-5.6-luna,openai/gpt-5.4-nano,openai/gpt-5.4-mini,openai/gpt-5.2,openai/gpt-5.1,openai/gpt-5anthropic/claude-opus-4-8,anthropic/claude-opus-4-7,anthropic/claude-sonnet-4-6,anthropic/claude-haiku-4-5
An unknown value returns 400 with the list.
Who sees a bot
Section titled “Who sees a bot”visibility is workspace (every member lists it and talks to it) or private
(only its creator — nobody else, the owner and admins included). Making a bot
workspace needs the bot: publish permission; a new bot is workspace when
the caller holds it, private otherwise. Another member’s private bot is a
404 everywhere.
When a private bot’s creator leaves the workspace, a role with bot: edit sees
it in the list with "orphaned": true and can POST /agents/{agentId}/takeover.
The bot becomes theirs, still private. The departed member’s conversations and
memories with it stay closed.