API overview
Everything you can do in the app is available over REST, including creating and running bots. An agent can use the same API to build other agents.
Base URL and paths
Section titled “Base URL and paths”Every resource lives under its workspace:
https://<your-kata-host>/api/workspaces/{workspaceId}/...The path names the workspace; the credential only proves who you are. {workspaceId}
may be the workspace id or its slug.
Authentication
Section titled “Authentication”Send an API token as a bearer token:
curl https://<your-kata-host>/api/workspaces/ \ -H "Authorization: Bearer kata_..."A token belongs to one workspace, and GET /api/workspaces/ returns that one — the
quickest way to find your workspaceId. Tokens start with kata_ and are shown once,
when created.
A token has full authority inside its workspace and none outside it:
- It cannot create workspaces, invite people or change membership.
- It cannot install or change plugins; those need a signed-in member.
- For private things — conversations, memory, routines — it acts as the member who created it, while that person is still a member.
Requests and errors
Section titled “Requests and errors”Send JSON with Content-Type: application/json. Errors are plain-text bodies:
| Status | Meaning |
|---|---|
400 |
The body is missing a field or has an invalid value |
401 |
No valid credential |
403 |
The credential can’t do this (for example, a token inviting someone) |
404 |
Not found — also returned for another workspace, or another member’s private data |
409 |
Conflict, such as a name already in use |
A token used against a workspace it doesn’t belong to gets 404, not 403, so
probing ids reveals nothing.