Koru API

• Store and system13 operationsThe Store's status, its own contracts, backup, import, settings, shutdown, and the sync WebSocket.
• Profiles48 operationsProfiles and their accounts, removal and restore, appearance, personal attributes, dictionary, reminders and workspace usage.
• Workspaces34 operationsWorkspaces, their manifests, listings, pins and lifecycle.
• Documents and search6 operationsDocument location and outline, search, and read-model queries over attributes and tasks.
• AI chats48 operationsAI chats, turns and attempts, messages, tools and tool calls, providers, search, exports and usage.
• Runs and schedules20 operationsWork delegated to an agent as runs, their history and MCP endpoint, and repeating schedules.
• Artifacts19 operationsArtifact families and immutable versions, their provenance and content, and run authorities.
• Terminal sessions19 operationsProcess sessions: create and terminate, controller lease, input, snapshots, scrollback, attachments and output.
• Events4 operationsThe event journal: publish, read pages after a cursor, activity, and a server-sent stream.

The contract's server is http://127.0.0.1, described as loopback only. It does not fix a port: use the one your running Koru gateway listens on. The examples on these pages write it as $PORT.

A running gateway serves this contract at GET /v1/openapi.json, the streaming contract at GET /v1/asyncapi.json, and its own offline pages at /docs and /docs/asyncapi.

http://127.0.0.1 loopback only

Requests carry a bearer token in the Authorization header: Authorization: Bearer <token>. Each operation lists the scopes its token must hold. A missing or unrecognised token answers 401; a token without the operation's scope answers 403.

One operation takes a different token, runBearer:

These need no token: GET /v1/openapi.json, GET /docs, GET /docs/asyncapi, GET /v1/asyncapi.json.

A failed request answers with a JSON body. Store operations use Failure, AI operations use AiFailure. Branch on code, a stable machine-readable token; message is untranslated developer text for logs, not for people.

• Failure
• AiFailure

The terminal session operations declare more about themselves than the others: whether they need the session's controller lease, whether they need an idempotency key, whether they are safe to retry after an unknown outcome, and which stable error code maps to which HTTP status. Each session operation lists these under "Behavior".

Terminal sessions →

Chat turns and retries, Ollama model pulls, run history, schedule lists, the event journal and terminal session output stream as server-sent events, and /v1/sync is a WebSocket. The streaming reference documents the four channels in the AsyncAPI contract: chat turns, Ollama model pulls, session output and sync.