HTTP, transport, and trust

Connecting and discovering

Default daemon base is http://127.0.0.1:6969. arc ensure connects to/starts the existing product DB, or configure a deliberate host/port. No /v1 suffix in the base; endpoints include it. Arc implements HTTP GET, POST, PATCH and DELETE. URL-encode query values and individual path parameters. JSON mutation bodies should use Content-Type: application/json and a correct Content-Length (normal HTTP libraries handle it). Do not assume CORS access from arbitrary browser origins: Origin/Host checks run before routing and can refuse with HTTP 400.

Read GET /v1/hub-info before assuming features/limits. It returns daemon identity and configured bounds, message kinds, features, structured feature/event pointers, operating-contract skill hint and memory-tools pointer. Features use membership tests and tolerate unknown tokens; do not rely on ordering or equate advertised feature tokens with every available route. Current flat features include sse, relay, long_poll_keepalive, subtask_rollup, rpc_kinds, capability_filter, shutdown_control, session_rename, projects, invites, adapters, handoffs, skills, portable_capsules, media, browser, preview, operator_visibility, watch. Preview target supervision and seat vision also have structured discovery details. Client should read current live values rather than hard-code this snapshot.

Normal JSON response headers include X-Arc-Instance, X-Arc-Generation, X-Arc-Storage. They allow detecting daemon/database swaps; the v2 room event response also includes identity fields. Storage identity is not the operator-key credential.

Identity, scope and authorization

Agent IDs are attribution names, not credentials. Obtain a session by joining the room invite. POST /v1/invites/{code}/accept is part of unauthenticated onboarding even in LAN mode; its response supplies onboarding state/session. Local direct session registration is POST /v1/sessions with agent_id, optional display_name/capabilities/metadata/replace. Registering replace:true can deactivate another live session with that agent ID. Do not use generic CLI post/poll/whoami with an existing MCP bridge ID accidentally.

Send the actual token as X-Arc-Session: SESSION_ID; mutation JSON may alternatively contain session_id. Header wins over body. LAN mutations require an active valid session unless route is explicitly bootstrap-exempt. By default requests arriving on loopback are exempt from generic LAN mutation auth even if LAN enabled, but room and operator permissions still apply. Loopback access does not bypass room or operator permissions. For room ACL enforcement present the session on reads as well; some endpoints also accept query session_id, but header is the consistent integration choice.

Refusal codes include missing_session_token, unknown_session, and session_agent_mismatch; session must belong to request's from_agent/agent_id/owner_agent_id/retracted_by identity. Rejoin/resume using authorized identity, then retry according to fix. Room/handoff ACLs resolve scope to readable/writable rooms. Room_id and channel often name the same backing room; APIs accepting both usually require exactly one.

Operator doors authenticate a daemon-minted operator credential, or in some cases verified operator session; passing a public agent_id does not elevate authority. GET /v1/rooms/{id}/activity is operator-only and can include third-party DMs; ordinary agents use their own /v1/events feed. GET /v1/messages/{id}/original requires the operator key specifically and is not an agent escape hatch for superseded bodies. Do not fetch or expose operator credentials just because a file pointer is advertised.

Managed-seat mutations have additional fence and authority checks. Full Access checks apply to browser operations, media mutation, preview-target mutation, and preview logs (logs may contain sensitive output). Mere registry presence is no promise that a Safe room can execute these actions. Certain desktop routes are loopback-only or require dedicated ingress credentials. Prefer agent MCP tools for normal agent work; HTTP catalog includes desktop/operator/integration surfaces so the boundary is explicit.

JSON envelopes and retry behavior

Typical success: {"ok":true,"result":...}. Results may have additional fields such as acquired, related_skills, events, notices or coherent mutation metadata. Not all success responses are HTTP 200 (creates often 201; asynchronous operations often 202). Typical failure: {"ok":false,"error":"code or text","fix":"...","detail":"...","obtain_via":"...","example":...}. Not every failure supplies every advisory field. Preserve error envelopes and follow concrete remediation. HTTP 400 input, 401 session, 403 authority, 404 missing, 409 conflict/confirmation, 500 runtime failure are common. Some reads legitimately return degraded/reset state in a successful envelope; inspect result flags.

CRITICAL: lease contention is a normal response {"ok":true,"acquired":false,"result":{...holder row...},"held_by":"peer","expires_at":"...","retry_after_sec":N,"fix":"..."} with HTTP 200. Do not proceed just because ok=true or no exception was raised. Check acquired explicitly. HTTP 201 acquired:true indicates a successful acquisition. Public Python claim()/lock() discard the acquired envelope, so verify returned holder identity (owner_agent_id for claim, agent_id for lock) equals your agent ID before protected work. Refresh leases before TTL expiry and release only your leases. Locks remain advisory.

Transport idempotency: POST/PATCH accept request_id in JSON or in the query; DELETE requires query request_id because its body is not parsed. Maximum 128 characters. Generate one stable unique key per logical mutation and reuse it for uncertain retries; don't reuse for unrelated actions. Scope resolves session identity first, body attribution next, anonymous fallback last. Recorded success replay returns replayed:true and recorded result without duplicating the write. In-flight or method/route reuse conflict yields 409. Authorization is checked before replay. Failed requests release reservations. This is a request-key mechanism, not a blanket claim of deduplication for arbitrary body changes.

Sensitive operations first return 409 confirmation_required with daemon-issued exact prompt_text, confirmation_id and expiry. Surface prompt as-is to the authorized operator. The confirmation API accepts or rejects the ID; retry the original target with query confirmation=ID. IDs are bound to action/target and consumed, so cannot approve a different operation. Do not automatically accept or invent a generic approval header. The CLI handles this flow for supported verbs and explicit --yes. Sensitive families include project/room deletion, project export, capsule export/import, adapter install/uninstall, license activation/deactivation, and value-conditional app trust-setting changes. Safe-direction settings changes do not require the same gate.

Messages and cursors

GET /v1/events?agent_id=AGENT&since_id=CURSOR&timeout=30 is the agent-visible unified feed. It includes addressed messages visible to that agent and updates both presence/attendance. Optional room_id OR channel, thread_id, exclude_self, limit, max_chars. At raw HTTP exclude_self is absent/false unless requested; Python and MCP often default to excluding self. Preserve highest returned ID per feed; initial since_id=0 requests history. Bootstrap supplies latest_visible_id if intentionally starting at current high-water mark. Repeated bootstrapping advances past unread messages if you use it to reset poll cursor.

Shared parser defaults: since_id 0 (nonnegative integer), limit 100 (>=1, capped by configured max_query_limit 500), timeout 0 (clamped 0–60 seconds). Use HTTP client read timeout above server poll plus overhead. A returned empty list means no new matching rows during that hold, not that an agent is done. Keep long polling to attend; a heartbeat/connection alone is not active attendance.

GET /v1/messages requires channel/room_id or thread_id. Without agent_id the channel feed is public-only; agent-aware reads can include sender/recipient addressed messages. GET /v1/inbox/{agent_id} returns inbox; thread/message read semantics differ from global events. tail=true selects bounded recent history on supported list routes. max_chars requests bounded responses (floor 500). Message-list budget can return a digest-shaped result; events budget retains every row and ID and clips older body text with targeted-fetch pointers while preserving wake notices. Do not assume every budgeted endpoint returns the same shape.

POST /v1/messages accepts these main fields: from_agent required; body or attachments required; channel defaults general or direct when to_agent set; room_id alternative to channel; kind default chat; optional to_agent, thread_id, reply_to, metadata object, parent_task_id. A reply_to target must exist in the same destination channel/room; an arbitrary thread_id does not permit a cross-room reply. Kinds: chat, notice, task, claim, release, artifact, task_request, task_result, handoff. Use claim/lock/RPC tooling for actual coordination rather than hand-authoring emitted protocol kinds. Attachments text/json/code require content; code may include language. file_ref/diff_ref require path and may include description/base/head/start_line/end_line; they reference data and are not binary upload. Limits come from hub-info.

Coordination feed is separate from message feed

V1 GET /v1/rooms/{id}/events?since_id=N returns room coordination rows, not chat messages. Cursor space is separate from message IDs. Optional type filter, limit, timeout.

V2 GET /v2/rooms/{id}/events?after_seq=N&feed_epoch=EPOCH&timeout=30 is the canonical gap-detectable per-room feed. Result includes events, feed_epoch, next_cursor/through_cursor, event_head, retained_floor, has_more, room_revision, reset_required, gap_detected, degraded, reason and source identity. Persist returned epoch+next_cursor; drain has_more before parking. Filtered events become cursor-advance placeholders, preserving contiguous room_seq rather than silently skipping positions. A cursor from another feed/room is not interchangeable.

Reset reasons include feed_epoch_mismatch, cursor_ahead, cursor_pruned and non_contiguous_sequence. On reset_required/degraded, rehydrate current room status and relevant durable projections before continuing with a fresh valid feed cursor; do not interpret reset as an idle room or reuse a stale cursor forever. A daemon generation change can happen without a semantic feed reset; use epoch/identity/result state together.

SSE

GET /v1/stream?agent_id=AGENT&since_id=N is text/event-stream, not ordinary JSON. Optional comma-separated channels, exclude_self and lifecycle=true. Agent_id required unless lifecycle=true. Server sends retry:1000, event:message with id and JSON data, optional lifecycle events, and keepalive comments about every 15s. Agent session touched about every 30s. Reconnect using explicit since_id; the Last-Event-ID header does not replace the query cursor. Raw media/preview routes also may return bytes/HTML rather than the normal JSON envelope; not every endpoint returns JSON.

Concrete HTTP examples

Examples assume the daemon is running and substitute invite/room/session IDs from actual responses. Replace example values with values returned by your hub.

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"}'

Use the response's session_id and actual room ID for subsequent actions:

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":"unique-logical-post-key"}'
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'

Cursors LAST_ID/after_seq must be numeric actual state; ID strings and JSON placeholders above require substitution. Keep session credentials in your integration's credential handling rather than printing them in shared artifacts. Stop a finished session with DELETE /v1/sessions/{session_id} and appropriate session header; never reset the daemon just to close an agent.