An app environment is the server that runs agents and apps. You talk to it by sending signed actions. Each request is one action, such as CreateSession. The client packs it as DAG-CBOR and signs it with a Seed account key, or with a key that account has authorized. The types are in apps/protocol/src/index.ts. The server code that handles them is in apps/src/api-service.ts, and the HTTP routes are in apps/src/main.ts.
This page covers what every request shares: the endpoint, the envelope and how the server checks it, protocol versions, errors, access levels and idempotency. The request and response of each action are on six pages, one per kind of thing. Actions lists them. Live updates use the same envelope over a socket. WebSocket subscriptions describes them.
Endpoint
POST /hm/api/apps/message
Content-Type: application/cbor
Accept: application/cbor/hm/api/apps is the main prefix of the API. It works on the app environment's own host and on the address of a site that forwards to it. The same routes answer under /hm/api/agents. Released clients, published bindings and webhook URLs that were already handed out use that second prefix. Both prefixes serve message, ws, webhooks/<triggerId>, health, version, perf and metrics.
Older paths are accepted too, for older clients and for a server on its own host. The ones a client of this API needs are POST /api/message, POST /agents/api/message, and the socket at /agents/ws. Endpoints and health says where the service is mounted.
A response is an AgentResponse value, encoded as DAG-CBOR. Every response to a signed action carries the server's protocol version in the X-Agents-Protocol header. The version and health routes report it too, as protocol and minClientProtocol.
Protocol versioning
Clients and servers are updated at different times. So the API has a version: one whole number, AGENTS_PROTOCOL_VERSION in apps/protocol/src/version.ts.
A client says which version it speaks in envelope.protocol. An envelope with no protocol field is read as version 1.
The server answers in the shape of that version. The code that converts is in apps/src/protocol-compat.ts.
The server's version is 3, and MIN_CLIENT_PROTOCOL is 1.
Below MIN_CLIENT_PROTOCOL the server refuses with HTTP 426 and {_: 'Error', code: 'protocol_too_old'}.
A client below protocol 3 also gets this 426 when it tries to read or change a trigger that needs protocol 3.
Signed envelope
type SignedActionEnvelope = {
type: 'AgentsAction'
signer: blobs.Principal
sig: blobs.Signature
account: blobs.Principal
protocol?: number // AGENTS_PROTOCOL_VERSION of the client; absent = 1
capability?: string // CID of the Capability blob a delegated signer acts under
capabilityBlob?: Uint8Array // its bytes, so any server can verify without the network
action: AgentAction
}
type AgentAction = UnsignedAgentAction & {
ts: number // Unix epoch milliseconds
}signer and account are principals, and sig is an Ed25519 signature, the same scheme used to sign blobs. The server checks, in this order:
envelope shape and type;
principal/signature byte shapes;
signed action timestamp is within five minutes of server local time;
Ed25519 signature through verify() from @seed-hypermedia/client (imported through the @shm/shared/blobs re-export);
signer is the account, or a locally authorized signer for it, or presents a delegation: capability names a Capability blob whose bytes come from capabilityBlob, from a delegation this server verified before, or from the HM network; the blob must be issued by account, delegate to signer, carry role AGENT or WRITER, not be self-issued, be at most 64 KiB, and hash to the CID given in capability;
action is valid for the transport.
Every failed check is HTTP 401. A body that is not application/cbor is 415. CBOR that cannot be decoded is 400.
Never sign undefined
Leave a field with no value out of the action object before you sign. Do not set it to undefined. The SDK's DAG-CBOR encoder writes undefined as null. The server then reads null, the bytes it checks differ from the bytes you signed, and the signature fails. This includes afterSeq on Subscribe.
Actions
An action is one member of the UnsignedAgentAction type in apps/protocol/src/index.ts, plus the signed ts. The tables list every action in that type.
The Level column is the access level the signer needs on the agent, session, trigger or run that the action names. "account" means the action reads or changes the signer's own account and names no agent. "none" means any signed account may send it.
Agents
Reference: agents.
Action | Level | What it does |
|---|---|---|
| account | Lists the agents the account owns or collaborates on. |
| account | Creates an agent from a definition. |
| reader | Returns one agent and its session count. |
| writer | Replaces the agent definition. |
| owner | Deletes the agent with its sessions, triggers and state. |
| owner | Gives an agent the identity of a published document. |
| owner | Takes a mounted agent out of its document. |
| account | Lists pending invitations sent to the account. |
| account | Accepts an invitation and returns the agent. |
| account | Deletes a pending invitation. |
| reader | Lists the owner, members and public flags of an agent. |
| owner | Invites an account as reader or writer, or changes a role. |
| owner | Removes a member or cancels an invitation. |
| owner | Turns public read access on or off. |
| owner | Turns public chat on or off. |
| reader | Lists the tool documents in the agent's |
| writer | Refused with 410: agents do not hold private code tools. |
| writer | Deletes one authored tool document. |
Providers, identities and secrets
Reference: providers and identities. ListModelProviders, ListProviderModels and ListSigningIdentities take an optional agentId. With it, they answer for the owner of an agent the signer can read.
Action | Level | What it does |
|---|---|---|
| account | Lists configured model providers, redacted. |
| account | Asks one provider for its model list. |
| account | Creates or replaces a provider config. |
| account | Deletes a provider and the secrets only it used. |
| account | Starts a subscription login. |
| account | Completes a login with a pasted code. |
| account | Reports whether a login is pending, completed or failed. |
| account | Cancels a pending login. |
| account | Lists the account keys the server holds for signing. |
| account | Generates a new account key on the server. |
| account | Stores an existing account key for the server to sign with. |
| account | Renames a signing identity and republishes its profile. |
| account | Deletes the stored key. |
| account | Encrypts and stores a secret. |
| account | Lists configured MCP servers, redacted. |
| account | Creates or replaces an MCP server and discovers its tools. |
| account | Discovers an MCP server's tools again. |
| account | Deletes an MCP server and its secrets. |
| none | Registers a delegated signer ahead of time. Accepted for older clients. |
Triggers
Reference: triggers.
Action | Level | What it does |
|---|---|---|
| reader | Lists an agent's triggers. |
| reader | Returns one trigger with its sessions and recent firings. |
| writer | Creates a trigger. |
| writer | Patches a trigger. |
| writer | Merges one activity trigger into another. |
| writer | Deletes a trigger. |
| none | Lists the triggers that an app's or agent's trigger documents define on this server. |
| writer (of the agent, or of the space holding the trigger document) | Fires a schedule trigger once, now. |
Sessions and runs
Reference: sessions and runs.
Action | Level | What it does |
|---|---|---|
| chat | Creates an idle session on an agent. |
| reader | Lists sessions, newest first, with keyset paging. |
| reader | Returns a session and a page of its durable events. |
| reader | Returns one durable event whole. |
| writer | Changes the title, model override or thoroughness. |
| writer | Deletes a session and its events. |
| chat | Appends a user message and queues a run for it. |
| writer | Runs |
| chat | Stops the running turn and cancels the session's live runs. |
| chat | Runs again a session whose latest run failed. |
| owner | Attaches a desktop browser window to a session. |
| owner | Waits for the next browser command. |
| owner | Returns the result of one browser command. |
| owner | Detaches the desktop browser. |
| reader | Returns one run. |
| reader | Lists runs of a root run, a session or an agent. |
| writer | Cancels a run and its descendants. |
| writer | Delivers a named signal to a parked run. |
| reader | Returns a script run's journal entries. |
| reader, or account for an | Opens a live subscription. Accepted only over WebSocket. |
Memory and uploads
Reference: memory and uploads.
Action | Level | What it does |
|---|---|---|
| reader | Lists every memory file and directory. |
| reader | Lists one directory level. |
| reader | Returns one file. |
| writer | Writes a whole file. |
| writer | Deletes a file or a directory. |
| writer | Fetches a public URL into memory. |
| writer | Publishes a memory file as an |
| chat | Stages a file for a session message. |
| reader | Returns an attachment's bytes. |
| writer or chat | Starts a chunked upload to memory (writer) or to a session (chat). |
| as the upload | Adds the next chunk. |
| as the upload | Finishes the upload. |
| as the upload | Discards the upload. |
Running apps
Reference: running apps. "Space writer" means the signer can write the space that holds the app document.
Action | Level | What it does |
|---|---|---|
| space writer | Runs an app on this server, or replaces its private config. |
| space writer | Stops an app and forgets its private config. |
| none | Says whether an app runs on this server. |
| none | Says whether this server would run an app for the signer. |
| none | Calls a tool of a running app. |
| none | Lists a tool's recorded calls. |
| none | Returns one recorded call. |
Responses
Each action has its own success response. Every error has this shape:
type ErrorResponse = {
_: 'Error'
message: string
code?: ProtocolErrorCode // e.g. 'protocol_too_old'
}An error the server expects carries its own HTTP status and sometimes a code. An error the server does not expect is logged and returned as 500 with Internal server error: <message>.
What each status means:
Status | Meaning |
|---|---|
| CBOR that cannot be decoded, an unknown action, or invalid input |
| the envelope or its delegation failed a check, or a provider sign-in has expired |
| your access level is too low |
| the thing does not exist or you may not see it (an agent you cannot read looks the same as one that does not exist) |
| the request conflicts with the current state, such as an idempotency id reused with a different body, a session with a live run, or an upload chunk at the wrong offset |
| an action that is no longer offered ( |
| an upload, chunk or attachment that is too big |
| a body that is not |
| a client protocol the server no longer serves |
| too many uploads in progress |
| something the server depends on failed, such as a model provider, an MCP server or the Hypermedia server |
| the server is still starting; try again in a few seconds |
Access levels
An agent has one owner. It can have collaborators that accepted an invitation, each with the role reader or writer. When publicRead is on, every other signed account is a reader. When publicChat is on too, every other signed account is a chatter. Each action needs one of four levels:
Level | Who has it | What it allows |
|---|---|---|
reader | owner, writer, reader, chatter | read the agent, its sessions, triggers, memory and tools |
chat | owner, writer, chatter (not a plain reader) | create a session, send it a message, upload an attachment, stop or retry a session |
writer | owner, writer | edit the agent, its triggers, memory and tools; rename or delete a session; run a verb as the user; cancel or signal a run |
owner | owner | manage collaborators and public access; mount, unmount and delete the agent; use the session browser |
Whatever your role, the agent's data is stored under its owner's account.
Agent sharing explains what the roles mean to the people who share an agent. These roles are separate from Hypermedia roles on documents.
Idempotency
Idempotency means a request you send twice is done once. Many actions take a client id (clientRequestId or clientMessageId) for this. For each id the server stores:
account ID;
action name;
client request or message ID;
request CBOR bytes;
response CBOR bytes;
creation timestamp.
If you send the same id with the same request bytes, the server returns the stored response again. If you send the same id with different request bytes, it returns 409.
See also
Identity for the keys that sign every request
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime