Skip to content

Beta: these docs are still being updated. The next full update is on 19 November at 8 PM UTC. Docs in beta. Full update 19 Nov, 8 PM UTC.

Hoody.com

The change-token endpoints expose one opaque token for each visible Work list: sessions, todos, workflow_runs, loops, tasks, gates, agents, rules, and memory. Use them to poll or stream changes and re-list only the topics whose token moved, rather than re-listing every topic on every tick.

These endpoints are exposed by a computer’s agent service. Access to a computer’s agent routes is governed by that computer’s proxy permission rules.

Tokens are opaque. Compare them for equality, never parse or order them. The scope value is also opaque and uses 16 hexadecimal characters. Compare scope for equality and re-list every topic when it changes. Tokens are computed from what the caller can see, so work in another realm or of another account never moves a token. Tokens are hints, and the Work lists remain authoritative.

The recommended pattern is:

  1. Read the tokens with one call to GET /api/v1/agent/changes, or open the SSE stream.
  2. List the topics you care about using their list endpoints.
  3. Re-read the tokens later.
  4. Re-list only the topics whose token moved since step 1. A missing or null token also requires re-listing that topic.
  5. When scope changes between reads, re-list every topic because the tokens belong to a different realm and account than the previous answer.

The JSON read is request-driven: each call returns the tokens as they stand at that moment. One read is shared for 1 s by requests with the same realm and scope headers, so an answer can be up to 1 s old. After the active realm or account switches, the new scope arrives within that second. The SSE stream is the one that re-reads tokens every 2 s, and one read per scope per second is shared by every stream.

Returns {scope, tokens} with one opaque token per topic. Read the response, then list the topics you care about. Later, re-read and re-list only the topics whose token moved, and every topic when scope changes.

NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, or tool and workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id. The realm query parameter is an alternative. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported.
realmquerystringNoPer-request realm selector and the query alias of X-Hoody-Realm. It is read when the header is absent or empty. The value must be global or a 24-hex realm id. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported.

This endpoint accepts no request body.

JSON error responses contain code and message, with optional structured details.

Media type: application/json

The change tokens.

{
"scope": "3f9a1c0b7d2e4a65",
"tokens": {
"sessions": "tok_s_a1b2c3d4e5f6",
"todos": "tok_t_b2c3d4e5f6a7",
"workflow_runs": "tok_w_c3d4e5f6a7b8",
"loops": "tok_l_d4e5f6a7b8c9",
"tasks": "tok_k_e5f6a7b8c9d0",
"gates": "tok_g_f6a7b8c9d0e1",
"agents": "tok_a_a7b8c9d0e1f2",
"rules": "tok_r_b8c9d0e1f2a3",
"memory": "tok_m_c9d0e1f2a3b4"
}
}
FieldTypeDescription
scopestring, requiredOpaque 16-hex-character value naming the realm and account the tokens belong to. It never carries the account itself. Compare it for equality, and re-list every topic when it changes.
tokensobject, requiredContains one opaque token per readable topic. Compare a token with the one you last saw, and re-list that topic when it differs. Never parse a token.
tokens.sessionsstringMoves when a visible session is created, closed, renamed, or re-persisted, such as for a model, agent, or cost change. It also moves when the session attaches or detaches, a turn starts, parks on a gate, or ends, a gate starts or stops waiting for a person, or a listSessions row changes because this agent holds or releases the session’s turn slot or closes it. Re-list with listSessions.
tokens.todosstringMoves on any change to a visible todo. Re-list with listTodos, and use getTodo for an open todo.
tokens.workflow_runsstringMoves when a visible run starts, steps, finishes, is cancelled, or is evicted. Re-list with listWorkflowRuns, and use getWorkflowRun for one run.
tokens.loopsstringMoves when a visible loop is created, deleted, paused, resumed, fires, finishes, or spends. Countdowns such as next_in_ms and expires_in_ms do not move it. Re-list with listAllLoops.
tokens.tasksstringMoves when a helper task of a visible live session starts, makes progress, or ends. Re-list with listTasks for the sessions you show.
tokens.gatesstringMoves when a gate of a visible live session parks or resolves, including the session’s own confirmation or question and each helper’s gate on a helper_gates session. Re-list with listPendingGates, or use getSessionState for one session’s pending_gate and pending_helper_gates.
tokens.agentsstringMoves when the realm’s agent list changes, such as after a create, delete, rename, model, tools, turns, or source edit. Re-list with listAgents.
tokens.rulesstringMoves when a rules layer of a visible live session changes, such as through setHookRules. It also moves when a settings file read by getHookRules changes for the same scope headers, with or without a live session. Re-list with getHookRules, listHooks, or getSessionRulesApplies.
tokens.memorystringMoves when the realm’s memory changes, such as after a memory is saved, edited, or deleted, an observation is captured, a project is erased, a consolidation pass is queued, started, or ended, or memory is switched on or off. While the store cannot be reached or memory reads are refused, the token holds until that changes. Re-read with getMemoryStatus, listMemoryProjects, or listMemoryItems.
unavailableobjectPresent only when a topic could not be read. Maps each topic name to its reason. That topic has no token in this answer and must be re-listed.
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.changes.get();
await client.agent.changes.get({
cwd: '/home/user/project',
configDir: '/home/user/project/.hoody',
agentRealm: 'global',
});

Streams change tokens as Server-Sent Events over getChanges. The stream starts with retry: 5000. Its first event frame is a snapshot carrying {scope, tokens}. After it, a changed frame carrying {topic, token} is sent for each topic whose token moved, and a new snapshot is sent when scope changes.

The stream re-reads tokens every 2 s, and one read per scope per second is shared by every stream.

There are no id: lines. After a reconnect, start again from the new snapshot and re-list the topics that differ from what you hold. Heartbeat comments are sent every 25 s as bare : comment lines. An end frame carrying {reason} closes the stream when the tokens cannot be read, with the reason set to changes unavailable.

The stream counts toward the per-IP stream cap (--http-max-streams-per-ip, default 16). A Frame tab holds this stream, the focused session’s /stream, and a prompt:stream while sending.

NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, or tool and workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id. The realm query parameter is an alternative. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported.
realmquerystringNoPer-request realm selector and the query alias of X-Hoody-Realm. It is read when the header is absent or empty. The value must be global or a 24-hex realm id. On a session route, it names the realm in which the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. A different realm for an agent pinned to one realm returns 400 realm_scope_unsupported.

This endpoint accepts no request body.

JSON error responses contain code and message, with optional structured details.

Media type: text/event-stream

The body is a sequence of SSE frames separated by blank lines.

retry: 5000
event: snapshot
data: {"scope":"3f9a1c0b7d2e4a65","tokens":{"sessions":"tok_s_a1b2c3d4e5f6","todos":"tok_t_b2c3d4e5f6a7","workflow_runs":"tok_w_c3d4e5f6a7b8","loops":"tok_l_d4e5f6a7b8c9","tasks":"tok_k_e5f6a7b8c9d0","gates":"tok_g_f6a7b8c9d0e1","agents":"tok_a_a7b8c9d0e1f2","rules":"tok_r_b8c9d0e1f2a3","memory":"tok_m_c9d0e1f2a3b4"}}
:
event: changed
data: {"topic":"sessions","token":"tok_s_b3c4d5e6f7a8"}
:
event: changed
data: {"topic":"memory","token":null}
event: snapshot
data: {"scope":"6b4d2e8a1f0c7d93","tokens":{"sessions":"tok_s_c4d5e6f7a8b9","todos":"tok_t_d5e6f7a8b9c0","workflow_runs":"tok_w_e6f7a8b9c0d1","loops":"tok_l_f7a8b9c0d1e2","tasks":"tok_k_a8b9c0d1e2f3","gates":"tok_g_b9c0d1e2f3a4","agents":"tok_a_c0d1e2f3a4b5","rules":"tok_r_d1e2f3a4b5c6"},"unavailable":{"memory":"memory store unavailable"}}
:
event: changed
data: {"topic":"gates","token":"tok_g_e3f4a5b6c7d8"}
event: end
data: {"reason":"changes unavailable"}
FrameWhenPayload
retryBefore the first event frameretry: 5000.
snapshotFirst frame after connect, and on every scope change{scope, tokens}, with the same token shape as the JSON read. It may also contain an unavailable map naming each topic that could not be read and its reason. A topic named in unavailable has no token in that snapshot and must be re-listed. Re-list topics whose token differs from what you hold, and re-list every topic if scope changed.
changedFor each topic whose token moved{topic, token}. The token is null when the topic becomes unreadable. Re-list the topic when its token changes, and re-list it whenever its token is missing or null.
Heartbeat commentEvery 25 sA bare : comment line. Ignore it.
endWhen the tokens cannot be read{reason} with reason set to changes unavailable. The stream closes.
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.changes.stream();
await client.agent.changes.stream({
cwd: '/home/user/project',
configDir: '/home/user/project/.hoody',
agentRealm: 'global',
});