HTTP API Reference

Loop exposes a lightweight HTTP API for managing channels, threads, messages, tasks, tickets, files, memory, and real-time events. All endpoints are prefixed with /api/.

Related docs: Terminal WebSocket | Events System | Memory System | Kanban Panel

General

• Authentication: Every route except the few listed under Authentication needs a token. See that section.
• CORS: All responses include Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS, and Access-Control-Allow-Headers: Content-Type, Authorization. Preflight OPTIONS requests return 204 No Content. CORS grants nothing on its own: without a token a page on another origin only gets 401s.
• Content-Type: JSON endpoints return application/json. File-reading endpoints return text/plain; charset=utf-8.
• Error responses: Plain text body with the appropriate HTTP status code.

Common Error Codes

Authentication

Every API caller is either the owner or an agent. Nothing is trusted for where it comes from: no cookies, no origin checks, and localhost gets no pass.

Tokens

The owner token’s directory is never a channel dir and never mounted into a container, whatever the config says.

Send the token as a header:

Authorization: Bearer <token>

Browsers can’t set headers on a WebSocket, so WebSocket clients send it as a subprotocol instead: Sec-WebSocket-Protocol: loop, loop.token.<token>. The server answers with loop.

Rotating. loop api:rotate-token, Developer → Rotate API Token… in the desktop app, or POST /api/auth/rotate with the owner token writes a new owner token and the daemon switches to it at once. The CLI reads the file on every request and the desktop app reads it again on its next 401, so both carry on without a restart. A browser tab opened with loop app:url needs a fresh URL. Agent tokens are unaffected.

Browser mode. A UI running in a plain browser tab, without the desktop app’s preload, has no file to read. loop app:url prints the UI’s URL with the token in the fragment (#loop_token=...); the UI moves it to the tab’s sessionStorage and drops it from the address bar. Fragments aren’t sent to the server, but anyone with the URL has full access, so treat it as a secret.

Agent scope

An agent token works only on the routes in-container clients call (the table is agentRoutes in internal/api/agent_scope.go): messages, threads, tasks, shortcuts, memory, PR/MR status (GET /api/channels/{id}/pr/status), playground, workflows, learn proposals, review, quality, the UI bridge (GET /api/ui/state, POST /api/ui/commands), and the browser action. Every other route answers 403, among them config, terminals, gates, images, token rotation and content links.

On the routes it may call, an agent is held to its own project. Every channel, thread, task, workflow run and dir_path a request names, in the path, the query or the JSON body, must be the agent’s own channel or dir, or share its project root (after symlinks). A request that names anything else gets 403. The exception is POST /api/messages (the send_message tool): its channel_id may be any channel, so one agent can hand work or news to another project’s channel. Agents may also only change project bash shortcuts, and can’t start workflows while workflow_bash_local runs workflow bash on the host. The routes that change review comments (delete, edit, assess a thread, push one, push all) are held to the agent’s own channel, not its project: they act on the PR as the user. An agent may not delete a GitHub comment, and may not approve a PR (POST .../review/approve is owner only).

On the UI bridge, an agent’s command must start with select_channel to a channel of its project, and every select_channel in it must name a channel of the project. GET /api/ui/state leaves out the state of windows showing a channel outside it. The UI WebSocket stays owner-only.

Listings an agent makes, such as a channel’s sessions with the ids imported into other channels, name only its project’s items, and a refusal names what the request named: another project’s task or run is refused by its id, not its channel. agent_scope_spec_test.go checks this over a daemon serving two projects: every agent route, with each of the other project’s ids in each place a handler reads one, shows and changes nothing of the other project’s (GET /api/channels lists every channel by design).

Public routes

POST /api/auth/rotate

Owner only. Writes a new owner token and switches to it. Returns 204 No Content.

POST /api/content-caps

Owner only. Iframes, images, video and <base href> can’t send an Authorization header, so the UI loads them through a short-lived signed link instead. Returns a base URL that serves one channel root’s files, one playground or one plugin’s panels.

Request body:

Response (200):

{"base_url": "/c/<cap>/", "expires_in_sec": 3600}

The link is signed with a key that lives only in the running daemon, so links stop working when it restarts. The UI mints a new one well before expiry.

GET /c/{cap}/{path...}

Serves path under what the link names, like GET /api/channels/{id}/raw/{root}/{path...} and the playground routes do, with the same path checks: a path that leaves the root, symlinks included, gets 400. A bad or expired link gets 403 link expired or invalid. Playground pages are sent with Content-Security-Policy: sandbox allow-scripts allow-forms allow-modals allow-popups allow-downloads, which gives them an opaque origin: agent-written JavaScript can’t read the UI’s storage even when both are served from the same origin.

A plugin link serves the files under the plugin’s /loop-plugin/ui/, so path starts with ui/, as a panel’s entry does. It answers 403 unless the plugin may run and the owner approved ui.panel. Files are sent with Cache-Control: no-store and a policy that sandboxes the page the same way and lets it load scripts, styles, images, fonts and fetches only from the link itself (plus data:/blob: for images, fonts and media), with no inline scripts, frames or form submission.

Health

GET /api/health

Returns server health status.

Response (200):

{"status": "ok"}

Channels

GET /api/channels

List all channels with optional filtering. Enriches each channel with container running status, agent running status, and current git branch.

Query Parameters:

Response (200):

[
  {
    "channel_id": "abc123",
    "name": "my-project-a1b2",
    "dir_path": "/home/user/projects/my-project",
    "display_path": "~/projects/my-project",
    "parent_id": "",
    "active": true,
    "container_running": true,
    "agent_running": false,
    "review_running": false,
    "branch": "main",
    "commit": "abc1234",
    "worktree": false,
    "locked": false,
    "last_activity_at": "2026-03-25T14:30:00Z"
  }
]

Behavior notes:

• When a channel has no dir_path, falls back to ~/.loop/{channel_id}/work.
• display_path is dir_path with the daemon user’s home dir shown as ~, for display; the header shows it.
• container_running is determined by querying the Docker daemon for running containers.
• agent_running indicates whether an active Claude agent run exists for the channel. A run is registered before its agent.status “running” event is broadcast, so a response to a request made after that event reflects the run.
• review_running is true while a review run or a dedup pass runs on the channel’s review session (its status is reviewing, or verifying during the verification step ). Review sessions live in the daemon’s memory, so this comes from the review store, not the database. The sidebar shows the channel as running and patches the flag live from review.status events.
• review_max_iterations is the project’s review.max_iterations (global, then project and worktree config; 3 unless set), where the Review panel’s pass count starts.
• branch is resolved by running git rev-parse --abbrev-ref HEAD in the channel’s directory.
• commit is the short commit hash from git rev-parse --short HEAD, and subject its subject line.
• upstream is the branch’s tracking branch (e.g. origin/main), with ahead / behind counting the commits between them. Omitted when there’s none.
• sync_base is set on a worktree thread whose base branch still resolves, with base_ahead / base_behind counting the commits between the checkout and it.
• worktree is true for threads created via POST /api/worktrees.
• root_dir_path is set on rows inside a worktree chain — the worktree thread itself, a thread under it (e.g. a scheduled task’s), or a worktree cut from another worktree — and holds the dir_path of the non-worktree checkout the chain was cut from. Omitted everywhere else. The Kanban panel uses it for its Local/Root board switch.
• model_override / effort_override are the model and effort picked for the channel (see PATCH /api/channels/{id}/agent-config ). Omitted when it inherits the config’s.
• last_activity_at is when the channel’s newest message was written, or when its review session last changed if that’s later, since a review writes no messages. Omitted when it has neither, or when the message lookup fails and there’s no review session (the list is still returned). The sidebar’s Recent section sorts by it.
• description is what the channel or thread is for, set via POST /api/channels/{id}/description . Omitted when empty.
• ticket_url is the URL of the channel or thread’s ticket, set via POST /api/channels/{id}/ticket . Omitted when unset.
• trust_pending is true when the project config’s host-reaching fields changed since you last trusted them, so they don’t apply yet (see GET /api/config/project/trust ). For a worktree chain it’s the root checkout’s config. Omitted otherwise, and when the config can’t be read.
• pr_attention is what the thread’s PR/MR needs (see PR watching ): failed for a failure no agent is fixing, which lights the sidebar’s ci pill, fixing while the thread’s agent was sent to fix one (ci…), or conflict for a merge conflict with the base (cnf), which is always the owner’s to resolve. Omitted otherwise, and when PR watching is off. The sidebar patches it live from channel.pr events.
• unresolved_threads counts the PR/MR’s unresolved review threads, which light the sidebar’s cmt pill. Omitted when there are none, and when PR watching is off. Patched live from channel.pr events.
• plugin_badges are the badges plugins set on the row with PUT /api/plugin/v1/badge , as [{"plugin_id", "text", "title"?}] in plugin id order. Omitted when there are none, when plugins are off, or when the lookup fails. The sidebar patches them live from plugin.badge events.
• task_id is set on a thread a scheduled task created for its output: the id of that task. Omitted on every other channel and thread, including ones that host tasks. The sidebar’s hide-task-threads toggle filters on it.
• locked is true when the channel/thread is guarded against accidental deletion (toggle via PATCH /api/channels/{id}/lock ). DELETE /api/channels/{id} and DELETE /api/threads/{id} return 409 Conflict while a row is locked.
• Hidden learn and explain threads (kind: "learn" or "explain", see Learn and Explain ) are left out of the list.

Errors: 501 if channel listing is not configured.

POST /api/channels

Ensure a channel exists for the given directory path. If a channel already maps to the directory on the specified platform, its ID is returned. Otherwise, a new channel is created on the chat platform and stored in the database.

Request:

{
  "dir_path": "/home/user/projects/my-project",
  "platform": "discord"
}

Response (200):

{"channel_id": "abc123"}

Behavior notes:

• Channel name is derived from filepath.Base(dir_path), sanitized to lowercase alphanumeric/hyphens/underscores, with a random hex suffix.
• On Discord/Slack platforms, invites the bot owner and sets the channel topic to the directory path.

Errors: 400 if dir_path is empty. 501 if channel creation is not configured.

POST /api/channels/create

Create a new channel with an explicit name.

Request:

{
  "name": "my-channel",
  "author_id": "user123",
  "channel_id": "source_channel_for_platform_lookup",
  "platform": "local"
}

Response (201):

{"channel_id": "abc123"}

Errors: 400 if name is empty. 501 if channel creation is not configured.

POST /api/channels/ensure-all

Ensure a channel exists for the given directory on all configured platforms.

Request:

{"dir_path": "/home/user/projects/my-project"}

Response (200):

[
  {"platform": "discord", "channel_id": "abc123", "created": false},
  {"platform": "slack", "channel_id": "C0123456", "created": true}
]

Errors: 400 if dir_path is empty. 501 if channel creation is not configured.

DELETE /api/channels/{id}

Delete a channel and all its child threads.

Path Parameters:

Response: 204 No Content

Behavior notes: Deletes child threads (channels with matching parent_id) before deleting the channel itself. Removes the MCP config files of the channel, its threads and their hidden learn and explain threads (.loop/mcp-<id>.json, and .loop/mcp-<id>-learn.json / .loop/mcp-<id>-explain.json for a hidden thread, each in its own dir), unless keep_mcp_configs is set for the channel’s project. Cancels a learn pass or explanation still running or queued, deletes the hidden threads’ forked session files, and removes the channel’s containers.

Errors: 404 if channel not found. 409 if the channel (or any of its threads) is locked. 501 if channel deletion is not configured.

PATCH /api/channels/{id}/lock

Toggle the locked flag on a channel or thread. Locking guards against accidental UI deletes — an unlock is required before the corresponding DELETE /api/channels/{id} or DELETE /api/threads/{id} will succeed (they return 409 Conflict otherwise).

Path Parameters:

Request:

{"locked": true}

Response: 204 No Content

Behavior notes: Broadcasts a channel.locked event with the new state so other clients update their sidebar/menus.

Errors: 404 if channel not found. 501 if channel locking is not configured.

POST /api/channels/{id}/rename

Rename a channel, thread or worktree thread’s display name. Only the name changes — the directory path, git branch and Claude sessions are untouched.

Path Parameters:

Request:

{"name": "New Name"}

Response: 200 OK

{"channel_id": "abc123", "name": "New Name"}

Behavior notes: Broadcasts a channel.updated event carrying the new name so other clients refresh their sidebar live.

Errors: 400 if name is empty. 404 if channel not found.

POST /api/channels/{id}/description

Set a channel, thread or worktree thread’s description, shown in the sidebar’s row info popup. An empty description clears it.

Path Parameters:

Request:

{"description": "Fixes the login redirect"}

Response: 200 OK

{"channel_id": "abc123", "description": "Fixes the login redirect"}

Behavior notes: Allowed on locked rows. Broadcasts a channel.updated event carrying only the new description, so other clients refresh their sidebar live.

Errors: 400 if the body isn’t valid JSON or the description is longer than 500 characters. 404 if channel not found. 501 if not configured.

POST /api/channels/{id}/ticket

Link a channel, thread or worktree thread to its ticket in any tracker (Jira, GitHub, Linear, …), shown in the sidebar’s row info popup. An empty ticket_url clears it.

Path Parameters:

Request:

{"ticket_url": "https://example.atlassian.net/browse/PROJ-123"}

Response: 200 OK

{"channel_id": "abc123", "ticket_url": "https://example.atlassian.net/browse/PROJ-123"}

Behavior notes: Allowed on locked rows. Broadcasts a channel.updated event carrying only the new ticket_url, so other clients refresh their sidebar live.

Errors: 400 if the body isn’t valid JSON, or the URL isn’t an absolute http(s) URL or is longer than 2048 characters. 404 if channel not found. 501 if not configured.

Threads

POST /api/threads

Create a new thread under a parent channel. If the channel ID points to a thread, resolves to its parent channel automatically.

Request:

{
  "channel_id": "parent_channel_id",
  "name": "Thread title",
  "author_id": "user123",
  "message": "Initial message for the thread"
}

Response (201):

{"thread_id": "thread_abc123"}

Behavior notes:

• When an IncomingMessageHandler (orchestrator) is configured, the initial message is not stored via CreateThread. Instead, HandleThreadCreated is called asynchronously to store it as a user message and trigger the agent.
• Broadcasts a channel.created event to the parent channel via the EventsHub.
• Thread inherits the parent’s dir_path, session_id, permissions, guild_id, and platform.

Errors: 400 if channel_id or name is empty. 501 if thread creation is not configured.

POST /api/threads/{id}/fork

Forks a thread: creates a sibling thread that continues the source thread’s conversation. The new thread copies the source’s Claude session id (marked fork-pending) and imports its history for display; the orchestrator runs the fork’s first message with --fork-session, so the two threads diverge instead of clobbering each other — the SOURCE thread keeps its session untouched.

For worktree threads, the fork additionally creates a new git worktree branched from whatever the source worktree has checked out: its current branch, whatever it’s named, or its commit when HEAD is detached. It starts from the committed state; uncommitted changes stay behind. The new thread’s base_branch is set to that branch (or commit) so its diff shows only the fork’s own delta. The source’s transcript is copied from the source worktree’s own Claude project dir (a worktree thread’s transcripts live there, not under the parent channel’s) into the new worktree’s, and its history is imported from there. When the source has no session, or its transcript is gone, the fork starts with no session rather than the parent channel’s.

Response (201):

{ "thread_id": "abc123", "worktree_path": "/path/to/.worktrees/wt-1a2b" }

worktree_path is present only for worktree forks. Errors: 400 when the id is not a thread or is a hidden learn thread (thread not found); 500 on git/store failures.

POST /api/channels/{id}/messages/{msgId}/fork

Forks a channel’s or thread’s conversation at one of its messages: like POST /api/threads/{id}/fork , but the new thread’s session is cut at that message. msgId is the message’s msg_id. The fork of a top-level channel is a new thread under it, and the fork of a thread is a sibling thread.

• Agent reply: the reply must record where it sits in its session’s transcript; such messages carry "forkable": true in the message list, the timeline and message.created events. The new thread holds the reply’s session with fork_pending and the reply’s transcript uuid. Its first run resumes with --fork-session --resume-session-at=<uuid>, so it keeps the reply and drops everything after it. See Orchestrator: Fork at a turn .
• User message: Claude Code doesn’t report a prompt’s uuid, so Loop finds it when the message’s run ends: it walks the transcript back through parentUuid from the run’s first reply that records a uuid to the prompt, and records the prompt’s uuid on the message. The fork cuts at the entry before the prompt. A message from before Loop recorded prompts is located the same way at fork time, from its first reply that records a uuid. When the prompt started its session, the new thread starts with no session. Either way, the response’s prompt is the message’s text, for the composer to offer again.

The history up to the cut is imported into the new thread for display. Worktree threads also get a new worktree, as in the thread fork.

Response (201):

{ "thread_id": "abc123", "prompt": "the user message, for a fork at one" }

worktree_path is present for worktree forks, and prompt only for a fork at a user message.

Errors:

• 404: the channel doesn’t exist or is a hidden learn or explain thread, or it has no such message.
• 409: the message can’t be forked at. This covers a reply with no transcript position, a user message with no such reply, and a transcript that is missing or doesn’t contain the reply.
• 500: git or store failures.
• 501: not configured.

DELETE /api/threads/{id}

Delete a thread.

Path Parameters:

Response: 204 No Content

Behavior notes: Deletes from the chat platform (if a creator is configured) and removes from the database, then cancels the runs of its hidden learn and explain threads, deletes their forked session files and removes the MCP config files of the thread and those threads, unless keep_mcp_configs is set for the parent channel’s project. If the thread has an associated git worktree, the worktree and its branch are cleaned up automatically.

Errors: 409 if the thread is locked (toggle via PATCH /api/channels/{id}/lock ). 501 if thread deletion is not configured.

Messages

POST /api/messages

Send a message to a channel. When an orchestrator is configured, routes through it asynchronously so Claude can respond.

Request:

{
  "channel_id": "abc123",
  "content": "Hello, bot!",
  "mode": "plan",
  "interrupt": false,
  "delay_seconds": 0
}

Response: 204 No Content, or with delay_seconds > 0, 200 OK with the queued message’s id, so the caller can remove it with DELETE /api/messages/{id} before it runs:

{"msg_id": "ask-3f2a…"}

Behavior notes:

• When an IncomingMessageHandler is set, the message is dispatched asynchronously with a detached context (the HTTP response returns immediately).
• When no handler is set, falls back to direct PostMessage via the configured message sender.
• interrupt=true requires both a RunCanceller and a Store on the server; the orchestrator wires both during startup.
• delay_seconds > 0 routes through HandleIncomingMessageDelayed with a msg_id picked by the handler, which stamps not_before on the inserted row. Because the row is not yet due, the immediate drain claims nothing; the orchestrator’s delay poller re-drains the channel once not_before passes (this also recovers pending delays across a daemon restart, since the drain is event-driven).

Errors: 400 if channel_id or content is empty. 501 if message sending is not configured and no handler is set.

DELETE /api/messages/{id}

Remove a waiting user message from a channel’s queue before the orchestrator dispatches it.

Path Parameters:

Query Parameters:

Response: 204 No Content

Behavior notes:

• Only deletes rows where is_bot = 0 AND is_processed = 0 AND is_running = 0 — bot replies, already-processed history and a message an agent has already claimed can never be removed through this endpoint.
• On success, broadcasts a message.deleted WebSocket event so connected clients remove the message from their local state.
• A queued row deleted while another run is in progress simply never gets claimed: ClaimNextPending only sees is_processed=0 AND is_triggered=1 AND is_running=0 rows, so the atomic claim transaction can never hand the deleted row to an agent.

Errors: 400 if channel_id is missing. 404 if no matching deletable row exists (message missing, already processed or running, or is a bot message). 500 on database error. 501 if message deletion is not configured.

GET /api/channels/{id}/sessions

List Claude Code session JSONL files for a channel’s project directory.

Path Parameters:

Response:

{
  "current_session_id": "4482da1c-831c-...",
  "sessions": [
    {
      "session_id": "4482da1c-831c-...",
      "last_modified": "2026-03-25T14:30:00Z",
      "last_message": "I've updated the configuration file..."
    }
  ],
  "imported_session_ids": ["4482da1c-831c-..."]
}

Sessions are sorted by modification time (newest first). last_message is extracted from the last assistant or user message in the JSONL file (last 32KB reverse-scanned). current_session_id is the session currently associated with the channel. imported_session_ids lists the session ids already held by a channel or thread.

Learn passes’ sessions aren’t importable and are left out: every pass forks a new session file into the channel’s project dir. A file is taken for one when its id is a learn thread’s own session (not the reviewed run’s, which a learn thread holds with fork_pending until its pass forks it), or when the first prompt it logs (the first queue-operation enqueue in its first 64KB, which Claude writes at the top of a --print session, before the history a fork copies in) is a learn pass’s trigger message. Explanations’ sessions are left out the same way.

PUT /api/channels/{id}/session

Switch the channel to another of its project’s Claude sessions, so its next run resumes that conversation. The Sessions panel’s resume here button and the resume_session MCP tool call it.

Request:

{ "session_id": "4482da1c-831c-..." }

• The session must be a transcript in the channel’s project dir, as listed by GET /api/channels/{id}/sessions .
• The chat’s messages are left as they are.
• A session another channel or thread also holds is stored with fork_pending, so the next run starts with --fork-session instead of writing into the other’s conversation.
• While a chat run is in progress in the channel, the switch is held (in memory) and applied when the run ends, after the run saves its own session id.

Response:

{ "deferred": false }

deferred is true when the switch waits for the run in progress.

Errors: 400 for a missing or malformed session_id, or a channel with no project dir. 404 if the channel or the session isn’t found. 500 on database error. 501 if session switching is not configured.

GET /api/channels/{id}/agent-config

Return the channel’s per-channel model/effort overrides plus the effective config defaults they fall back to (global → project → worktree merge for the channel’s dir), so a UI can label “default” concretely.

Response (200):

{
  "model": "claude-opus-4-8",
  "effort": "high",
  "default_model": "claude-sonnet-5-5",
  "default_effort": "",
  "models": ["claude-opus-5-5", "claude-opus-5-5[1m]", "claude-opus-5", "..."]
}

model / effort are empty when the channel inherits from config. models lists the model ids to offer — the same list as the claude_model config options; a [1m] id runs the model with its 1M-token context window.

Errors: 404 if the channel doesn’t exist. 501 if the store is not configured.

PATCH /api/channels/{id}/agent-config

Set the channel’s model/effort overrides. Empty strings clear an override (inherit from config). Takes effect on the channel’s next agent run — chat and scheduled runs alike — with no restart.

Request:

{"model": "claude-opus-4-8", "effort": "high"}

effort must be one of low, medium, high, xhigh, max, or empty. model is free text (any Claude model id).

Response: 204 No Content.

Behavior notes: Broadcasts a channel.agent_config event with the new overrides so the sidebar updates live.

Errors: 400 on invalid effort. 404 if the channel doesn’t exist. 501 if the store is not configured.

GET /api/channels/{id}/container-stats

Live CPU/memory usage for the channel’s running containers, digested from the Docker stats endpoint with the docker-cli formulas (CPU% from cpu/system deltas × online CPUs; memory usage minus reclaimable page cache). The desktop app polls this every ~3s to render the readout in the chat and docker-agent pane headers.

Response (200):

[
  {
    "container_id": "0a1b2c…",
    "type": "agent",
    "cpu_percent": 12.5,
    "mem_usage": 402653184,
    "mem_limit": 4294967296
  }
]

Behavior notes:

• Containers whose stats fetch fails (teardown race) are silently skipped.
• Returns [] when the channel has no running containers or the daemon lacks a stats source — never an error.
• The non-streaming Docker stats call takes ~1s server-side (the daemon primes the CPU delta), so responses are not instant.

GET /api/channels/{id}/audit

List the agent-gate audit files accumulated for a channel. The files are rotating JSONL (agentgate-YYYY-MM-DD.jsonl) written by FileAuditor inside the container and kept on the host under {policyDir}/<channel>/audit/. See Security Gate: Known gaps for the record schema and the verbose flag.

Path Parameters:

Query Parameters:

Response (200):

{
  "files": [
    {
      "date": "2026-04-24",
      "size": 12456,
      "last_modified": "2026-04-24T18:02:11Z"
    }
  ],
  "total": 1
}

Behavior notes:

• date is parsed out of the filename and validated against YYYY-MM-DD; anything else is skipped.
• Files are sorted newest-first by date for infinite-scroll pagination.
• When the audit directory does not yet exist (container never spawned or gate disabled), the endpoint returns {"files": []} with 200 rather than 404.

Errors: 501 if the audit-dir resolver is not configured.

DELETE /api/channels/{id}/audit/{date}

Remove one audit file from disk.

Path Parameters:

Response: 204 No Content on success.

Errors: 400 if date is not YYYY-MM-DD. 500 if the unlink fails. 501 if the audit-dir resolver is not configured.

GET /api/channels/{id}/messages

List messages for a channel. Supports two modes: cursor-based pagination (default) and around mode.

Path Parameters:

Query Parameters (cursor mode):

Query Parameters (around mode):

Response (200):

{
  "messages": [
    {
      "id": 42,
      "channel_id": "abc123",
      "msg_id": "discord_msg_id",
      "author_id": "user123",
      "author_name": "Alice",
      "content": "Hello!",
      "is_bot": false,
      "trigger_msg_id": "",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "next_cursor": 41
}

trigger_msg_id is the msg_id of the user message whose agent run produced this row. Empty (and omitted in JSON via omitempty) for user messages and pre-feature bot rows.

forkable is true on a message that records its place in the session’s transcript (an agent reply, a user message whose run has ended, or a message a fork or resume imported), so the conversation can be forked at it . It is omitted otherwise.

Behavior notes:

• Cursor mode: Fetches limit+1 messages to determine if more exist. If so, next_cursor is set to the last returned message’s ID. Messages are ordered oldest-first.
• Around mode: Uses a UNION ALL query (half before + half after the target message ID), ordered by id ASC. next_cursor is not set in around mode.
• This endpoint returns chat-only rows (kind = 'message'); agent thinking and tool events are not included. Use /api/channels/{id}/timeline for an interleaved view.

Errors: 400 if query params are invalid. 501 if message listing is not configured.

GET /api/channels/{id}/queued

Return the canonical queue of unprocessed user messages for a channel — every row with kind = 'message', is_bot = 0, is_processed = 0, ordered by priority DESC, id ASC (the exact order the orchestrator drains in). The chat UI calls this on channel mount and after every event that could change the queue (message.created, message.deleted, message.updated, messages.processed, agent.status) so the “queued”/“processing” labels and the queued-messages popup stay correct even when older pages of chat history are not loaded in the renderer.

Path Parameters:

Response (200):

{
  "messages": [
    {
      "id": 51,
      "channel_id": "abc123",
      "msg_id": "msg-bumped",
      "author_id": "user123",
      "author_name": "Alice",
      "content": "do this first instead",
      "is_bot": false,
      "is_processed": false,
      "priority": 1,
      "created_at": "2026-01-01T00:00:30Z"
    },
    {
      "id": 49,
      "channel_id": "abc123",
      "msg_id": "msg-older",
      "author_id": "user123",
      "author_name": "Alice",
      "content": "do this second",
      "is_bot": false,
      "is_processed": false,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

The in-flight message is included in the response, marked "is_running": true (omitted on the others). Clients use the agent.status event’s msg_id to distinguish “processing” from “queued”, and is_running until that event arrives. A scheduled task running in the thread claims no row, so every message sent meanwhile stays “queued” until it finishes. Higher priority values sort first; priority is omitted when zero. Rows queued with a delay carry not_before (unix seconds); the chat UI renders a live countdown chip until it elapses. not_before is omitted when zero (immediate). A row being edited in some window carries edit_hold_until (unix seconds) until the edit is saved, cancelled, or its lease lapses; it and everything behind it won’t start meanwhile (see POST /api/channels/{id}/queued/{msg_id}/hold ).

Errors: 501 if message listing is not configured. 500 on database error.

POST /api/channels/{id}/queued/{msg_id}/steer

Promote one queued message to the front of the channel’s queue and cancel the active run, so the agent takes that message next instead of when the current turn ends. This is the per-row form of POST /api/messages with interrupt=true, and makes the same trade: the cancelled run’s session is resumed on the next turn, so the work so far is redirected rather than discarded. Queued rows are preserved.

Path Parameters:

Request Body: none.

Response: 204 No Content.

Ordering matters and is handled server-side: the row is promoted before the run is cancelled, or the dying run’s drain loop could claim an older queued row in the window between the two. A row already claimed by a run (is_running = 1) is never promoted — the response is 404 and the active run is left alone. A row that was queued with a delay has its not_before pulled back to 1: already in the past, so ClaimNextPending accepts it, but still non-zero so the delay poller keeps seeing it and wakes an otherwise idle channel.

Errors: 404 if no matching queued row exists (already processed, already running, wrong channel, or never existed). 501 if the store is not configured. 500 on database error.

POST /api/channels/{id}/queued/{msg_id}/hold

Hold a queued user message so it can be edited: until the hold expires or is released, the drain won’t start it — nor anything queued behind it, so queue order is kept (see Edit holds ). Calling it again renews the hold; the chat app renews every 2 minutes while the edit is open.

Path Parameters:

Request Body: none.

Response (200):

{ "hold_until": 1790000000 }

hold_until is unix seconds, 5 minutes from now.

Errors: 409 if the row is no longer waiting — it already started, finished, was deleted, or never existed (bot rows and non-message rows never match). 501 if the store is not configured. 500 on database error.

DELETE /api/channels/{id}/queued/{msg_id}/hold

Release an edit hold without changing the message — the cancel path. When a hold was actually cleared, the channel’s drain is kicked so the row (and anything behind it) can start.

Response: 204 No Content, also when there was nothing to release.

Errors: 501 if the store is not configured. 500 on database error.

PUT /api/channels/{id}/queued/{msg_id}

Replace a queued user message’s content and clear its edit hold in one write, then kick the channel’s drain. Broadcasts message.updated so other windows show the new text.

Request Body:

{ "content": "the edited prompt" }

Response: 204 No Content.

The write only matches a row that is still waiting (is_running = 0 AND is_processed = 0), and it serializes with the orchestrator’s claim on SQLite’s single writer. If a run claimed the row first — typically after the hold lapsed — the response is 409 and the edit is not applied; the run uses the original text.

Errors: 400 on an invalid body or blank content. 409 if the row is no longer waiting. 501 if the store is not configured. 500 on database error.

POST /api/channels/{id}/monitors

Start a monitor: a watch script that runs in the background, so the agent’s run can end while it waits. This is what the monitor MCP tool calls. The script runs with /bin/sh -c in a fresh agent container for the channel, like a scheduled bash task, with the channel’s dir and mounts, and the request returns at once. When the script exits or times out, a message is queued in the channel, as queue_message would, which starts the agent’s next turn:

[monitor mon-1a2b3c4d] "PR 7 merged" exited with status 0. Output:

followed by the last 4000 bytes of the script’s output in a code block (or No output.). The status reads exited with status N, timed out after 1h0m0s, or the error that stopped the container.

Request Body:

{ "command": "until gh pr view 7 --json state -q .state | grep -q MERGED; do sleep 60; done", "description": "PR 7 merged", "timeout_sec": 3600, "interrupt": false }

Response (201): the monitor, shaped as in GET /api/channels/{id}/monitors .

Behavior notes: Broadcasts monitor.started now and monitor.finished when the script ends. Monitors live in the daemon’s memory: a cancelled one, and every one still running when the daemon stops, ends without a wake-up message. A container approval for the script’s container shows in the channel’s chat like any other.

Errors: 400 on an invalid body, a blank command or description, a negative timeout_sec, or a channel that doesn’t exist. 409 if the channel already runs 10 monitors. 503 while the daemon shuts down. 501 if monitors are not configured.

GET /api/channels/{id}/monitors

List the channel’s running monitors, oldest first.

Response (200):

{
  "monitors": [
    { "id": "mon-1a2b3c4d", "channel_id": "ch1", "description": "PR 7 merged", "command": "until …; do sleep 60; done", "started_at": "2026-01-02T03:04:05Z", "timeout_sec": 3600, "interrupt": false }
  ]
}

Errors: 501 if monitors are not configured.

DELETE /api/channels/{id}/monitors/{monitor_id}

Stop a monitor’s container without waking the agent. The chat’s monitor row has a Cancel button for this.

Response: 204 No Content.

Errors: 404 if the channel has no such running monitor. 501 if monitors are not configured.

GET /api/channels/{id}/live

Owner only. The channel’s live session , and whether its chat turns run live.

Response (200):

{ "running": true, "enabled": true, "channel_id": "ch1", "started_at": "2026-01-02T03:04:05Z", "session_id": "0a1b2c3d-…", "busy": false, "background": "1 background task: watch CI", "background_tasks": [{ "id": "b1x2", "type": "local_bash", "description": "watch CI", "started_at": "2026-01-02T03:04:06Z" }] }

Fields are as in the live.status event, plus enabled: whether the channel’s plain chat turns run live (live_sessions and live_session_platforms allow its platform, and it isn’t a hidden learn or explain thread). With no session running, it is {"running": false, "busy": false} plus enabled.

Errors: 501 if live sessions are not configured.

POST /api/channels/{id}/live

Owner only. Start the channel’s live session ahead of its next chat turn, as that turn would: resuming the channel’s session, or forking the parent’s for a thread’s first turn. The chat’s composer calls it when you start typing, so the container is up by the time the message is sent. It does nothing when a session already runs, a run or scheduled task holds the channel, or the channel’s turns don’t run live.

Response (200):

{ "started": true }

started is whether this call started the session; when it did, a live.status event follows.

Errors: 500 if the session failed to start. 503 if no live runner is set up. 501 if live sessions are not configured.

DELETE /api/channels/{id}/live

Owner only. Stop the channel’s live session, with reason stopped. Its Claude session stays: the next message starts a new live session on it.

Response: 204 No Content.

Errors: 404 if the channel has no live session. 501 if live sessions are not configured.

POST /api/channels/{id}/live/tasks/{task_id}/stop

Owner only. Stop one background task of the channel’s live session: a shell command, a Monitor, a subagent or a workflow, by the id its background_tasks carry. Claude stops it and reports the tasks left, which ends its pill above the composer. The session and its turn, if one runs, go on.

Response: 204 No Content.

Errors: 404 if the channel has no live session, or the session runs no background task with that id. 503 if no live runner is set up. 501 if live sessions are not configured.

POST /api/channels/{id}/side-chats

Owner only. Create a side chat of the channel or thread: an unlisted local thread with its own live session, for a Chat (Resume with fork) or Chat (Fresh session) pane. It is left out of the channel list, search and plugin events, and is deleted with its parent.

Request Body:

{ "mode": "fork" }

Response (201):

{ "channel_id": "side-1a2b3c4d5e6f" }

Errors: 400 on an invalid body or mode. 404 if the channel doesn’t exist. 409 if the channel is itself unlisted (a side chat, or a learn or explain thread), or in fork mode when it has no session yet. 501 if the store is not configured.

GET /api/channels/{id}/side-chats

Owner only. List the channel’s side chats, as channel rows ([] when there are none). The app uses it to delete side chats whose pane is gone.

Errors: 501 if the store is not configured.

DELETE /api/side-chats/{id}

Owner only. Stop a side chat’s live session (reason closed) and delete it like a thread, with its messages and containers. Its Claude session’s transcript stays.

Response: 204 No Content.

Errors: 404 if there’s no side chat with that id. 501 if the store or threads are not configured.

GET /api/channels/{id}/timeline

List the channel’s interleaved timeline — chat messages plus persisted agent events (thinking blocks, tool calls, tool results) — in canonical chain order. Each row carries a kind discriminator and a per-channel chain_position.

Path Parameters:

Query Parameters:

Response (200):

{
  "items": [
    {
      "kind": "message",
      "position": 12,
      "id": 101,
      "data": {
        "id": 101,
        "channel_id": "abc123",
        "msg_id": "user_msg_uuid",
        "author_id": "user123",
        "author_name": "Alice",
        "content": "Refactor the auth middleware",
        "is_bot": false,
        "is_processed": true,
        "created_at": "2026-04-30T08:00:00Z"
      }
    },
    {
      "kind": "thinking",
      "position": 13,
      "id": 102,
      "text": "Let me check how the existing tests cover this path...",
      "truncated": false,
      "trigger_msg_id": "user_msg_uuid"
    },
    {
      "kind": "tool_use",
      "position": 14,
      "id": 103,
      "tool_use_id": "toolu_017fNc...",
      "tool_name": "Read",
      "tool_input": "{\"file_path\":\"/work/internal/api/auth.go\"}",
      "trigger_msg_id": "user_msg_uuid"
    },
    {
      "kind": "tool_result",
      "position": 15,
      "id": 104,
      "tool_use_id": "toolu_017fNc...",
      "text": "package api\n\n// ...\n",
      "is_error": false,
      "truncated": true,
      "trigger_msg_id": "user_msg_uuid"
    }
  ],
  "next_cursor": { "position": 12, "id": 101 }
}

Behavior notes:

• Rows are ordered by (chain_position DESC, id DESC) so the response runs newest → oldest.
• The endpoint fetches limit + 1 rows to determine whether a next page exists. If so, next_cursor is set to the (chain_position, id) of the row past the cap.
• Legacy rows (chat from before this feature shipped) all carry chain_position = 0 and are ordered by id within that bucket. Cursor pagination handles the boundary between backfilled rows (chain_position > 0) and legacy rows transparently.
• Thinking, tool-use, and tool-result content are stored inline on the message row and truncated at 8 KiB when the docker stream writes them. The truncated flag tells the UI when a block was clipped.
• Live agent.thinking / tool.use / tool.result SSE events fire alongside row inserts, so the desktop app can render them in real time and refetch the head of the timeline on run completion.

Errors: 400 if cursor params are negative or non-numeric. 501 if the timeline service is not configured.

GET /api/messages/search

Full-text search across all messages using case-insensitive LIKE %query%. Messages in hidden learn and explain threads are left out.

Query Parameters:

Response (200):

[
  {
    "id": 42,
    "channel_id": "abc123",
    "author_name": "Alice",
    "content": "matching message",
    "is_bot": false,
    "created_at": "2026-01-01T00:00:00Z"
  }
]

Errors: 400 if q is empty. 501 if message search is not configured.

GET /api/channels/{id}/messages/search

Finds the channel’s messages whose content contains q, case-insensitively. % and _ in q match literally. Tool calls, tool results and thinking rows are not searched. Backs the chat’s find bar.

Query Parameters:

Response (200): the matching message ids, newest first.

{ "ids": [812, 640, 57] }

Errors: 400 if q is empty or limit is invalid. 501 if message search is not configured.

Learn

A channel’s learn switch, its hidden learn thread, and the proposals learn passes file. See Chat: Learn from a run . The channel endpoints below return 404 when {id} is itself a learn thread.

GET /api/channels/{id}/learn

Return the channel’s learn switch, the config default it falls back to (global → project → worktree merge for the channel’s dir), and its learn thread.

Response (200):

{
  "available": true,
  "learn": "on",
  "default_learn": false,
  "enabled": true,
  "learn_channel_id": "learn-a1b2c3d4e5f6",
  "running": false
}

Errors: 404 if the channel doesn’t exist or is a learn thread. 500 on a store error. 501 if the store is not configured.

PUT /api/channels/{id}/learn

Set the channel’s learn switch. It takes effect from the channel’s next run.

Request:

{"learn": "off"}

learn must be "on", "off", or empty to inherit the config.

Response: 204 No Content.

Behavior notes: Broadcasts a channel.learn event.

Errors: 400 if the body isn’t valid JSON, learn is another value, or the channel is a Slack or Discord one (learn runs only in desktop app channels) or a scheduled task’s thread (learn doesn't run in task threads). 404 if the channel doesn’t exist or is a learn thread. 501 if the store is not configured.

GET /api/channels/{id}/learn/proposals

List the proposals filed for the channel, newest first, in every status.

Response (200):

{
  "proposals": [
    {
      "id": 12,
      "channel_id": "abc123",
      "learn_channel_id": "learn-a1b2c3d4e5f6",
      "message_id": "loop-msg-17",
      "kind": "bash_shortcut",
      "title": "Add a make lint bash shortcut",
      "rationale": "make lint was typed three times in this run.",
      "payload": "{\"name\":\"lint\",\"description\":\"Run the linter\",\"command\":\"make lint\"}",
      "status": "pending",
      "created_at": "2026-03-25T14:30:00Z",
      "updated_at": "2026-03-25T14:30:00Z"
    }
  ]
}

proposals is [] when there are none.

Errors: 404 if the channel doesn’t exist or is a learn thread. 500 on a store error. 501 if the store is not configured.

POST /api/channels/{id}/learn/proposals

File a learn pass’s proposals and withdraw earlier ones it found stale. This is what the learn agent’s propose_learnings MCP tool calls. Here {id} is the learn thread; the proposals are stored for the channel it learns from, as pending.

Request:

{
  "proposals": [
    {
      "kind": "gate_rule",
      "title": "Ask before git push",
      "rationale": "The agent pushed without asking.",
      "payload": {"type": "command", "rule": {"commands": ["git"], "args_patterns": ["^push( .*)?$"], "decision": "approve", "message": "git push"}},
      "replaces": 9
    }
  ],
  "withdraw": [
    {"id": 7, "reason": "The run removed the lint target this shortcut calls."}
  ]
}

At least one of proposals and withdraw must be non-empty: a call may only withdraw. Only the channel’s own pending or failed proposals can be withdrawn, never one applying, applied, dismissed or already withdrawn. A withdrawn proposal keeps its row, with status: "withdrawn" and the reason in withdrawn_reason; a failed one’s error is cleared.

At most 5 proposals per call. Each needs a kind, a title (at most 200 characters) and a payload object; rationale is optional (at most 1000 characters). Title and rationale are trimmed. Payloads by kind (unknown fields are rejected):

The payload is stored in canonical JSON. New proposals get the message_id of the learn thread’s running pass, else its newest done one (a user’s reply in the learn thread files against the turn that pass reviewed); none when it has neither. The withdrawals and the inserts run in one transaction: either every proposal is valid and every withdrawal allowed, and all are stored, or nothing changes. A withdrawal takes the proposal the same way apply claims it (a conditional update on its status), so one the user is applying or dismissing at that moment can’t be withdrawn, and one withdrawn first can’t be applied.

Response (201): {"proposals": [...], "withdrawn": [...]}, the stored proposals and the withdrawn ones as in the GET above. proposals is [] for a withdraw-only call; withdrawn is omitted when none were.

Behavior notes: Broadcasts a learn.proposals event for the learning channel.

Errors: 400 if the body isn’t valid JSON, both proposals and withdraw are empty (proposals or withdraw is required), proposals has more than 5 items or withdraw more than 20, a proposal is invalid (the message names it, e.g. proposal 2: title is required), a withdrawal has no reason (withdraw 1: reason is required), or a proposal is withdrawn twice in the call (withdraw 2: proposal 7 is withdrawn twice, also when a replaces repeats one). 404 if {id} isn’t a learn thread. 409 if a proposal to withdraw isn’t the channel’s (proposal 7 not found in this channel) or isn’t open (proposal 7 is applied; only pending or failed proposals can be withdrawn). 500 on a store error. 501 if the store is not configured.

GET /api/channels/{id}/learn/passes

List the channel’s learn passes, newest first, in every status. Each reviews one turn, the one ending with bot message message_id.

Response (200):

{
  "passes": [
    {
      "id": 5,
      "channel_id": "abc123",
      "message_id": "loop-msg-17",
      "learn_channel_id": "learn-a1b2c3d4e5f6",
      "status": "done",
      "created_at": "2026-03-25T14:30:00Z",
      "updated_at": "2026-03-25T14:31:10Z",
      "message_row_id": 412
    }
  ]
}

passes is [] when there are none. A pass is recorded only when its turn has a bot reply. Passes left queued or running when Loop stopped are marked failed at the next start, unless their trigger still waits to run.

Behavior notes: Each status change is broadcast as a learn.pass event.

Errors: 404 if the channel doesn’t exist or is a learn thread. 500 on a store error. 501 if the store is not configured.

POST /api/channels/{id}/learn/passes

Start a learn pass over the turn that ended with bot message message_id, on demand. It runs whether or not the channel’s Learn switch is on, and whatever the turn’s length (learn.min_turns). A pass over the turn already queued or running is returned as it is; otherwise a new one is queued, also when the turn’s earlier pass is done or failed (or superseded, on an old row).

Request:

{"message_id": "loop-msg-17"}

Response (200): the pass, shaped as in the list (without message_row_id).

Behavior notes: A new pass creates the channel’s hidden learn thread on first use and is broadcast as a learn.pass event, as is each later status change. It forks the session where the turn ended, so it sees the turn as it was even when later ones followed (a turn from before Loop recorded where turns end forks the channel’s current session instead), and its trigger message quotes the turn’s prompt and final reply. Like an automatic pass, it queues behind the passes already in the learn thread and runs after them; nothing is replaced.

Errors: 400 if the body isn’t valid JSON, message_id is missing, the channel isn’t one learn passes run for (a Slack or Discord channel, or a task thread), or the message isn’t a bot message of a turn in the channel. 404 if the channel doesn’t exist, is hidden, or was deleted meanwhile. 409 if neither the turn nor the channel has a session to fork. 500 on a store error. 501 if on-demand learn passes are not configured.

POST /api/learn/proposals/{id}/apply

Apply a pending or failed proposal. It moves to applying first, so a double click can’t apply it twice. One left in applying for over a minute (its outcome was lost: the status save failed, or Loop stopped mid-apply) can be applied or dismissed again. See Configuration: Where learn proposals are written for what each kind changes.

Response (200): the proposal, with status applied, or failed and an error. A failed apply is recorded on the proposal, not returned as an HTTP error, so it can be retried.

Behavior notes: Broadcasts a learn.proposal_updated event. A rename, description or ticket URL also broadcasts channel.updated, a scheduled task task.created. Config-kind applies to the same .loop/config.json (e.g. several proposals applied at once) are serialized, from the duplicate check to the write, so none is lost or added twice.

Errors: 400 if {id} isn’t an integer. 404 if the proposal doesn’t exist. 409 if it’s already applied, dismissed or withdrawn (a learn pass may withdraw it while the request is in flight), or has been applying for under a minute (proposal is already applied). 500 on a store error. 501 if the store is not configured.

GET /api/learn/proposals/{id}/preview

What applying a proposal would change in the project config, without changing it. The server works out the same edit apply makes, with the same duplicate checks, against the file as it is now. Owner-only.

Response (200):

{
  "path": "/home/user/project/.loop/config.json",
  "diff": "--- /home/user/project/.loop/config.json\n+++ /home/user/project/.loop/config.json\n@@ -1,3 +1,6 @@\n {\n-  \"envs\": {}\n+  \"envs\": {},\n+  \"mounts\": [\n+    \"~/.aws:~/.aws:ro\"\n+  ]\n }\n"
}

All fields are omitted for kinds that edit no file (scheduled_task, rename, description, ticket_url).

Errors: 400 if {id} isn’t an integer. 404 if the proposal doesn’t exist. 500 on a store error. 501 if the store is not configured.

POST /api/learn/proposals/{id}/dismiss

Dismiss a pending or failed proposal, or one stuck in applying as above.

Response (200): the proposal, with status: "dismissed".

Behavior notes: Broadcasts a learn.proposal_updated event.

Errors: Same as apply.

Explain

A channel’s explain switch and the explanations of its turns. See Chat: Explain a turn . These endpoints return 404 when {id} is a hidden learn or explain thread, and 501 if the store is not configured.

GET /api/channels/{id}/explain

Return the channel’s explain switch and the config default it falls back to (global → project → worktree merge for the channel’s dir).

Response (200):

{"available": true, "explain": "", "default_explain": false, "enabled": false}

Errors: 404 if the channel doesn’t exist or is hidden. 500 on a store error.

PUT /api/channels/{id}/explain

Set the channel’s explain switch: with it on, every turn that completes is explained. It takes effect from the channel’s next run.

Request:

{"explain": "on"}

explain must be "on", "off", or empty to inherit the config.

Response: 204 No Content.

Behavior notes: Broadcasts a channel.explain event.

Errors: 400 if the body isn’t valid JSON, explain is another value, or the channel is never explained (explain runs only in desktop app channels, explain doesn't run in task threads). 404 if the channel doesn’t exist or is hidden. 500 on a store error.

GET /api/channels/{id}/explanations

List the channel’s explanations, newest first, in every status.

Response (200):

[
  {
    "id": 3,
    "channel_id": "abc123",
    "message_id": "loop-msg-17",
    "explain_channel_id": "explain-a1b2c3d4e5f6",
    "status": "done",
    "content": "### Summary\n\nAdded a lint target...",
    "created_at": "2026-03-25T14:30:00Z",
    "updated_at": "2026-03-25T14:31:10Z",
    "message_row_id": 412,
    "prompt": "add a lint target",
    "reply": "Added `make lint`..."
  }
]

The list is [] when there are none.

Errors: 404 if the channel doesn’t exist or is hidden. 500 on a store error.

POST /api/channels/{id}/explanations

Explain the turn that ended with bot message message_id. Without force, an existing explanation is returned as it is; with force (Re-explain) a done or failed one is queued again, replacing its content. An explanation already queued or running is returned as it is either way, unless it has been so for over an hour (its run was lost).

Request:

{"message_id": "loop-msg-17", "force": false}

Response (200): the explanation, shaped as in the list.

Behavior notes: A newly queued explanation creates the channel’s hidden explain thread on first use, queues a run there that forks the channel’s current session, and broadcasts an explain.updated event, as does each later status change.

Errors: 400 if the body isn’t valid JSON, message_id is missing, the channel is never explained, or the message isn’t a bot message of a turn in the channel. 404 if the channel doesn’t exist, is hidden, or was deleted meanwhile. 409 if the channel has no session to fork yet. 500 on a store error. 501 if explanations are not configured.

Tasks

POST /api/tasks

Create a new scheduled task.

Request:

{
  "channel_id": "abc123",
  "schedule": "0 9 * * *",
  "type": "cron",
  "prompt": "Summarize today's PRs",
  "template_name": "daily-summary",
  "auto_delete_sec": 3600,
  "worktree": true,
  "origin_branch": "main",
  "update_before_run": true
}

Response (201):

{"id": 1}

GET /api/tasks

List tasks for a channel.

Query Parameters:

Response (200):

[
  {
    "id": 1,
    "channel_id": "abc123",
    "schedule": "0 9 * * *",
    "type": "cron",
    "prompt": "Summarize today's PRs",
    "enabled": true,
    "next_run_at": "2026-01-02T09:00:00Z",
    "template_name": "daily-summary",
    "auto_delete_sec": 3600,
    "worktree": true,
    "origin_branch": "main",
    "update_before_run": true,
    "running": false,
    "thread_id": "thread_abc123",
    "workflow_name": "",
    "workflow_inputs": ""
  }
]

The running field indicates whether the task is currently being executed. It is set atomically when execution begins and cleared when it finishes. When workflow_name is set, the task triggers a workflow run instead of an agent prompt. plugin_id and plugin_action, omitted otherwise, are set on the task of a plugin action : it asks the plugin’s container in the channel to run the action. With worktrees=true or threads=true, a task of a listed thread carries the thread’s channel_name and dir_path, and channel_worktree: true when it is a worktree thread.

Errors: 400 if channel_id is missing.

GET /api/tasks/{id}

Get a single task by ID.

Path Parameters:

Response (200): Single task object (same schema as list items).

Errors: 400 if ID is invalid. 404 if task not found.

DELETE /api/tasks/{id}

Delete a scheduled task.

Response: 204 No Content

Errors: 400 if ID is invalid.

PATCH /api/tasks/{id}

Update one or more fields of a scheduled task. At least one field must be provided.

Request:

{
  "enabled": false,
  "schedule": "0 10 * * *",
  "type": "cron",
  "prompt": "Updated prompt",
  "auto_delete_sec": 7200,
  "worktree": true,
  "origin_branch": "develop",
  "update_before_run": true,
  "workflow_name": "validate",
  "workflow_inputs": "{}",
  "bash_script": "df -h | tail -1"
}

All fields are optional (use JSON null or omit). When enabled is provided, it is applied separately via SetTaskEnabled. Other fields are applied via EditTask. Set workflow_name to convert a prompt task into a workflow task, or bash_script to convert it into a bash task (clear either with an empty string to revert).

Response: 200 OK (empty body)

Errors: 400 if no fields provided or ID is invalid.

POST /api/tasks/{id}/run

Trigger an immediate execution of a task (“Run Now”). The task runs asynchronously in the background; the endpoint returns immediately.

Path Parameters:

Response: 202 Accepted (empty body)

Errors: 400 if ID is invalid. 404 if task not found. 409 Conflict if the task is already running.

POST /api/tasks/{id}/move

Move a task under another channel, thread or worktree thread of the same project, for example from a worktree thread to the root channel or back. The target must be under the same root channel as the task’s current owner, since its worktree, origin branch, templates and workflows belong to that project’s repo. Only the task’s owner changes: its schedule, prompt, worktree, origin_branch and other settings stay as they are. A thread deeper than one level resolves to its depth-1 parent, as on create.

On the local platform the task’s thread moves along with it. A thread with its own worktree (a worktree: true task) keeps its directory. A thread that shares its parent’s directory switches to the new parent’s, and its session transcript is copied there so the next run resumes it. Other platforms own their threads, so the task starts a fresh thread on its next run.

Path Parameters:

Request Body:

{"channel_id": "wt-thread-1"}

Response: 200 OK (empty body). Moving a task to the channel it’s already under is a no-op.

Errors: 400 if the ID or body is invalid, channel_id is missing, the target is the task’s own thread, or the target is in another project. 404 if the task, the target channel or the task’s current channel isn’t found. 409 Conflict if the task is running.

GET /api/tasks/{id}/runs

List recent run logs for a task (up to 50, newest first).

Path Parameters:

Response (200):

[
  {
    "id": 10,
    "task_id": 1,
    "status": "success",
    "response_text": "Completed successfully",
    "error_text": "",
    "started_at": "2026-01-02T09:00:00Z",
    "finished_at": "2026-01-02T09:01:30Z"
  }
]

The status field is one of "running", "success", or "failed".

Errors: 400 if ID is invalid.

Commands

POST /api/commands

Execute a slash command. The command is parsed and dispatched asynchronously through the interaction handler.

Request:

{
  "channel_id": "abc123",
  "author_id": "user123",
  "command": "schedule type=cron schedule='0 9 * * *' prompt='Daily standup'"
}

Supported commands:

Response: 204 No Content

Behavior notes:

• The command string supports quoted arguments (single or double quotes).
• Key-value pairs use key=value syntax.
• Unknown commands return 400 with "unknown command".

Errors: 400 if channel_id or command is empty, or command is unknown. 503 if commands not configured.

Extra Directories

Extra directories are configured in the project config (.loop/config.json) via the extra_dirs field. They are automatically loaded when listing roots or resolving file paths.

GET /api/channels/{id}/roots

List all root directories for a channel: the primary dir_path followed by any extra directories from the project config.

Path Parameters:

Response (200):

{
  "roots": [
    {"index": 0, "path": "/home/user/projects/my-project", "display_path": "~/projects/my-project", "name": "my-project"},
    {"index": 1, "path": "/home/user/projects/shared-lib", "display_path": "~/projects/shared-lib", "name": "shared-lib"},
    {"index": 2, "path": "/opt/proto", "display_path": "/opt/proto", "name": "proto"}
  ]
}

The first entry is always the primary dir_path. Subsequent entries are the extra directories in the order they were set. index is the value file endpoints take as root; display_path is path with the daemon user’s home dir shown as ~, which the root dropdowns show.

Errors: 404 if channel not found.

Files

All file endpoints resolve the channel’s dir_path from the database, falling back to ~/.loop/{channel_id}/work when the channel has no explicit path. When a channel has extra directories, file endpoints accept an optional root query parameter to select which root directory to operate on.

GET /api/channels/{id}/files

List directory contents for a channel’s working directory.

Query Parameters:

Response (200):

{
  "entries": [
    {"name": "src", "type": "dir"},
    {"name": "main.go", "type": "file", "size": 1234}
  ]
}

Behavior notes: Entries are sorted with directories first, then alphabetically by name (case-insensitive).

Errors: 400 if path validation fails (absolute path, .. traversal, symlink escape).

GET /api/channels/{id}/file

Read a file’s contents.

Query Parameters:

Response (200):

• Text files: Content-Type: text/plain; charset=utf-8 with file contents as body.
• Image files (.png, .jpg/.jpeg, .gif, .webp): Content-Type set to the matching image/* MIME with the raw bytes as the body. No X-File-Binary header — the desktop app uses this endpoint directly as <img src> so the browser handles caching and decoding.
• Video and PDF files (.mp4, .webm, .mov, .pdf): streamed from disk with Content-Type set to the matching video/* or application/pdf MIME and Accept-Ranges: bytes, so Range requests return 206 Partial Content. The desktop app plays videos with <video src> and renders PDFs with its pdf.js viewer.
• Other binary files: Empty body with X-File-Binary: true header and Content-Length set.

Behavior notes:

• The image, video and PDF branches are matched on extension and run before null-byte binary detection.
• Binary detection checks the first 512 bytes for null bytes.
• Maximum file size is 5 MB (5,242,880 bytes). Larger files return 413. Videos and PDFs are exempt: they’re streamed, never buffered whole.
• Path validation rejects absolute paths, .. traversal, and symlink escapes.
• With ref, the file only has to exist in that commit — it may since have been deleted — so only the lexical checks apply; the response is text or X-File-Binary, never the image/video/PDF branches. The path is resolved relative to the channel’s directory, as on disk.

Errors: 400 if path or ref is invalid. 404 if file not found (at ref, when given). 413 if file too large.

PUT /api/channels/{id}/file

Write content to a file.

Query Parameters:

Request body: Raw file content (not JSON). Maximum 5 MB.

Response (200):

{"ok": true}

Behavior notes:

• Preserves original file permissions if the file already exists; defaults to 0644 for new files.
• A symlink whose target resolves inside the root is followed: the write lands on the target and the link stays. A link that resolves outside the root, or points at nothing, is refused rather than written through.

Errors: 400 if path is invalid, a symlink leaves the root, or a symlink is dangling. 413 if content exceeds 5 MB.

DELETE /api/channels/{id}/file

Delete a file or directory.

Query Parameters:

Response (200):

{"ok": true}

Behavior notes: If the target is a directory, it is removed recursively (RemoveAll) with path traversal protection. If the target is a file, it is removed with Remove.

Errors: 400 if path is invalid. 404 if not found.

GET /api/channels/{id}/raw/{root}/{path...}

Serve a file’s raw bytes by path. The editor’s HTML preview uses this as the <base href> of the rendered page, so relative stylesheets, scripts and images resolve against the file’s directory. The root index is a path segment rather than a query parameter because relative URL resolution drops the query string.

Path Parameters:

Response (200): The file’s bytes with Content-Type from its extension (application/octet-stream when unknown). Range requests return 206 Partial Content.

Behavior notes:

• Responses carry X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox allow-scripts, so a page opened directly from this route runs in an opaque origin and can’t call the API with the app’s origin.
• Path validation matches the other file routes: absolute paths, .. traversal and symlink escapes are rejected.

Errors: 400 if the root index or path is invalid, or the path is a directory. 404 if file not found.

POST /api/channels/{id}/dir

Create a directory (including nested intermediate directories).

Query Parameters:

Response (200):

{"ok": true}

Behavior notes: Uses MkdirAll to create the directory and any missing intermediate parents. Path validation walks up to the first existing ancestor to verify the path stays under the root directory.

Errors: 400 if path is invalid.

POST /api/channels/{id}/files/exists

Batched existence check for path candidates discovered in chat text or tool input. Used by the desktop app’s clickable file-link UX (see Chat: File Links ).

Request body:

{"paths": ["app/src/main.tsx", "/Users/me/dev/loop/README.md", "missing/file.go"]}

Response (200):

{
  "results": [
    {"path": "app/src/main.tsx",                      "exists": true,  "root_index": 0, "rel_path": "app/src/main.tsx"},
    {"path": "/Users/me/dev/loop/README.md",          "exists": true,  "root_index": 0, "rel_path": "README.md"},
    {"path": "missing/file.go",                       "exists": false}
  ]
}

Behavior notes:

• Each candidate is resolved against the channel’s primary dir_path and any extra_dirs from project config, in order. The first root that contains the path wins; the root_index in the response refers to that root (compatible with the root query parameter on other file endpoints).
• Relative paths are tried under each root via the same path-validation rules as the read/write endpoints (no absolute, no .. traversal, symlink-aware containment check).
• Absolute paths are stat’d directly, then matched against each root’s resolved prefix to derive rel_path. Paths outside every root return exists: false.
• Directories return exists: false — only regular files are reported as existing, since the link UX opens files in the editor.
• The batch is capped at 200 paths per request; extras are silently dropped. Request body is limited to 64 KiB.

Errors: 400 if the request body is malformed or the channel’s directory cannot be resolved.

GET /api/channels/{id}/files/search

Fuzzy search for files across the channel’s primary dir_path and any extra_dirs. Used by the chat composer’s @ file picker.

Query Parameters:

Response (200):

{
  "results": [
    {"root_index": 0, "rel_path": "app/src/main.tsx",    "name": "main.tsx"},
    {"root_index": 0, "rel_path": "internal/api/server.go", "name": "server.go"}
  ]
}

Behavior notes:

• Walks all configured roots (primary dir_path first, then extra_dirs). root_index indicates which root the match came from (compatible with the root query parameter on file read/write endpoints).
• Always skips .git, node_modules, vendor, .next, dist, build, __pycache__ subtrees.
• Honors the top-level .gitignore in each root (basename and full-relpath patterns; negation patterns and nested .gitignore files are ignored).
• Walk stops once limit matches have accumulated across all roots.

Errors: 400 if the channel’s directory cannot be resolved.

POST /api/channels/{id}/paste-image

Persist an image pasted into the chat input. The desktop app calls this from ChatInput’s onPaste handler whenever the clipboard contains an image file (see Chat: Paste Images ).

Request body:

{
  "data": "<base64-encoded image bytes>",
  "media_type": "image/png"
}

Response (200):

{"path": "/Users/me/dev/project/.loop/pastes/paste-20260518-112528-66a7b575.png"}

The returned path is absolute, so the agent’s built-in Read tool (which requires absolute paths) can pick the file up directly. The renderer inserts the path at the caret position in the chat input.

Behavior notes:

• The file is written under <workspace>/.loop/pastes/; the directory is created with MkdirAll on first paste. .loop/ should be gitignored. Both are opened within the workspace: a .loop or pastes symlink leading out of it fails the paste with 500.
• Filename format: paste-<YYYYMMDD>-<HHMMSS>-<8-hex>.<ext> (UTC timestamp, 4-byte random suffix). Collisions within the same second are avoided by the random suffix.
• Extension is derived from media_type — .jpg for image/jpeg, .png/.gif/.webp otherwise.
• Request body is limited to 5 MB of raw image bytes after base64 decoding. Larger payloads return 413.

Errors: 400 for malformed JSON, missing data, unsupported media_type, or invalid base64. 404 if the channel does not exist. 413 if the image exceeds 5 MB. 501 if file operations are not configured. 500 if the filesystem write fails.

Path Validation

All file operations validate the relative path against the channel’s root directory:

1. Rejects absolute paths.
2. Rejects .. traversal components.
3. Resolves symlinks and verifies the real path stays under the root directory.
4. For writes to nonexistent files, validates the parent directory instead.
5. For directory creation, walks up to the first existing ancestor (allows creating nested directories).

Diff

GET /api/channels/{id}/diff

Get git diff information for a channel’s working directory. Includes both tracked changes and untracked files, and tags each entry with the bucket it came from (staged / unstaged / untracked / conflict).

Query Parameters:

Response (200) — uncommitted mode:

{
  "files": [
    {"path": "main.go",   "additions": 5, "deletions": 2, "binary": false, "status": "staged"},
    {"path": "main.go",   "additions": 1, "deletions": 0, "binary": false, "status": "unstaged"},
    {"path": "new.txt",   "additions": 4, "deletions": 0, "binary": false, "status": "untracked"},
    {"path": "image.png", "additions": 0, "deletions": 0, "binary": true,  "status": "untracked"}
  ],
  "diff": "diff --git a/main.go b/main.go\n...",
  "staged_diff": "diff --git a/main.go b/main.go\n...",
  "unstaged_diff": "diff --git a/main.go b/main.go\n...",
  "untracked_diff": "diff --git a/new.txt b/new.txt\n...",
  "conflict_diff": "",
  "total_additions": 10,
  "total_deletions": 2
}

File entry fields:

Behavior notes:

• Uncommitted mode (default): runs git diff --cached (staged), git diff (unstaged), and git ls-files --others --exclude-standard (untracked). Conflicts are surfaced via git diff --diff-filter=U.
• The frontend parses staged_diff / unstaged_diff / untracked_diff / conflict_diff independently so the per-bucket status tag survives partial staging (a path that appears in both staged and unstaged buckets would otherwise collide in a single parsed-by-path lookup).
• Branch-to-branch mode (?source=branchA&target=branchB): a single git diff is returned in diff; the per-status fields and the status tag on each file are omitted.
• Single-commit mode (?commit=<sha>): runs git show --diff-merges=first-parent, so a merge commit is diffed against its first parent and a root commit against the empty tree. The response has the branch-to-branch shape. Anything other than a hex hash returns 400; a hash that doesn’t resolve to a commit returns 404.
• Untracked files generate synthetic diff patches (all lines as additions). Binary detection checks the first 512 bytes for null bytes.
• If the directory is not a git repo, returns an empty files array.
• Files are sorted by (path, status priority) — conflict < staged < unstaged < untracked.
• The root parameter mirrors the same field on file endpoints: 0 (default) targets the channel’s primary dir_path; 1+ indexes into extra_dirs from the project’s .loop/config.json. Both uncommitted and branch-to-branch modes honor root.

Errors: 404 if channel not found. 400 if root is non-numeric, negative, or out of range.

Pull Request

GET /api/channels/{id}/pr

Look up the pull request whose head branch matches the channel’s current branch: a GitHub PR via gh, or a GitLab merge request via glab when the repo’s origin is a GitLab host. Shells out against the channel’s working directory.

Response (200, PR found):

{
  "present": true,
  "pr": {
    "number": 24,
    "url": "https://github.com/owner/repo/pull/24",
    "base_ref": "main",
    "head_ref": "feat/git-panel-pr-aware",
    "state": "OPEN",
    "title": "feat(git-panel): default diff base to PR target and live-update branch",
    "is_draft": false
  }
}

A GitLab merge request has "kind": "mr", its IID as number, and GitLab’s lowercase state (opened, merged, closed); kind is absent for a GitHub PR.

Response (200, no PR):

{"present": false}

Behavior notes:

• The lookup uses gh pr view --json number,url,baseRefName,headRefName,state,title,isDraft and falls back to a gh pr list query when pr view reports no match.
• The gh account is picked by the github.gh_user config key (mergeable per-project via .loop/config.json); empty falls back to whichever account gh currently has active.
• A repo without an origin remote looks nothing up. An origin on a GitLab host (its name contains gitlab, or the glab config lists it) runs glab mr list --source-branch <branch> --all, newest first; gitlab.glab_config_dir picks the config, so the account, it uses. Any other host goes to gh, GitHub Enterprise included.
• Environmental failures (gh or glab not installed, network) degrade to present: false rather than a 5xx so the UI hides the PR chip silently.
• A PR/MR found has the PR watcher poll the thread’s checks.

Errors: 404 if channel not found.

PR watching

Loop watches the checks of a thread’s PR/MR and sends failures on the agent’s own commits back to it (see pr.md ). These routes are owner-only: the agent scope leaves them out. All of them return 501 with PR watching not configured when the daemon runs without it.

GET /api/channels/{id}/pr/status

The status of the channel’s PR/MR, as the last channel.pr event reported it, or read from the forge when nothing has been reported yet.

Response (200):

{
  "present": true,
  "pr": {
    "channel_id": "thread-id",
    "kind": "mr",
    "number": 57,
    "url": "https://gitlab.example.com/example/group/project/-/merge_requests/57",
    "head_sha": "4f1c2d9e8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e",
    "base_ref": "main",
    "checks": {"total": 7, "passed": 5, "failed": 2, "pending": 0},
    "failed": [{"id": "981", "name": "lint", "group": "test", "url": "https://gitlab.example.com/example/group/project/-/jobs/981", "run_id": "981"}],
    "merge_state": "blocked",
    "auto_merge": false,
    "merge_methods": ["squash", "merge"],
    "merge_method": "squash",
    "pr_attention": "fixing",
    "auto_fix": true,
    "auto_fix_default": true,
    "attempts": 1,
    "max_attempts": 3,
    "reason": "fix_sent",
    "checkout_sha": "4f1c2d9e8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e",
    "unresolved_threads": 2
  }
}

{"present": false} when the branch has no PR/MR. The fields are those of the channel.pr event.

POST /api/channels/{id}/pr/fix

Sends the PR/MR’s current failure to the thread’s agent now, whoever made the commit and whatever the auto-fix guards say. Returns 204.

Errors: 404 when the branch has no PR/MR, 409 when no check failed (a merge conflict alone is never sent), 502 when the forge can’t be read.

POST /api/channels/{id}/pr/rerun

Re-runs the PR/MR’s failed checks on the forge now: each failed GitHub workflow run once (gh run rerun --failed), or each failed GitLab job. Returns 204.

Errors: 404 when the branch has no PR/MR, 409 when nothing failed, 502 when the forge can’t be read or refuses.

GET /api/channels/{id}/pr/log?check={id}

The tail of the log of a failed check, one of the failed the status last reported.

Response (200):

{"log": "--- FAIL: TestParse (0.00s)\n..."}

Errors: 404 when the branch has no PR/MR or check isn’t one of the failed checks, 502 when the forge can’t be read.

PUT /api/channels/{id}/pr/auto-fix

Overrides pr.auto_fix for the thread. Returns 204.

Request body:

{"auto_fix": false}

null drops the override, so the config’s setting applies again.

Errors: 400 for a malformed body, 502 when the setting can’t be saved.

POST /api/channels/{id}/pr/merge

Merges the thread’s PR/MR now, or arms “merge when ready”. Returns 204.

Request body:

{"when_ready": true, "method": "squash"}

Behavior notes:

• Armed, the merge goes through the forge’s own auto-merge when the repo allows it (gh pr merge --auto, or GitLab’s auto-merge). Otherwise Loop merges once the checks pass and the PR/MR can merge cleanly. Loop disarms its own merge when someone other than the agent pushes a new head.
• A method the repo doesn’t allow fails with 502.

Errors: 400 for a malformed body, 404 when the branch has no PR/MR, 502 when the forge refuses or can’t be read.

DELETE /api/channels/{id}/pr/merge

Cancels the “merge when ready” Loop armed, turning the forge’s auto-merge off when that’s what it armed. An auto-merge turned on outside Loop is left alone. Returns 204.

Errors: 404 when the branch has no PR/MR, 502 when the forge refuses.

Branches & Worktrees

GET /api/channels/{id}/branches

List local git branches and worktrees for a channel’s directory.

Query Parameters:

Response (200):

{
  "branches": ["main", "feature/foo"],
  "current": "main",
  "worktrees": [
    {"path": "/project/.worktrees/wt1", "branch": "feature/bar", "thread_id": "thread-id-if-imported"}
  ]
}

Behavior notes:

• Branches checked out in other worktrees are excluded from the branches list (git won’t allow switching to them).
• The main worktree is excluded from the worktrees list.
• thread_id is populated when the worktree has been imported as a thread (via POST /api/worktrees or POST /api/worktrees/import).
• The root parameter mirrors the same field on /api/channels/{id}/diff and /api/channels/{id}/commits: 0 (default) targets the channel’s primary dir_path; 1+ indexes into extra_dirs from the project’s .loop/config.json. Each extra root is treated as an independent repo.

Errors: 400 if root is non-numeric, negative, or out of range.

POST /api/channels/{id}/branches/switch

Switch the git branch in a channel’s working directory.

Request: {"branch": "feature/foo"}

Response (200): {"ok": true}

Errors: 400 if branch name is invalid or missing. 500 if git checkout fails (e.g. uncommitted changes).

POST /api/channels/{id}/branches/create

Create and checkout a new branch.

Request: {"name": "feature/new", "from": "main"} (from is optional)

Response (200): {"ok": true}

GET /api/channels/{id}/commits

List commit history for a channel’s git repository.

Query Parameters:

Response (200):

{
  "commits": [
    {
      "hash": "abc123def456...",
      "short": "abc123d",
      "subject": "feat: add new feature",
      "author": "John Doe",
      "date": "2026-03-30 14:22:01 +0000"
    }
  ]
}

Behavior notes:

• Commits are returned in reverse chronological order (newest first).
• On empty repositories (no commits yet), returns {"commits": []} instead of an error.
• Branch names are validated against a safe character set (alphanumeric, slashes, hyphens, dots, underscores).
• The skip parameter enables lazy pagination — the frontend loads pages of 50 commits and fetches more on scroll.
• The root parameter mirrors the same field on /api/channels/{id}/diff and other file endpoints: 0 (default) targets the channel’s primary dir_path; 1+ indexes into extra_dirs from the project’s .loop/config.json.

Errors: 400 if branch name is invalid, or if root is non-numeric / negative / out of range.

POST /api/worktrees

Create a git worktree as a new thread. The worktree gets its own branch (worktree/<name>) based on the selected branch, inherits the parent’s session for --fork-session, and appears in the sidebar as a thread.

Request:

{
  "channel_id": "parent-channel-id",
  "branch": "main",
  "name": "optional-name",
  "author_id": "optional-user-id",
  "message": "optional first prompt"
}

If message is provided, the bot posts it as a self-mention into the new thread to trigger a runner immediately with that prompt — same auto-trigger semantics as POST /api/threads.

Response (201):

{
  "thread_id": "new-thread-id",
  "worktree_path": "/project/.worktrees/wt-abc123"
}

Behavior notes:

• Creates git worktree add -b worktree/<name> <path> <branch> so any branch can be used as base, including the currently checked out one.
• Copies the parent’s Claude session file to the worktree’s project dir (~/.claude/projects/<encoded-path>/) so --resume --fork-session works on the first message.
• The thread’s DirPath points to the worktree directory; Worktree flag is set to true.
• Container mounts include the parent project directory so git worktree references resolve correctly.

POST /api/worktrees/import

Import an existing git worktree as a thread. Unlike POST /api/worktrees which creates a new worktree, this associates an already-existing worktree directory with a thread.

Request:

{
  "channel_id": "parent-channel-id",
  "worktree_path": "/project/.worktrees/existing-wt"
}

Response (201):

{
  "thread_id": "new-thread-id",
  "worktree_path": "/project/.worktrees/existing-wt"
}

Behavior notes:

• Validates that worktree_path is a real git worktree (checked against git worktree list --porcelain).
• Idempotent: if a thread already exists for the worktree path, returns it with 200 instead of creating a duplicate.
• Copies the parent’s Claude session file to the worktree’s project dir for --fork-session support.
• Thread name is derived from the worktree directory name and branch: <dirname> (<branch>).

DELETE /api/worktrees

Remove a git worktree from disk and optionally delete its associated thread.

Request Body:

Response: 204 No Content on success.

Behavior notes:

• Runs git worktree remove --force on the worktree path, then git worktree prune.
• If thread_id is provided, also deletes the thread record from the database and broadcasts a channel.deleted event. As with DELETE /api/threads/{id}, the thread’s hidden learn and explain threads go with it: their running pass or explanation is cancelled, the queued ones are dropped, and their forked session files are deleted.
• If the git worktree removal fails (e.g. path already gone), returns 500.

Errors: 400 if channel_id or worktree_path is missing, or if the channel is not found.

Quality

See Quality for the engine’s full architecture, metric definitions, and rule semantics.

POST /api/channels/{id}/quality/scan

Kick a quality scan for the channel. The request returns immediately; the full report ships over the WebSocket as a quality.scanned event.

Response (202 Accepted):

{ "status": "started" }

When a scan is already in flight for this channel, returns {"status": "in_progress"} without queueing or replacing — the engine coalesces concurrent triggers per channel.

Errors: 501 if the quality scanner is not configured.

GET /api/channels/{id}/quality/snapshot

Fetch the persisted quality snapshot. Returns the row for the channel’s current branch first; on miss falls back to the most recent snapshot on any branch with branch_mismatch: true so the panel can render a banner.

Response (200):

{
  "dir_path": "/work",
  "branch": "main",
  "current_branch": "main",
  "branch_mismatch": false,
  "signal": 6532,
  "geo_mean": 0.6532,
  "scanned_at": "2026-04-30T17:01:23Z",
  "metrics": [
    { "name": "modularity", "score": 0.71, "raw": 0.42 }
  ],
  "tiles": [
    { "path": "internal/foo/bar.go", "loc": 312, "deficit": 0.18, "metric_deficits": { "depth": 0.12 }, "top_reason": "depth" }
  ]
}