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

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

Returns 201 with the created bot, including its id.

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

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-5
• anthropic/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.