API reference

Every path is prefixed with /api.

Authorization — the access key: Authorization: Bearer <key>, the X-Api-Key header, or ?token= in the address (the last one is needed for SSE and images, where there is no way to set a header). The main API_KEY or any named key will do. There is no login-and-password.

Authentication

Method	Path	Description
GET	/auth/verify	check the key → {ok, mode, subject}
GET	/auth/connection	the address and key for the connection QR code
GET	/health	liveness check, no authorization

Projects and sessions

Method	Path	Description
GET	/projects	the list of projects from every source
POST	/projects/rescan	a full re-parse of the transcripts (the "pull down" gesture)
PATCH	/projects/:project	{title} — your own project name, empty resets it
POST	/projects/:project/favorite	{favorite} — pin the project to the top
GET	/projects/:project/sessions	the project's sessions
GET	/projects/:project/sessions/:id?offset&limit&tail=1	a session's records, page by page
PATCH	/projects/:project/sessions/:id	{title} — your own chat name
POST	/projects/:project/sessions/:id/favorite	{favorite} — pin the chat
POST	/projects/:project/sessions/:id/read	"read all the way down"
POST	/projects/:project/sessions/:id/view	"the chat was opened" — the list is sorted by this
POST	/sessions/read-all · /projects/:project/sessions/read-all	mark everything as read
GET	/projects/:project/sessions/:id/prompts	the numbers of your own messages (the "↑" button)
GET	/projects/:project/sessions/:id/image?record=&block=&agent=	an image from a record
GET	/projects/:project/sessions/:id/subagents	the session's subagents
GET	/projects/:project/sessions/:id/subagents/:agentId	a subagent's records
GET	/projects/:project/sessions/:id/export?tools=&thinking=&system=	the chat as one Markdown file
GET/POST	/projects/:project/sessions/:id/shares	read-only links to the chat: list and issue {hours, full?} (hours — 1, 24 or 168)
DELETE	/shares/:id	revoke a link
POST	/projects/:project/sessions/:id/message	a message into a session run by a foreign process (or by the host bridge)
DELETE	/sessions/:id/inbox/:messageId	take such a message back before a hook picks it up
GET	/sessions/search?q=&limit=	search over titles and conversations
POST	/sessions/:id/relay	{enabled} — answer this session's questions from Clauder
POST	/sessions/:id/question/answer	an answer to a question of a session Clauder doesn't run
GET	/favorites	pinned projects and chats in one response
GET/POST	/hidden · /hidden/merge	hidden projects and chats
GET/PUT	/client-prefs	a snapshot of client settings for moving to a new device
GET/POST	/user-data?mode=replace	titles, favourites, hidden and read marks as one file

Token spend and traffic

Method	Path	Description
GET	/usage?days= or ?from=&to=	spend by day, model and project
GET	/usage/window	the current 5-hour window across all sessions
GET	/usage/timeline?hours=	the dashboard's series: by hour and the window's fill
GET	/usage/net?hours=	the api's own network usage, split by client
GET/PUT	/usage/budget	the daily spending cap: thresholds {warnUsd, stopUsd}, spend and level; only the owner changes it

The agent

Method	Path	Description
GET	/agent/status	permission mode, limits, allowed roots, defaultEffort
GET	/agent/models	models and effort levels from the CLI
GET	/agent/rate-limits	plan limit utilisation
GET	/agent/workspaces	directories available as cwd
GET	/agent/browse?path=	a directory's contents for picking cwd
POST	/agent/mkdir	{path, name} — a new folder
GET	/agent/recent	the directories of recent sessions
GET	/agent/active	who is working now: chats, subagents, background tasks
GET	/agent/runs?sessionId=	active agent sessions
POST	/agent/runs	{cwd, prompt?, resume?, fork?, model?} → start
GET	/agent/runs/:id	the session's state, including a hanging question
POST	/agent/runs/:id/messages	{text} — a message into the session
POST	/agent/runs/:id/ask	a side question (/btw) in the same conversation
POST	/agent/runs/:id/answer · /answer/skip	an answer to the model's question, and skipping it
POST	/agent/runs/:id/permission	allow / always / deny for a permission request
DELETE	/agent/runs/:id/queue/:messageId	remove a message from the CLI's queue
POST	/agent/runs/:id/model · /effort · /ultracode	change model, effort, ultracode mode
POST	/agent/runs/:id/workflows	allow workflows (restarts the session)
POST	/agent/runs/:id/permission-mode	change the permission mode
POST	/agent/runs/:id/budget	a spending cap for one session (restarts it)
GET	/agent/runs/:id/context · /cost	what fills the context window; cost and duration
GET	/agent/runs/:id/mcp · /agent-types	MCP server state; subagent types
POST	/agent/runs/:id/retry · /interrupt	retry a failed request; interrupt the reply
DELETE	/agent/runs/:id	end the session
POST	/agent/sessions/:id/terminate	end the session, whoever is running it

Git

Method	Path	Description
GET	/git/status?cwd=	branch, upstream, files with index and tree states
GET	/git/diff?cwd=&path=&staged=	the diff of one file
GET	/git/log?cwd= · /git/branches?cwd=	recent commits; local branches
POST	/git/stage · /git/unstage · /git/discard	the index and discarding changes
POST	/git/commit	{message, all} — commit, with a fresh status in the response
POST	/git/checkout	{branch, create} — git switch [-c]
POST	/git/suggest	a commit message from the model
GET/POST	/git/worktrees · /git/worktree · /git/worktree/remove	working copies

Your own model servers

Method	Path	Description
GET/POST	/providers	the list of servers (without keys) and adding one
PATCH/DELETE	/providers/:id	editing (an empty apiKey means "keep the stored one") and deleting
GET	/providers/:id/key	a server's key as a separate request
POST	/providers/:id/models	re-read the model list from the server
POST	/providers/probe	the connection check, step by step

The second agent (opencode)

Method	Path	Description
GET	/opencode/status	whether the server is up and which models it has
GET/POST	/opencode/sessions	the chat list and a new chat
GET/DELETE	/opencode/sessions/:id	the whole feed, or deleting a chat
GET	/opencode/sessions/:id/stream?after=	SSE: records from a number, questions and busy state
POST	/opencode/sessions/:id/message · /interrupt	a message and "Stop"
POST	/opencode/sessions/:id/question/:requestId · /permission/:requestId	answers to a question and to a permission request

Files, command output, terminal

Method	Path	Description
GET	/files?path=&offset=&limit=	a directory, or a window of a file's lines
GET	/files/raw?path=&token=	an image's bytes
GET	/files/diff?path=	the diff of one file
GET	/files/complete?cwd=&q=&limit=	@ completion: paths in the chat's folder by the start or a piece of the name
POST	/files/mkdir	{path, name} — a new folder in the open directory
POST	/files/put	{path, name, data, relative?} — a file into the same place (base64, one at a time)
GET	/output · /output/stream	the tail of a running command's output, and the same as a stream
GET	/commands	the catalogue of composer slash commands
GET	/terminal · /terminal/:id	the open shells and one of them
POST	/terminal	{cwd, cols?, rows?} — open one
GET	/terminal/:id/stream	SSE: hello, the accumulated output, live output, exit
POST	/terminal/:id/input · /resize	input and window size
DELETE	/terminal/:id	close the shell

Events, hooks, notifications

Method	Path	Description
GET	/events/stream?token=&sources=&project=&session=	SSE: the file system, hooks, agent statuses
POST	/hooks/ingest	receiving hook events (X-Hook-Token)
POST	/hooks/question	a question from a PreToolUse hook; held until a client answers
POST	/hooks/inbox	the Stop hook picks up messages accumulated for its session
GET/PUT	/hooks/targets	the Clauder addresses in the CLI's own settings.json
GET	/push/key · /push/state?endpoint=	the public VAPID key; subscription toggles
POST	/push/subscribe · /push/unsubscribe	create or forget a subscription
POST	/push/watch · /push/unwatch · /push/test	watch a session, stop watching, a test push
GET/POST	/presence	whether the owner is at the machine; an open page's mark (once a minute)

Read-only link

No access key: the token from the link lets you in, and only to these two endpoints.

Method	Path	Description
GET	/share/:token?before=&after=	the chat's feed for the guest: a window of records, then by record numbers. Expired — 410, revoked or unknown — 404
GET	/share/:token/image?record=&block=	an image from a message

The app and the bot

These sections answer only in the desktop build (in a container — 403).

Method	Path	Description
GET/PATCH	/desktop/network	listen on the loopback or the network, the port, the machine's addresses
PATCH	/desktop/api-key	set your own access key or issue a new one
GET/POST/PATCH/DELETE	/desktop/api-keys	named keys: the list, issuing, editing scope and rights, revoking
GET/PATCH	/desktop/settings	mode, autostart, tray, always-on-top, hotkey, notifications
POST	/desktop/window	open a web UI route in a separate window
GET	/desktop/sources	which session directories the server actually reads
POST	/desktop/companions	look for the other side (WSL/Windows) again
GET	/telegram/state	the bot's state and the linked chats
PATCH	/telegram/token · /telegram/app-url	the token and the address for "Open" buttons
POST	/telegram/pairing · /telegram/test	a one-time linking code; a test message
PATCH/DELETE	/telegram/chats/:chatId	a chat's settings, or unlinking