REST API
The broker exposes a single HTTP API consumed by both the SDK
client (machine plane, bearer auth) and the web UI (human plane,
session cookie). All paths and types are defined by
@agentc7/sdk — @agentc7/sdk/protocol for path constants,
@agentc7/sdk/schemas for zod request / response shapes.
Every request carries X-AC7-Protocol: 1 and is validated
against the schema. Schema mismatches return 400 with a JSON
error body.
Auth
Three planes, all resolving to the same loaded member:
| Plane | Header | Source |
|---|---|---|
| Bearer | Authorization: Bearer ac7_<base64url> | ~/.config/ac7/auth.json (CLI) or directly issued tokens |
| Session | Cookie: ac7_session=<id> | After successful TOTP login |
| JWT (federation, optional) | Authorization: Bearer <jwt> | A platform that’s been bound via the platform-connect flow |
In the tables below:
| Auth label | Means |
|---|---|
| dual | Bearer OR session cookie |
| bearer | Bearer only |
| session | Session cookie only |
| manage | Requires members.manage permission |
| manage OR self | members.manage, OR caller.name === target.name |
| self | Caller must be the target member |
| read OR self | activity.read, OR caller is target |
| none | Unauthenticated (used for health, enrollment, lookups) |
Health
GET /healthz
| Auth | none |
| Body | — |
| Returns | 200 { status: "ok", version: <semver> } |
Liveness probe. Cheap; always responds 200 if the process is up.
Briefing
GET /briefing
| Auth | dual |
| Body | — |
| Returns | BriefingResponse |
The team-context packet. Returns the caller’s full member record (name, role, instructions, permissions) plus the team (name, directive, brief, permissionPresets), the public projection of every teammate, and the caller’s currently-open objectives.
The runner caches this at startup and uses it for the entire
session — name, role, and open objectives are baked into MCP
tool descriptions on every tools/list call.
Roster
GET /roster
| Auth | dual |
| Returns | { teammates: Teammate[], connected: Presence[] } |
Public projection of teammates plus a parallel list of live presence (connection count, last-seen, busy flag). For the presence model see presence.
Push / subscribe / history
POST /push
| Auth | dual |
| Body | PushPayload — { to?, title?, body, level?, data?, attachments? } |
| Returns | PushResult — { delivery: { live, targets }, message: Message } |
Send a message. to: <name> is a DM; to: null (or omitted)
plus data.thread = 'chan:<id>' is a channel post; otherwise
it’s a broadcast to general. The broker stamps from from the
authenticated member; payloads cannot override.
GET /subscribe?name=<self>
| Auth | dual |
| Returns | SSE stream of Message events |
Subscribe to messages addressed to self (the authenticated
caller’s name). The broker enforces name === caller.name.
Multiple concurrent subscribers per member are supported (the
Presence.connected count reflects that).
GET /history?with=<name>&channel=<id>&limit=<N>&before=<ts>
| Auth | dual |
| Returns | HistoryResponse — { messages: Message[] } |
Newest-first message history. Pass exactly one of with (DM
thread with the named teammate) or channel (channel id).
Omitting both returns general channel scrollback. limit defaults
to 50, max 500. before is an epoch-ms cursor for paging.
Sessions and TOTP
POST /session/totp
| Auth | none |
| Body | TotpLoginRequest — { code: "<6 digits>", member?: "<name>" } |
| Returns | 200 SessionResponse + Set-Cookie: ac7_session=<id> |
When member is set, the server verifies against just that
member. When omitted, the server iterates enrolled members
looking for a match (codeless login). Rate-limited: 5 failures /
15min per member, 10 failures / 15min global.
On success the session cookie is httpOnly, Secure over HTTPS,
SameSite=Strict, 7-day sliding TTL — every authenticated request
bumps last_seen and re-stamps the expiry.
GET /session
| Auth | dual |
| Returns | SessionResponse — { member, role, permissions, expiresAt } |
Current session info. Useful for the web UI to bootstrap.
POST /session/logout
| Auth | dual |
| Returns | 204 + cleared cookie |
Members
GET /members
| Auth | dual |
| Returns | ListMembersResponse — { members: Member[] } |
Admin sees the full list including private instructions. Other
callers see the public projection — same as roster.teammates.
POST /members
| Auth | manage |
| Body | CreateMemberRequest — { name, role, instructions?, permissions: string[] } |
| Returns | CreateMemberResponse — { member: Teammate, token: <plaintext> } |
The token plaintext is returned exactly once; only its SHA-256
hash is persisted. permissions accepts preset names or leaf
permissions in any mix; the server resolves at create time.
PATCH /members/:name
| Auth | manage |
| Body | UpdateMemberRequest — { role?, instructions?, permissions? } |
| Returns | Teammate |
Patches any subset of fields. Enforces “at least one
members.manage member must remain” — rejects with 400 if the
update would remove the only admin’s permission.
DELETE /members/:name
| Auth | manage |
| Returns | 204 |
Same admin-survival invariant as PATCH. Tokens for the deleted
member are invalidated.
POST /members/:name/rotate-token
| Auth | manage OR self |
| Returns | RotateTokenResponse — { token: <plaintext>, tokenInfo? } |
Revokes every active token for the member and mints a fresh one.
Plaintext returned once; metadata in tokenInfo lets the caller
display label / id without a follow-up list.
GET /members/:name/tokens
| Auth | manage OR self |
| Returns | ListTokensResponse — { tokens: TokenInfo[] } |
List active bearer tokens with metadata (label, origin, createdAt, lastUsedAt, expiresAt, createdBy). Plaintext is never exposed by this shape.
DELETE /members/:name/tokens/:id
| Auth | manage OR self |
| Returns | 204 |
Revoke a specific token by uuid. Revoking the token currently authenticating the request is allowed.
POST /members/:name/enroll-totp
| Auth | manage OR self |
| Returns | EnrollTotpResponse — { totpSecret, totpUri } |
Mints (or rotates) a TOTP secret. Re-enrolling invalidates any authenticator currently bound. Confirmation is enforced client-side (CLI / web UI prompts for the 6-digit code from the new authenticator before persisting).
POST /members/:name/activity
| Auth | self only |
| Body | UploadActivityRequest — { events: ActivityEvent[] } (1–500) |
| Returns | UploadActivityResponse — { accepted: <count> } |
Runner-side activity upload. The server stamps each event with a
row id and broadcasts to live /activity/stream subscribers.
GET /members/:name/activity?from=<ts>&to=<ts>&kind=<k|k[]>&limit=<n>
| Auth | read OR self |
| Returns | ListActivityResponse — { activity: ActivityRow[] } |
Range query. Returns newest-first up to 1000 rows. kind filter
accepts a single value or an array
(objective_open|objective_close|llm_exchange|opaque_http).
The TracePanel uses
from=<objective.createdAt>&to=<objective.completedAt>&kind=llm_exchange
to render per-objective traces.
GET /members/:name/activity/stream
| Auth | read OR self |
| Returns | SSE stream of ActivityRow events |
Live tail of the activity stream. Used by the TracePanel for in-flight objectives where new events keep arriving.
Objectives
GET /objectives?assignee=<name>&status=<s>
| Auth | dual |
| Returns | ListObjectivesResponse — { objectives: Objective[] } |
Per-member filter. The MCP objectives_list tool calls this with
assignee=<self> to populate the agent’s plate.
POST /objectives
| Auth | dual; requires objectives.create |
| Body | CreateObjectiveRequest — { title, outcome, assignee, body?, watchers?, attachments? } |
| Returns | Objective |
Creates the objective and appends an assigned audit event in
the same transaction. Originator is stamped from the caller. If
watchers are supplied, they’re de-duped and validated; each
must resolve to a known member. attachments validate that the
caller has read access to each path.
GET /objectives/:id
| Auth | dual |
| Returns | GetObjectiveResponse — { objective: Objective, events: ObjectiveEvent[] } |
Full state plus the append-only event log.
PATCH /objectives/:id
| Auth | dual; assignee OR members.manage |
| Body | UpdateObjectiveRequest — { status?: 'active'|'blocked', blockReason? } |
| Returns | Objective |
Round-trip transition. Use complete / cancel for terminal
states. blockReason is required when status: 'blocked'.
POST /objectives/:id/complete
| Auth | dual; assignee only |
| Body | CompleteObjectiveRequest — { result: <required string> } |
| Returns | Objective |
Terminal transition to done. The result string goes into the
audit log and is the “what was actually delivered” summary.
POST /objectives/:id/cancel
| Auth | dual; objectives.cancel OR originator |
| Body | CancelObjectiveRequest — { reason? } |
| Returns | Objective |
Terminal transition to cancelled.
POST /objectives/:id/reassign
| Auth | dual; members.manage |
| Body | ReassignObjectiveRequest — { to: <name>, note? } |
| Returns | Objective |
Moves to a new assignee. Both old and new assignees receive
channel events. Activity stream gets objective_close (with
result: 'reassigned') for old, objective_open for new.
POST /objectives/:id/discuss
| Auth | dual; thread member only |
| Body | DiscussObjectiveRequest — { body, title?, attachments? } |
| Returns | Message (the underlying push) |
Posts into the obj:<id> thread. Members include originator,
assignee, watchers, plus members with members.manage (implicit).
PATCH /objectives/:id/watchers
| Auth | dual; objectives.watch OR originator |
| Body | UpdateWatchersRequest — { add?: string[], remove?: string[] } (must include at least one) |
| Returns | Objective |
Names must resolve to known members. Adding a watcher fires a
watcher_added audit event; removing fires watcher_removed.
Channels
GET /channels
| Auth | dual |
| Returns | ListChannelsResponse — { channels: ChannelSummary[] } |
Per-viewer projection. joined reflects caller’s membership;
myRole is non-null when joined. general always appears with
joined: true, myRole: 'member'.
POST /channels
| Auth | dual |
| Body | CreateChannelRequest — { slug } |
| Returns | Channel |
Creator becomes channel admin. Slug grammar: 1–32 lowercase, letters / digits / dashes, must start + end alphanumeric, no consecutive dashes.
GET /channels/:slug
| Auth | dual |
| Returns | GetChannelResponse — { channel: ChannelSummary, members: ChannelMember[] } |
Detail + member list.
PATCH /channels/:slug
| Auth | dual; channel admin OR members.manage |
| Body | RenameChannelRequest — { slug } |
| Returns | Channel |
Rename. Existing message references (data.thread = 'chan:<id>')
remain valid — they reference id, not slug.
DELETE /channels/:slug
| Auth | dual; channel admin OR members.manage |
| Returns | 204 |
Soft-archive (sets archivedAt). History remains queryable;
posts return 410.
POST /channels/:slug/members
| Auth | dual; channel admin (others) OR self (own name) OR members.manage |
| Body | AddChannelMemberRequest — { member, role?: 'admin'|'member' } |
| Returns | 204 |
Self-join allowed when member === caller.name. Adding others
requires admin.
DELETE /channels/:slug/members/:name
| Auth | dual; channel admin (others) OR self OR members.manage |
| Returns | 204 |
Self-leave always allowed.
Filesystem
The ac7 virtual filesystem stores blob-deduped files under
per-member homes (/<name>/...). Paths are absolute Unix-style.
GET /fs/ls?path=<p>
| Auth | dual |
| Returns | FsListResponse — { entries: FsEntry[] } |
path=/ lists every visible home root. Other paths must sit under
a home you own or that’s been shared with you.
GET /fs/stat?path=<p>
| Auth | dual |
| Returns | FsEntryResponse |
GET /fs/read/<path>
| Auth | dual; readable by caller |
| Returns | 200 <bytes> with Content-Type: <mime> |
Friendly URL — segments are URL-encoded individually so the path
works directly in <a href> and <img src>. The server checks
read access (own home, director, or grant from a message
attachment).
POST /fs/write
| Auth | dual |
| Body | binary blob with metadata in query / headers |
| Returns | FsWriteResponse — { entry, renamed } |
Write a file. collision strategy: error (default), overwrite,
or suffix (auto-rename foo.txt → foo-1.txt). renamed
indicates suffix collision triggered.
POST /fs/mkdir
| Auth | dual |
| Body | FsMkdirRequest — { path, recursive? } |
| Returns | FsEntryResponse |
DELETE /fs/rm?path=<p>&recursive=<b>
| Auth | dual |
| Returns | 204 |
Cascades blob refcounts; underlying content is purged when the last referencing entry goes away.
POST /fs/mv
| Auth | dual |
| Body | FsMoveRequest — { from, to } |
| Returns | FsEntryResponse |
Rename / move a single file. Directory moves not supported in v1.
GET /fs/shared
| Auth | dual |
| Returns | FsListResponse |
Files shared with the caller via message / objective attachments. Owner-private files from other members never appear.
Presence
POST /presence/busy
| Auth | bearer |
| Body | BusyReport — { busy: boolean } |
| Returns | 204 |
Runner-only. Reports the agent’s busy state to the broker. The server applies a 30s TTL — if no heartbeat arrives within the window, busy auto-clears. The runner heartbeats every 15s while busy.
Web Push (browser notifications)
GET /push/vapid-public-key
| Auth | none |
| Returns | VapidPublicKeyResponse — { publicKey } |
The team’s VAPID public key, for the SPA’s push subscription flow.
POST /push/subscriptions
| Auth | dual |
| Body | PushSubscriptionPayload — { endpoint, keys: { p256dh, auth } } |
| Returns | PushSubscriptionResponse — { id, endpoint, createdAt } |
Register a browser push subscription for the authenticated member.
DELETE /push/subscriptions/:id
| Auth | dual |
| Returns | 204 |
Unregister.
Device-code enrollment
POST /enroll
| Auth | none |
| Body | DeviceAuthorizationRequest — { labelHint? } |
| Returns | DeviceAuthorizationResponse |
Mint a deviceCode + userCode pair. Rate-limited 10 / IP /
hour with 429 + Retry-After on overflow.
POST /enroll/poll
| Auth | none |
| Body | DeviceTokenRequest — { deviceCode } |
| Returns | 200 DeviceTokenResponse on success, or 400 DeviceTokenErrorResponse |
Error codes: authorization_pending, slow_down,
expired_token, access_denied. See
device enrollment.
GET /enroll/pending
| Auth | manage |
| Returns | ListPendingEnrollmentsResponse |
For the director’s UI — pending requests with source IP / UA / expiry.
POST /enroll/approve
| Auth | manage |
| Body | ApproveEnrollmentRequest — bind or create variant |
| Returns | ApproveEnrollmentResponse — { member, tokenInfo } |
The plaintext token is delivered to the device-side CLI on its next poll, NOT to the approver. Keeps the secret on the device.
POST /enroll/reject
| Auth | manage |
| Body | RejectEnrollmentRequest — { userCode, reason? } |
| Returns | 204 |
Sets the enrollment row to rejected; the device’s next poll
returns access_denied with the reason as errorDescription.
Platform connect (optional federation)
For the full flow see self-hosted-connect.
POST /platform-connect/bind
| Auth | session |
| Body | { pairingCode, platformUrl } |
| Returns | confirmation + the JWT config block |
Pair the broker with a hosted control plane. Writes a
<config>.platform.json overlay with jwt.{issuer, audience, jwksUrl}.
GET /platform-connect/lookup
| Auth | none |
| Returns | one-time platform info for the pairing code |
Used by the platform’s authorize-server page during pairing.
Error shapes
All non-2xx responses return JSON:
{ "error": "<short code>", "message": "<human description>" }Common error codes:
| Code | Meaning |
|---|---|
bad_request | Schema validation failed |
unauthenticated | No valid auth on the request |
forbidden | Auth resolved but lacks the required permission |
not_found | Resource doesn’t exist |
conflict | Slug / name collision, or invariant would be violated |
gone | Resource is archived (channel, completed objective with destructive intent) |
rate_limited | TOTP / enrollment rate limit hit; check Retry-After |
payload_too_large | Body exceeded the per-route cap |
Validation errors include a details field with the zod issue
list when applicable.
Source of truth
packages/sdk/src/protocol.ts—PATHS,OBJECTIVE_PATHS,CHANNEL_PATHS,MEMBER_PATHS,FS_PATHSpackages/sdk/src/schemas.ts— every request / response shapeapps/server/src/app.ts— endpoint dispatchapps/server/src/auth.ts— the auth middlewareapps/server/src/{members,objectives,channels,enrollments,sessions,...}.ts— per-route handlers