Agent Rooms HTTP API
@agentplat/rooms-api is a Hono transport adapter around injected Agent Room
services. It contains no database or server choice. Routes backed by optional
services exist only when that service is passed to createRoomsApp.
Authentication, tenancy and envelopes
GET /health is public. Every other route requires an authenticated
TenantContext. The default development authenticator reads
X-Agentplat-Tenant-Id; it is not suitable for an untrusted network. Production
deployments must inject an authenticator that verifies identity and returns a
tenant and, where applicable, an actor.
Tenant, Room and resource identifiers from the authenticated context and URL override reserved body fields. Authenticated actor identity overrides body participant IDs for approvals, interventions, Handoffs and contribution lifecycle actions.
Success responses use { "data": ... }. Errors use
{ "error": { "code", "message", "details"? } }. Adapter details are hidden
unless exposeErrorDetails is enabled for local debugging. Creation returns
201; accepted asynchronous work returns 202; reads and transitions return
200. Invalid JSON or input returns 400, missing authentication 401,
missing resources/routes 404, revision conflicts 409, and policy or
lifecycle rejection uses the mapped AgentPlat error status.
Core Room routes
| Method and path | Body/query | Result |
|---|---|---|
GET /health | — | { status: "ok" } |
POST /rooms | CreateRoomInput | Created Room |
GET /rooms | — | Tenant Rooms |
GET /rooms/:roomId | — | Complete Room aggregate projection |
PATCH /rooms/:roomId | UpdateRoomInput | Updated Room |
POST /rooms/:roomId/{pause,resume,complete,archive} | optional { actorId } | Transitioned Room |
POST /rooms/:roomId/participants | AddParticipantInput, optional actorId | Participant |
POST /rooms/:roomId/messages | SendMessageInput | Persisted message; may enqueue coordination transactionally |
POST /rooms/:roomId/tasks | CreateTaskInput, optional actorId | Task |
POST /rooms/:roomId/tasks/:taskId/run | — | Created run |
POST /rooms/:roomId/artifacts | CreateArtifactInput | Artifact |
POST /rooms/:roomId/artifacts/:artifactId/versions | CreateArtifactVersionInput | Append-only version |
POST /rooms/:roomId/approvals | RequestApprovalInput | Approval request |
POST /approvals/:approvalId/{approve,reject,request-revision} | ResolveApprovalInput | Resolved approval |
GET /rooms/:roomId/events | optional cursor, limit | Array or bounded { items, nextCursor } page |
Optional operational routes
| Injected service | Routes |
|---|---|
execution | GET .../execution-sessions/:sessionId; POST .../interventions (202); GET .../events?after=sequence |
executionEventStream | GET .../execution-sessions/:sessionId/events/stream?after=sequence |
agentRegistry | POST /agents; create/list/get revisions; publish/deprecate with { expectedLifecycleRevision } |
handoffs | propose/get; accept with { expectedRevision, acceptedByParticipantId }; reject; bind-run; reconcile |
humanContributions | request/get; assign/start/complete/cancel contribution |
workManagement | enqueue delivery (202); retry with { expectedRevision, leaseToken }; Room metrics |
knowledge | create bundle revision; resolve ?reference=; read document by ID and reference |
liveView | GET /rooms/:roomId/live; GET /rooms/:roomId/live/stream |
planner | create/get/materialize/replan plans; reconcile from { triggerEventId } |
participantMembership | create or transition membership; list Room memberships |
LiveView and SSE
LiveView accepts optional coordinationId, comma-separated
executionSessionIds, handoffIds, contributionIds, planIds, and a
composite cursor. Omit projection IDs to use automatic Room-scoped discovery.
SSE endpoints emit the versioned AgentPlat envelope and honor request
cancellation. Consumers must resume from durable cursors; a connection is not
a source of completion or authority.
Concurrency and retry requirements
Lifecycle and operational writes that expose expectedRevision use
compare-and-set semantics. A conflict must be re-read and deliberately retried.
Interventions, coordination, plan materialization, Handoff projection and work
delivery preserve stable logical identities. Clients must not replace those
identities during retry. Work-management retry additionally requires the
current lease token.
For exact TypeScript bodies and return types, use the exports from
@agentplat/rooms and the package README for the exact coordinated version.