API reference

Caity's Code mode

Coding sessions on your own machine, with your own Claude Code or Codex login.

These routes start and run Caity's Code mode on your own machine: a session runs there through your agent, with your own Claude Code or Codex login, in a folder you allowed with cactive-agent code allow <folder>. Nothing runs on the platform, and your provider login never leaves the machine.

A session's events (messages, steps, command output, approvals, checkpoints) come back in order after the last seq you read. Steps your mode doesn't allow wait for you: answer them with the approval route. Anything outside the folder always asks.

They're for you in person: organization keys and the phone assistant get 403, and another person's machine or session is 404. The device endpoints the agent calls are under Agent device endpoints.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/me/code/devices`	Your machines approved for Code mode, with the folders each allows (`cactive-agent code allow`), whether it's online and whether its agent is ready (full network access, a recent agent with room for a session).
`GET /v1/me/code/sessions`	Your Code mode sessions, newest first (50).
`POST /v1/me/code/sessions`	Starts a Code mode session on one of your own machines, in a folder it allows, with your own Claude Code or Codex login there. `mode` is at most your mode for the assistant in that machine's space; `effort` (low to max) and `plan` (plan mode) are optional; `isolation` (`branch` or `worktree`) with a `branch` starts it on a new branch or in a worktree of its own inside the folder; 409 when the machine isn't approved for Code mode or lacks full network access. `bedrock` is Caity herself: the tools run on the machine, each model step through the platform.
`POST /v1/me/code/cloud-sessions`	A session in the cloud, on one of the person's organisation's repositories (docs/specs/caity/coding.md → Caity in the cloud).
`GET /v1/me/code/sessions/:sessionId`	A session: its machine, folder, provider, mode, status, turns and the approvals waiting for you.
`GET /v1/me/code/sessions/:sessionId/events`	The session's events after `after` (their `seq`), in order, up to 500 (`more` when there are more): messages, steps, command output, approvals, checkpoints.
`POST /v1/me/code/sessions/:sessionId/messages`	Starts a turn with your message, or queues it behind the turn running (a `turn.queued` event). Up to 4 `images` (PNG, JPEG, WebP or GIF as base64, 300 KB together). 409 when the session has ended.
`POST /v1/me/code/sessions/:sessionId/steer`	Sends your message into the turn running (Codex takes it mid-turn; Claude Code's turn stops and the message runs next).
`POST /v1/me/code/sessions/:sessionId/queue/:queued/cancel`	Drops a message waiting in the queue before it starts.
`POST /v1/me/code/sessions/:sessionId/settings`	Changes the session's `mode` (at most your mode for the assistant in its space), `plan` (plan mode), `model` and `effort`, from the agent's next step. Only you, from your own sign-in.
`POST /v1/me/code/sessions/:sessionId/interrupt`	Stops the running turn; approvals waiting in it are declined.
`POST /v1/me/code/sessions/:sessionId/approvals/:requestId`	Allows or declines a step waiting for you (a command, an edit, anything outside the folder). `always` with an allow adds the command to the machine's list for the folder; `feedback` with a decline tells the agent what to do instead. Only you, from your own sign-in: not keys or the phone assistant.
`POST /v1/me/code/sessions/:sessionId/checkpoints/diff`	Asks the machine for the patch between two turns' checkpoints; it arrives as a `checkpoint.diff` event with this command's id.
`POST /v1/me/code/sessions/:sessionId/checkpoints/:turn/restore`	Puts the folder back as that turn's checkpoint left it (files added since are removed; ignored files stay). Only you, and not while a turn runs.
`POST /v1/me/code/sessions/:sessionId/stop`	Ends the session: the turn interrupted, waiting approvals declined, the provider closed on the machine.
`POST /v1/me/code/sessions/:sessionId/files/list`	Asks the machine for the folder's files (git's view: ignored files left out); the answer is the stream `reply-<commandId>`, JSON `{ files, truncated }`.
`POST /v1/me/code/sessions/:sessionId/files/read`	Asks the machine for one file's text (`path`, inside the folder); the answer is the stream `reply-<commandId>`. Binary files, files over 2 MB and files likely to hold secrets come back without their text.
`POST /v1/me/code/sessions/:sessionId/files/write`	Saves your edit to a file on your machine (`path`, `content` up to 300 KB); never a file likely to hold secrets. Only you, from your own sign-in.
`POST /v1/me/code/sessions/:sessionId/changes/diff`	Asks for the changes from checkpoint `fromTurn` to `toTurn`, or to the folder as it is now without `toTurn`; the patch is the stream `reply-<commandId>`.
`POST /v1/me/code/sessions/:sessionId/changes/revert`	Puts `path` back as checkpoint `fromTurn` had it, or undoes one `hunk` of its change in the folder. Not while a turn runs.
`POST /v1/me/code/sessions/:sessionId/terminals`	Opens a terminal on your machine, in the session's folder, as you (`cols`, `rows`; at most 3 at once); a `terminal.opened` event says its id, and its output is the stream `term-<terminalId>`.
`POST /v1/me/code/sessions/:sessionId/terminals/:terminalId/input`	Types into a terminal (`data`, up to 4,096 characters). Each line is recorded in the session and the audit log; one typed at a password prompt as hidden. Only you, from your own sign-in.
`POST /v1/me/code/sessions/:sessionId/terminals/:terminalId/resize`	Changes a terminal's size (`cols`, `rows`).
`POST /v1/me/code/sessions/:sessionId/terminals/:terminalId/close`	Closes a terminal; a `terminal.closed` event follows.
`POST /v1/me/code/sessions/:sessionId/git/status`	Asks the machine for the folder's git status: its branch, upstream, ahead and behind, remote (no credentials), changes and recent commit summaries; the answer is the stream `reply-<commandId>`.
`POST /v1/me/code/sessions/:sessionId/git/diff`	Asks the machine for the folder's changes against its last commit, new files too, with known kinds of keys taken out; the answer is the stream `reply-<commandId>`, JSON `{ diff, truncated }`.
`POST /v1/me/code/sessions/:sessionId/git/branch`	Makes a new branch (`name`) where the folder is and switches to it; a `git.branched` event follows. Not while a turn runs. Only you, from your own sign-in.
`POST /v1/me/code/sessions/:sessionId/git/commit`	Commits every change in the folder with `message`, as you (your git identity and hooks on the machine); a `git.committed` event says its sha. Not while a turn runs. Only you, from your own sign-in.
`POST /v1/me/code/sessions/:sessionId/git/push`	Pushes the folder's branch to its upstream, or to `origin` as its upstream, with your credentials on the machine; a `git.pushed` event follows. Only you, from your own sign-in.
`POST /v1/me/code/sessions/:sessionId/git/message`	A commit message drafted by the assistant's fast model from `diff` (as `git/diff` answered it; the first 60 KB, keys taken out) and `recent` commit summaries for their style; on your allowance in the session's space. Answers `{ message }`.
`GET /v1/me/code/sessions/:sessionId/streams/:stream`	A stream's pieces after `after` (a command's reply or a terminal's output), in order, kept an hour; a reply read to its end is gone.