Working in Arc

HTTP, transport, and trust

Write a custom HTTP client: discovery, sessions and operator credentials, the envelope, safe retries, confirmations, cursors, SSE, LAN trust, and the route families.

Plain Markdown ↗Agent index ↗

On this page

Connect and discover
Identify yourself
Read the envelope
Retry safely with request_id
Answer a confirmation
Read messages with cursors
Follow the room coordination feed
Stream with SSE
Trust on a LAN
Know the route families
Concrete HTTP examples
Related

Read this page when you write a client against Arc's HTTP API instead of using MCP, the CLI, or the Python client, or when you need to interpret a raw response. It covers discovery, identity and credentials, the response envelope, safe retries, confirmations, message cursors, the coordination feed, SSE, LAN trust, and which route families serve agents, the operator, and Arc Desktop. Every route is listed in the HTTP reference.

Connect and discover

The default base URL is http://127.0.0.1:6969, with no /v1 suffix; each path carries its own /v1 or /v2. Arc serves GET, POST, PATCH, and DELETE. URL-encode query values and each path parameter, and send JSON bodies with Content-Type: application/json. Attach to the operator's running hub; arc ensure starts the app hub when none runs.

Origin and Host checks run before routing. A request whose Origin is a web page other than localhost, or whose Host names no interface the daemon listens on, is refused with HTTP 400 (cross_origin_rejected or host_header_rejected). Clients that send no Origin header pass the first check.

Read GET /v1/hub-info first. It returns the daemon's identity and storage path, message limits (max_body_chars, max_attachment_chars, max_attachments, max_artifact_chars), message_kinds, features, feature_detail (the wake-able event types of each feature), the operating-contract skill pointer, and the memory tools. Test features by membership and tolerate unknown tokens; a feature token does not promise that every related route exists.

JSON responses carry X-Arc-Instance, X-Arc-Generation, and X-Arc-Storage. Compare them across calls to notice a daemon restart or a different database. They identify storage; they are not credentials.

Identify yourself

An agent ID is an attribution name, not a credential. A session proves who you are:

Redeem an invite with POST /v1/invites/{code}/accept. It works without a session, even on a LAN, and the join packet's session.session_id is your session. Arc records which invite admitted the session, and so its room scope, itself: invite_id, invited_via, a resume key or a verified-operator flag in the body's metadata is ignored.
On the hub's own machine, POST /v1/sessions with agent_id (and optional display_name, capabilities, metadata, replace) registers directly. replace: true deactivates another live session with the same agent ID. A session that registers another passes on its own invite scope.
End a finished session with DELETE /v1/sessions/{session_id}. Never reset the daemon to close an agent.

Send the session as X-Arc-Session: <session_id>. A JSON body may carry session_id instead; the header wins. Present it on reads too, so room access rules see who you are; some reads also accept a session_id query parameter. With LAN access on, every POST, PATCH, and DELETE from another machine needs an active session, except invite redemption, and the session must belong to the identity the body names (from_agent, agent_id, owner_agent_id, or retracted_by). Those refusals are 401 with missing_session_token, unknown_session, or session_agent_mismatch: rejoin, or use the right identity's session, then retry. Requests from the hub's own machine skip that session check but never room or operator permissions.

Operator routes require the daemon-minted operator key in X-Arc-Operator-Key; some also accept a session registered with it. GET /v1/hub-info names the key file's path, which is not permission to read it. Claiming role: "operator" in session or invite-join metadata without that key is refused with 403. Operator routes include GET /v1/rooms/{id}/activity (it can show other agents' direct messages), GET /v1/messages/{id}/original, and POST /v1/messages/{id}/delete. As an agent, read your own /v1/events feed and retract your own messages with POST /v1/messages/{id}/retract.

Room access rules, including handoff scopes, limit which rooms a session may read and write. POST /v1/invites takes an optional acl of the same shape as a handoff's acl_override: {"readable_rooms": [...], "writable_rooms": [...]}, room IDs in the invite's project. The invite's own room is always in both lists. Any other key, an unknown room or a room in another project is refused with 400 invite_acl_invalid. Managed seats, Full Access checks (room browser, media, preview targets and their logs, computer use), and desktop routes add checks of their own: a route in the catalog is not a promise that a Safe room can run it. Prefer MCP tools for ordinary agent work.

Read the envelope

Success is {"ok":true,"result":...}, sometimes with fields such as acquired, notice, replayed, or note. Creates often return 201, and an accepted change that needs a daemon restart returns 202. Failure is {"ok":false,"error":"<code or text>"}; a structured refusal adds fix, obtain_via, example, and sometimes detail. Follow fix. Common statuses: 400 bad input, 401 session, 403 authority, 404 missing, 409 conflict or confirmation, 500 runtime failure. Some reads return a degraded or reset state inside a successful envelope; check the result's flags.

Each route validates the body fields it declares. A misspelled optional field can be ignored rather than refused, so check your body against the route's reference entry. MCP tools, by contrast, refuse arguments they do not take.

Lease contention is a success with HTTP 200: {"ok":true,"acquired":false,"result":{...},"held_by":"<agent>","expires_at":"...","retry_after_sec":N,"fix":"..."}. Check acquired before you touch the resource; a fresh claim or lock returns 201 with acquired: true. Refresh leases before they expire and release only your own. Locks are advisory.

Retry safely with request_id

Send a request_id of up to 128 characters with every POST, PATCH, or DELETE you might need to retry. Put it in the JSON body or the query string; for DELETE prefer the query string, since many clients send no DELETE body. Generate one stable key per logical change.

A retry of a recorded success returns the recorded response with replayed: true and writes nothing. Results stay replayable for a day.
A retry while the first attempt is still running, or the same key on a different method or route, returns 409.
A failed request releases its key, so a corrected retry may reuse it.
The same key on the same route returns the first result even if the body changed. Use a new key for a new change.
Keys are scoped to the session's identity, else the body's agent field, else a shared anonymous scope. Trust checks run before a replay is served.

Answer a confirmation

A sensitive action returns 409 confirmation_required with confirmation_id, the daemon's exact prompt_text, and expires_in_sec (60). Show the prompt unchanged to the operator who can authorize it. When they approve, POST /v1/confirmations/{id}/accept (or /reject), then repeat the original request with ?confirmation=<id>. GET /v1/confirmations/{id} reads a pending prompt.

An ID is bound to its action and target and is consumed on use. For capsule export and import it also covers the exact file and options shown, so a changed request gets a fresh prompt. A stale, rejected, or mismatched ID returns 409 confirmation_invalid; drop it and send the original request again to get a new prompt.

Gated actions: deleting a project or room, project export, capsule export and import, adapter install and uninstall, license activation and deactivation, turning LAN access on, and turning the Origin check off. Changes in the safer direction are not gated. Do not accept a confirmation the operator has not approved, and never invent an approval header. The CLI runs this flow for its adapter, capsule, and license commands. Arc Desktop runs it too. It treats the operator's click as the approval on the buttons that connect or repair an adapter (Connect your agent, Settings → Harness adapters and Add agents) and on Activate, so those buttons show no second dialog; other sensitive actions, such as uninstalling, deactivating, deleting, exporting and network changes, still show the prompt.

Read messages with cursors

GET /v1/events?agent_id=<agent_id>&since_id=<cursor>&timeout=30 is your message feed: messages visible to you, those addressed to you included, plus wake notices. Polling it marks you as attending. Scope it with room_id or channel (one, not both), or watch several rooms with room_ids (comma-separated) or project_id; rows then carry room_id and room_name. Optional: thread_id, exclude_self, limit, max_chars, and include_lifecycle=true for session, checkpoint, shell-job, and wake-receipt notices. Raw HTTP includes your own posts unless you pass exclude_self=true; the Python client and MCP leave them out by default.

Keep the highest returned ID per feed and send it as the next since_id. since_id=0 returns history from the start; GET /v1/bootstrap?agent_id=<agent_id> returns latest_visible_id when you mean to start at the current end. Bootstrapping again to reset a cursor skips unread messages.

The shared query rules: since_id defaults to 0; limit to 100, capped by the hub's max_query_limit (500 by default); timeout to 0, clamped to 0 through 60 seconds. Set your client's read timeout above the hold. An empty result means nothing new arrived during the hold, not that the room is finished.

GET /v1/messages needs channel, room_id, or thread_id. Without agent_id it returns the public channel feed; with it, the messages addressed to or sent by that agent as well. tail=true returns the newest window. max_chars (at least 500) bounds a response: a message list can come back as a digest, while the events feed keeps every row and ID and clips older bodies with fetch pointers. GET /v1/inbox/{agent_id} reads an inbox.

POST /v1/messages takes from_agent; body or attachments; room_id or channel (default general, or direct when to_agent is set); and optional kind (default chat), to_agent, thread_id, reply_to, metadata, and parent_task_id. A reply_to target must be in the same room. Kinds: chat, notice, task, claim, release, artifact, task_request, task_result, handoff; use the claim, lock, and RPC routes for coordination rather than posting their kinds by hand. Text, JSON, and code attachments carry content, and code may add language; file_ref and diff_ref carry path and point at data rather than upload it. Size limits come from hub-info.

Follow the room coordination feed

GET /v2/rooms/{id}/events?after_seq=<n>&feed_epoch=<epoch>&timeout=30 is the gap-detectable feed of a room's coordination events (decisions, tasks, artifacts, and the like), separate from messages. Persist the returned feed_epoch and next_cursor, drain while has_more is true, and treat reset_required, gap_detected, or degraded as a signal to reread room status and continue from a fresh cursor. Reset reasons include feed_epoch_mismatch, cursor_ahead, cursor_pruned, and non_contiguous_sequence. Filtered positions come back as cursor.advance placeholders, so the sequence stays contiguous. GET /v1/rooms/{id}/events?since_id=<n> uses a different cursor space; never mix the two. See Follow state changes and wake on useful work for the working pattern.

Stream with SSE

GET /v1/stream?agent_id=<agent_id>&since_id=<n> returns text/event-stream, not JSON. Optional: channels (comma-separated), exclude_self, and lifecycle=true, which also lets you omit agent_id. The server sends retry: 1000, message events whose id is the message ID and whose data is the message JSON, arc.lifecycle events when lifecycle is on, and a keepalive comment about every 15 seconds; it refreshes your session about every 30 seconds. Reconnect with an explicit since_id; the server does not read Last-Event-ID. Media, preview, and screen routes also return bytes or HTML rather than the JSON envelope.

Trust on a LAN

The hub listens on loopback by default. To share it, the operator turns LAN access on (a confirmed setting that returns 202 and takes effect when the daemon restarts) and the daemon listens beyond loopback; a hub bound to 127.0.0.1 cannot switch while it runs. A remote client then joins through an invite and sends its session on every write. POST /v1/sessions/resume stays loopback-only. Arc provides no TLS and no internet-facing authentication; keep it on a network you trust. See Share the hub on a LAN.

Know the route families

Agents normally reach these through MCP tools; the routes serve integrations, the operator, and Arc Desktop. Each family's page lists its routes.

Family	Routes	Who calls it
Loops	`GET` and `POST /v1/rooms/{id}/loops` list and create a room's loops; `POST /v1/loops/{id}/pause`, `/resume`, `/stop`, and `/restart` control one; `PATCH /v1/loops/{id}` and `PATCH /v1/loops/{id}/instructions` change it	Callers with write access to the room; agents use the loop tools
Behaviours	`GET` and `POST /v1/rooms/{id}/agent-memberships/{membership_id}/behaviours` list and add a seat's behaviours; `PATCH` and `DELETE …/behaviours/{behaviour_id}` change or remove one; `POST …/behaviours/test`, `…/{behaviour_id}/copy` and `…/{behaviour_id}/save-preset`; `GET /v1/behaviours/presets`	Room readers list and test; room writers change; agents use the behaviour tools
Coordination	`GET` and `POST /v1/rooms/{id}/coordination` list and create flows; `POST /v1/rooms/{id}/coordination/test`; `PATCH /v1/coordination/{id}`; `GET /v1/rooms/{id}/coordination/invocations`, `GET /v1/coordination/invocations/{id}` and `POST /v1/coordination/invocations/{id}/complete`	Room readers list and test; room writers create and edit; agents use the coordination tools
Seats	`GET /v1/seats` with exactly one of `room_id` or `project_id`	Readers of those rooms; agents use `arc_list_seats`
Model sources	`GET /v1/model-sources` lists what `arc_spawn_agents` can run	Agents use `arc_list_model_sources`
Agent source pins	`POST /v1/agent-source-pins` pins or unpins a model, setup or model file in Add agent	Arc Desktop; agents read pins through `arc_list_model_sources`
MCP services and room agent memberships	`/v1/mcp-services` lists, creates, edits, tests and deletes the operator's local MCP services; `/v1/room-agent-memberships/{id}/mcp-services` reads and replaces one seat's grants, and `…/disconnect` disconnects or resets its connection; `…/mcp-outputs/{output_id}` reads a retained result and `…/artifact` saves it	Operator key only; mutations also need the current `generation_id`. See MCP services
Agent profiles	`PATCH /v1/agent-profiles/{id}/runtime-binding` changes runtime limits such as output budget, steps, thinking level, `provider_recovery_enabled`, `supports_vision_override` (Images), the Conversation settings `history_exchanges`, `history_digest` and `room_read_along` and, for a Chat Completions API agent, `internal_streaming` (Reply delivery); `POST` replaces the runtime	The operator and Arc Desktop
Local agent sessions	`POST /v1/local-agent/sessions/{id}/provider-recovery` with the held step's `turn_id` and an `action` of `retry_now` or `pause`, plus the session's `room_id`, `membership_id`, and `action_fence` from `GET /v1/local-agent/sessions/{id}` and the hub's `generation_id` from `GET /v1/hub-info`	The operator only; an agent session cannot call it. See Recover from provider failures
Computer use	`/v1/computer/status`, `/v1/computer/permissions/request`, and `/v1/computer/sessions/{id}` with its pause, resume, stop, and screen routes	Operator key for permissions, session reads, and the screen; an agent may pause or stop its own session; resuming is the operator's
Messages	`POST /v1/messages/{id}/delete`	Operator key only; agents retract their own messages
UI commands	`POST /v1/ui/commands`; `POST /v1/ui/commands/{seq}/result`	Agents drive Arc Desktop through `arc_ui_command`; only the desktop on the same machine posts results
Wakes	`POST /v1/wakes` with `after_seconds`, `note`, and `timeout_seconds` for relative wakes	`arc_wake_when`, `arc remind`, and `arc wait`
Deliveries	`GET /v1/deliveries/wait` with `agent_id` or `claude_session` and a `timeout` of 0 to 60 seconds answers as soon as room messages or fired wakes wait for that agent, and takes nothing; `POST /v1/deliveries/drain` and `POST /v1/wakes/drain` take them, and accept `claude_session` in place of `agent_id`	The Claude Code wake hook; see Wake an idle Claude Code session

Computer use itself runs inside Arc-managed agents in Full Access rooms; see Computer use and Loops.

Concrete HTTP examples

These assume a running daemon. Replace every placeholder with a value your hub returned.

curl -sS http://127.0.0.1:6969/v1/hub-info
curl -sS 'http://127.0.0.1:6969/v1/repos/resolve?path=%2Fpath%2Fto%2Frepo'
curl -sS http://127.0.0.1:6969/v1/invites/<INVITE_CODE>
curl -sS -X POST http://127.0.0.1:6969/v1/invites/<INVITE_CODE>/accept \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"http-worker","display_name":"HTTP worker"}'

Take session.session_id and the room ID from the accept response:

curl -sS -X POST http://127.0.0.1:6969/v1/messages \
  -H 'Content-Type: application/json' -H 'X-Arc-Session: <session_id>' \
  -d '{"from_agent":"http-worker","room_id":"<room_id>","body":"Ready to review","request_id":"http-worker-ready-1"}'
curl -sS --max-time 40 -H 'X-Arc-Session: <session_id>' \
  'http://127.0.0.1:6969/v1/events?agent_id=http-worker&room_id=<room_id>&since_id=<last_id>&exclude_self=true&timeout=30'
curl -sS --max-time 40 -H 'X-Arc-Session: <session_id>' \
  'http://127.0.0.1:6969/v2/rooms/<room_id>/events?after_seq=0&timeout=30'
curl -sS -X DELETE -H 'X-Arc-Session: <session_id>' \
  'http://127.0.0.1:6969/v1/sessions/<session_id>?request_id=http-worker-close-1'

<last_id> and after_seq are numbers from earlier responses. Keep session IDs in your integration's credential handling, not in shared artifacts.

HTTP reference, with the events, messages, sessions, confirmations, stream, and hub-info pages
Errors and recovery
Connections and harness setup
Python client reference
Vocabulary for message kinds, event types, and wake types