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

Two lease families guard an agent session. The approver lease grants one client the exclusive right to answer a session’s approval gates. The attachment lease keeps a live session, and a parked gate especially, from being torn down while no stream is attached. Use these endpoints to acquire, renew and release either lease, and to recover after a lease expires or a daemon restarts. Access to these agent routes follows the computer’s proxy permission rules. For the gates an approver lease lets you answer, see Session approvals.

OperationApprover leaseAttachment lease
AcquirePOST /api/v1/agent/sessions/{id}/approver-leasePOST /api/v1/agent/sessions/{id}/attachments
RenewPATCH /api/v1/agent/sessions/{id}/approver-leasePATCH /api/v1/agent/sessions/{id}/attachments/{lease_id}
ReleaseDELETE /api/v1/agent/sessions/{id}/approver-leaseDELETE /api/v1/agent/sessions/{id}/attachments/{lease_id}
JobGrants the exclusive right to answer the session’s gatesKeeps the live session and its parked gate from being reaped by the idle sweep
ExpiryFails closed on an always session after a lease has been minted: decisions stay refused until a holder acquires again. On a default-policy session, a decision without a capability is still accepted.Not revived by renewal: acquire a new lease
EventApprover leaseAttachment lease
Renew after the lease lapsed410 approver_lease_expired, re-acquire410 attachment_expired, acquire a new lease
Expired lease presented at a decision on an always session410 approver_lease_expired, expiry never lets anyone answerNot applicable, an attachment lease does not authorise decisions
Daemon or gateway restartThe lease is gone, acquire again; GET /api/v1/agent/sessions/{id}/approval reports held:falseThe lease is gone, acquire again; GET /api/v1/agent/sessions/{id}/state shows the session’s real state

Both lease families are held in memory. A restart ends them, and the client re-acquires.

POST /api/v1/agent/sessions/{id}/approver-lease

Section titled “POST /api/v1/agent/sessions/{id}/approver-lease”

Approver lease, acquire. Acquires the session’s approver lease: a random capability bound to the session, the daemon execution epoch, this holder and a generation, with a visible expiry.

  • holder is required: an opaque per-caller id that identifies this client as the holder. It is never a credential.
  • The capability is returned once, here. It is never shown again, so store it.
  • Takeover needs proof. While a lease is live, acquire is 409 approver_lease_held unless the request presents the current capability (X-Hoody-Approver-Lease or body.lease). On its own, replace: true never authorises, and holder strings are never compared. After expiry or release, an acquire needs no proof.
  • Expiry fails closed on an always session after a lease has been minted. The expired lease keeps the capability requirement (410 approver_lease_expired) until a holder acquires again. On a default-policy session, a decision without a capability is still accepted. An expired capability never authorises a decision.
  • A create or attach that asserts always is handed a lease only when none is live (approver_lease_error: approver_lease_held otherwise; an assertion never evicts).
NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope for the .hoody project layer, the record cwd and the tool and workflow cwd. The value must be UTF-8, other bytes 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-ComputerheaderstringNoPer-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id.

Lease request. holder is required on acquire; renew and release need only the capability.

NameTypeRequiredDescription
holderstringYesAn opaque per-caller id (1 to 64 printable ASCII, no spaces) that identifies this client as the holder, reported as holder on the event.gate_resolved stream event. Never a credential; an empty holder is refused with 400.
ttl_msintegerNoRequested lifetime in milliseconds. The daemon clamps it to its bounds. On renew it never shortens the lease: the expiry becomes the later of the current one and now + ttl_ms.
replacebooleanNoDocumentation only: a live lease is taken over only by presenting its current capability as proof (X-Hoody-Approver-Lease or body.lease). replace: true without the proof is still 409 approver_lease_held. After expiry or release an acquire needs no proof.
leasestringNoThe capability: what renew and release act on, and the proof an acquire presents to take over a live lease (alternative to the X-Hoody-Approver-Lease header).
FieldTypeDescription
leasestringThe capability to present as X-Hoody-Approver-Lease on POST /api/v1/agent/sessions/{id}/confirm. It is present only on acquire and is never shown again: store it.
heldbooleanWhether a lease is currently held.
holderstringThe holder identity: the holder sent on acquire, prefixed http:.
generationintegerLease generation. A decision echoes it, and a replacement bumps it, fencing the previous holder.
expires_atstringRFC3339 expiry; renew before it.
epochstringThe daemon execution epoch (an opaque id) the lease is bound to. A restart starts a new one, and every lease must be re-acquired.

Error responses use the envelope below.

FieldTypeRequiredDescription
codestringYesStable machine-readable error code.
messagestringYesHuman-readable error message.
detailsobjectNoOptional structured detail payload, present only for codes that carry it.

Lease acquired.

Media type: application/json

{
"lease": "8f2b7c4d1e6a9b3c5d8e2f1a7b4c6d9e",
"held": true,
"holder": "http:reviewer-01",
"generation": 3,
"expires_at": "2026-03-04T11:42:00Z",
"epoch": "ep_2c6f4a91"
}
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/{sessionId}/approver-lease" \
-H "Content-Type: application/json" \
-d '{"holder":"reviewer-01","ttl_ms":900000}'

PATCH /api/v1/agent/sessions/{id}/approver-lease

Section titled “PATCH /api/v1/agent/sessions/{id}/approver-lease”

Approver lease, renew. Extends the presented lease (X-Hoody-Approver-Lease header or body.lease) to now + ttl_ms.

  • A renew never shortens the lease. The expiry becomes the later of the current one and now + ttl_ms, so a renew delivered after a longer one, or with a shorter ttl_ms, leaves expires_at as it was. The response reports the expiry in force.
  • 409 approver_lease_invalid for a capability that does not verify.
  • 410 approver_lease_expired once the lease lapsed. Re-acquire.
NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-Approver-LeaseheaderstringNoThe approver-lease capability returned by POST /api/v1/agent/sessions/{id}/approver-lease. It is required on every decision (POST /api/v1/agent/sessions/{id}/confirm, or the confirmed re-issue of a gated tool run) on an always session whose lease was minted; the daemon verifies it at decision consumption. On renew and release it names the lease to act on.
X-Hoody-CwdheaderstringNoPer-request working-directory scope for the .hoody project layer, the record cwd and the tool and workflow cwd. The value must be UTF-8, other bytes 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-ComputerheaderstringNoPer-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id.

Lease request (renew and release): the capability via body.lease or the X-Hoody-Approver-Lease header; ttl_ms is optional on renew.

NameTypeRequiredDescription
ttl_msintegerNoRequested lifetime in milliseconds. The daemon clamps it to its bounds. On renew it never shortens the lease: the expiry becomes the later of the current one and now + ttl_ms.
leasestringNoThe capability: what renew and release act on, and the proof an acquire presents to take over a live lease (alternative to the X-Hoody-Approver-Lease header).
FieldTypeDescription
leasestringThe capability to present as X-Hoody-Approver-Lease on POST /api/v1/agent/sessions/{id}/confirm. It is present only on acquire and is never shown again: store it.
heldbooleanWhether a lease is currently held.
holderstringThe holder identity: the holder sent on acquire, prefixed http:.
generationintegerLease generation. A decision echoes it, and a replacement bumps it, fencing the previous holder.
expires_atstringRFC3339 expiry; renew before it.
epochstringThe daemon execution epoch (an opaque id) the lease is bound to. A restart starts a new one, and every lease must be re-acquired.

Error responses use the envelope below.

FieldTypeRequiredDescription
codestringYesStable machine-readable error code.
messagestringYesHuman-readable error message.
detailsobjectNoOptional structured detail payload, present only for codes that carry it.

Lease renewed.

Media type: application/json

{
"held": true,
"holder": "http:reviewer-01",
"generation": 3,
"expires_at": "2026-03-04T11:57:00Z",
"epoch": "ep_2c6f4a91"
}
Terminal window
curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/{sessionId}/approver-lease" \
-H "Content-Type: application/json" \
-H "X-Hoody-Approver-Lease: $APPROVER_LEASE" \
-d '{"ttl_ms":900000}'

DELETE /api/v1/agent/sessions/{id}/approver-lease

Section titled “DELETE /api/v1/agent/sessions/{id}/approver-lease”

Approver lease, release. Releases the presented lease (X-Hoody-Approver-Lease).

  • Releasing is never a privilege. A lapsed lease is released by its own capability too, and with no lease held the release succeeds as a no-op (held:false).
  • 409 approver_lease_invalid when the capability is not the current lease’s, for example when another holder acquired since.
  • On an always session where a lease was ever minted, decisions stay refused (approver_lease_required) until a holder acquires again.

This endpoint accepts no request body.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-Approver-LeaseheaderstringNoThe approver-lease capability returned by POST /api/v1/agent/sessions/{id}/approver-lease. It is required on every decision (POST /api/v1/agent/sessions/{id}/confirm, or the confirmed re-issue of a gated tool run) on an always session whose lease was minted; the daemon verifies it at decision consumption. On renew and release it names the lease to act on.
X-Hoody-CwdheaderstringNoPer-request working-directory scope for the .hoody project layer, the record cwd and the tool and workflow cwd. The value must be UTF-8, other bytes 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-ComputerheaderstringNoPer-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id.
FieldTypeDescription
heldbooleanWhether a lease is currently held.
holderstringThe holder identity: the holder sent on acquire, prefixed http:.
generationintegerLease generation. A decision echoes it, and a replacement bumps it, fencing the previous holder.
expires_atstringRFC3339 expiry; renew before it.
epochstringThe daemon execution epoch (an opaque id) the lease is bound to. A restart starts a new one, and every lease must be re-acquired.

When no lease is held at the moment the response is built, holder, generation and expires_at are omitted. The response reports the state at that moment, so another holder can acquire between the release and the response.

Error responses use the envelope below.

FieldTypeRequiredDescription
codestringYesStable machine-readable error code.
messagestringYesHuman-readable error message.
detailsobjectNoOptional structured detail payload, present only for codes that carry it.

Lease released, or none was held.

Media type: application/json

{
"held": false,
"epoch": "ep_2c6f4a91"
}
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/{sessionId}/approver-lease" \
-H "X-Hoody-Approver-Lease: $APPROVER_LEASE"

POST /api/v1/agent/sessions/{id}/attachments

Section titled “POST /api/v1/agent/sessions/{id}/attachments”

Attachment lease, acquire. Acquires a renewable attachment lease that keeps the live session, a parked approval gate especially, from being reaped by the 5-minute idle sweep while no stream is attached, so a client that dispatched a turn and disconnected can reconnect and still answer the gate.

  • The acquire is decided atomically against the reaper. A session whose close is already committed answers 404.
  • An attachment lease only keeps the session alive. The approver lease is a separate resource with its own expiry, renewed with PATCH /api/v1/agent/sessions/{id}/approver-lease. An expired approver lease fails closed.
  • Leases are in memory. A daemon or gateway restart ends them, GET /api/v1/agent/sessions/{id}/state then shows the session’s real state, and the client re-acquires.
  • The requested lifetime defaults to 15 minutes and is capped at 60 minutes.
NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope for the .hoody project layer, the record cwd and the tool and workflow cwd. The value must be UTF-8, other bytes 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-ComputerheaderstringNoPer-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id.

Lease request.

NameTypeRequiredDescription
ttl_msintegerNoRequested lifetime in milliseconds (default 15m, capped at 60m).
FieldTypeDescription
lease_idstringThe lease id (send it on PATCH or DELETE to renew or release).
expires_atstringRFC3339 expiry; renew before it or the session may be reaped once idle.

Error responses use the envelope below.

FieldTypeRequiredDescription
codestringYesStable machine-readable error code.
messagestringYesHuman-readable error message.
detailsobjectNoOptional structured detail payload, present only for codes that carry it.

Lease acquired.

Media type: application/json

{
"lease_id": "3f7c9a2b5d8e1f406a3b7c9d2e5f8a1b",
"expires_at": "2026-03-04T11:42:00Z"
}
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/{sessionId}/attachments" \
-H "Content-Type: application/json" \
-d '{"ttl_ms":900000}'

PATCH /api/v1/agent/sessions/{id}/attachments/{lease_id}

Section titled “PATCH /api/v1/agent/sessions/{id}/attachments/{lease_id}”

Attachment lease, renew. Extends the lease’s expiry.

  • The renewal is decided atomically against the reaper’s close, so it answers 404 once closing.
  • 410 attachment_expired once the lease lapsed. An expired lease is not revived by renewal: acquire a new one.
  • 404 when the lease is unknown, not this session’s, or not this owner’s.
  • The lease is re-authorized against the session’s current owner and realm, so a lease never outlives a changed pin or a credential switch.
NameInTypeRequiredDescription
idpathstringYesThe session id.
lease_idpathstringYesThe lease id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope for the .hoody project layer, the record cwd and the tool and workflow cwd. The value must be UTF-8, other bytes 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-ComputerheaderstringNoPer-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id.

Renewal.

NameTypeRequiredDescription
ttl_msintegerNoNew lifetime in milliseconds from now (default 15m, capped at 60m).
FieldTypeDescription
lease_idstringThe lease id (send it on PATCH or DELETE to renew or release).
expires_atstringRFC3339 expiry; renew before it or the session may be reaped once idle.

Error responses use the envelope below.

FieldTypeRequiredDescription
codestringYesStable machine-readable error code.
messagestringYesHuman-readable error message.
detailsobjectNoOptional structured detail payload, present only for codes that carry it.

Lease renewed.

Media type: application/json

{
"lease_id": "3f7c9a2b5d8e1f406a3b7c9d2e5f8a1b",
"expires_at": "2026-03-04T11:57:00Z"
}
Terminal window
curl -X PATCH "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/{sessionId}/attachments/{lease_id}" \
-H "Content-Type: application/json" \
-d '{"ttl_ms":900000}'

DELETE /api/v1/agent/sessions/{id}/attachments/{lease_id}

Section titled “DELETE /api/v1/agent/sessions/{id}/attachments/{lease_id}”

Attachment lease, release. Drops the lease; the session resumes ordinary idle-reap behaviour. It answers 404 when the lease is unknown, not this session’s, or not this owner’s.

This endpoint accepts no request body.

NameInTypeRequiredDescription
idpathstringYesThe session id.
lease_idpathstringYesThe lease id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope for the .hoody project layer, the record cwd and the tool and workflow cwd. The value must be UTF-8, other bytes 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-ComputerheaderstringNoPer-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the query alias of the X-Hoody-Realm header, read when the header is absent or empty: global (not tied to a realm) or a 24-hex realm id.
FieldTypeDescription
statusstringok on success.
releasedbooleanAlways true on a 200.

Error responses use the envelope below.

FieldTypeRequiredDescription
codestringYesStable machine-readable error code.
messagestringYesHuman-readable error message.
detailsobjectNoOptional structured detail payload, present only for codes that carry it.

Lease released.

Media type: application/json

{
"status": "ok",
"released": true
}
Terminal window
curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/{sessionId}/attachments/{lease_id}"