Agent: Session leases
Section titled “Agent: Session leases”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.
Lease families at a glance
Section titled “Lease families at a glance”| Operation | Approver lease | Attachment lease |
|---|---|---|
| Acquire | POST /api/v1/agent/sessions/{id}/approver-lease | POST /api/v1/agent/sessions/{id}/attachments |
| Renew | PATCH /api/v1/agent/sessions/{id}/approver-lease | PATCH /api/v1/agent/sessions/{id}/attachments/{lease_id} |
| Release | DELETE /api/v1/agent/sessions/{id}/approver-lease | DELETE /api/v1/agent/sessions/{id}/attachments/{lease_id} |
| Job | Grants the exclusive right to answer the session’s gates | Keeps the live session and its parked gate from being reaped by the idle sweep |
| Expiry | Fails 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 |
Lease expiry and restarts
Section titled “Lease expiry and restarts”| Event | Approver lease | Attachment lease |
|---|---|---|
| Renew after the lease lapsed | 410 approver_lease_expired, re-acquire | 410 attachment_expired, acquire a new lease |
Expired lease presented at a decision on an always session | 410 approver_lease_expired, expiry never lets anyone answer | Not applicable, an attachment lease does not authorise decisions |
| Daemon or gateway restart | The lease is gone, acquire again; GET /api/v1/agent/sessions/{id}/approval reports held:false | The 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.
holderis 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_heldunless the request presents the current capability (X-Hoody-Approver-Leaseorbody.lease). On its own,replace: truenever authorises, and holder strings are never compared. After expiry or release, an acquire needs no proof. - Expiry fails closed on an
alwayssession 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
alwaysis handed a lease only when none is live (approver_lease_error: approver_lease_heldotherwise; an assertion never evicts).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”Lease request. holder is required on acquire; renew and release need only the capability.
| Name | Type | Required | Description |
|---|---|---|---|
holder | string | Yes | An 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_ms | integer | No | Requested 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. |
replace | boolean | No | Documentation 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. |
lease | string | No | The 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). |
Response fields
Section titled “Response fields”| Field | Type | Description |
|---|---|---|
lease | string | The 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. |
held | boolean | Whether a lease is currently held. |
holder | string | The holder identity: the holder sent on acquire, prefixed http:. |
generation | integer | Lease generation. A decision echoes it, and a replacement bumps it, fencing the previous holder. |
expires_at | string | RFC3339 expiry; renew before it. |
epoch | string | The 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.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable error message. |
details | object | No | Optional structured detail payload, present only for codes that carry it. |
Responses
Section titled “Responses”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"}Bad request.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not empty, global, or a 24-hex id). | Pass a valid realm selector. |
Forbidden.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Not found.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Another unexpired holder exists, or the presented capability is not the current lease.
Media type: application/json
{ "code": "approver_lease_held", "message": "another holder owns the approver lease"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approver_lease_held | Approver lease held | Another unexpired holder owns this session’s approver lease. details.expires_at is when it lapses unless renewed (RFC3339); the holder and its capability are never disclosed. | Wait for it to expire or be released, or take it over by presenting its current capability as proof (X-Hoody-Approver-Lease / body.lease). On its own, replace: true never authorises. |
approver_lease_invalid | Approver lease invalid | The presented capability does not verify for this session (wrong session, a fenced generation, or a daemon restart). | Re-acquire the lease (POST /api/v1/agent/sessions/{id}/approver-lease). |
Payload too large.
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured size limit (default 8 MiB). Reduce the request body. | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
Too many requests.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
Internal error.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
Service unavailable.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
Examples
Section titled “Examples”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}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const lease = await client.agent.sessions.approverLease.claim('{sessionId}', { 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 shorterttl_ms, leavesexpires_atas it was. The response reports the expiry in force. 409 approver_lease_invalidfor a capability that does not verify.410 approver_lease_expiredonce the lease lapsed. Re-acquire.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
X-Hoody-Approver-Lease | header | string | No | The 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-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”Lease request (renew and release): the capability via body.lease or the X-Hoody-Approver-Lease header; ttl_ms is optional on renew.
| Name | Type | Required | Description |
|---|---|---|---|
ttl_ms | integer | No | Requested 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. |
lease | string | No | The 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). |
Response fields
Section titled “Response fields”| Field | Type | Description |
|---|---|---|
lease | string | The 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. |
held | boolean | Whether a lease is currently held. |
holder | string | The holder identity: the holder sent on acquire, prefixed http:. |
generation | integer | Lease generation. A decision echoes it, and a replacement bumps it, fencing the previous holder. |
expires_at | string | RFC3339 expiry; renew before it. |
epoch | string | The 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.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable error message. |
details | object | No | Optional structured detail payload, present only for codes that carry it. |
Responses
Section titled “Responses”Lease renewed.
Media type: application/json
{ "held": true, "holder": "http:reviewer-01", "generation": 3, "expires_at": "2026-03-04T11:57:00Z", "epoch": "ep_2c6f4a91"}Bad request.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not empty, global, or a 24-hex id). | Pass a valid realm selector. |
Forbidden.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Not found.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The capability does not verify.
Media type: application/json
{ "code": "approver_lease_invalid", "message": "the approver lease does not verify"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approver_lease_invalid | Approver lease invalid | The presented capability does not verify for this session (wrong session, a fenced generation, or a daemon restart). | Re-acquire the lease (POST /api/v1/agent/sessions/{id}/approver-lease). |
The lease expired.
Media type: application/json
{ "code": "approver_lease_expired", "message": "the approver lease expired"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approver_lease_expired | Approver lease expired | The presented lease lapsed; an expired lease never authorises a decision. | Re-acquire the lease (POST /api/v1/agent/sessions/{id}/approver-lease). |
Payload too large.
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured size limit (default 8 MiB). Reduce the request body. | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
Too many requests.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
Internal error.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
Service unavailable.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
Examples
Section titled “Examples”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}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
// The capability returned by the acquire call.const capability = '8f2b7c4d1e6a9b3c5d8e2f1a7b4c6d9e';
const renewed = await client.agent.sessions.approverLease.renew( '{sessionId}', { ttl_ms: 900000 }, { approverLease: capability });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_invalidwhen the capability is not the current lease’s, for example when another holder acquired since.- On an
alwayssession where a lease was ever minted, decisions stay refused (approver_lease_required) until a holder acquires again.
This endpoint accepts no request body.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
X-Hoody-Approver-Lease | header | string | No | The 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-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Response fields
Section titled “Response fields”| Field | Type | Description |
|---|---|---|
held | boolean | Whether a lease is currently held. |
holder | string | The holder identity: the holder sent on acquire, prefixed http:. |
generation | integer | Lease generation. A decision echoes it, and a replacement bumps it, fencing the previous holder. |
expires_at | string | RFC3339 expiry; renew before it. |
epoch | string | The 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.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable error message. |
details | object | No | Optional structured detail payload, present only for codes that carry it. |
Responses
Section titled “Responses”Lease released, or none was held.
Media type: application/json
{ "held": false, "epoch": "ep_2c6f4a91"}Bad request.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not empty, global, or a 24-hex id). | Pass a valid realm selector. |
Forbidden.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Not found.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The capability is not the current lease’s.
Media type: application/json
{ "code": "approver_lease_invalid", "message": "the approver lease does not verify"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
approver_lease_invalid | Approver lease invalid | The presented capability does not verify for this session (wrong session, a fenced generation, or a daemon restart). | Re-acquire the lease (POST /api/v1/agent/sessions/{id}/approver-lease). |
Too many requests.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
Internal error.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
Service unavailable.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
Examples
Section titled “Examples”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"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
// The capability returned by the acquire call.const capability = '8f2b7c4d1e6a9b3c5d8e2f1a7b4c6d9e';
const released = await client.agent.sessions.approverLease.release('{sessionId}', { approverLease: capability});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}/statethen shows the session’s real state, and the client re-acquires. - The requested lifetime defaults to 15 minutes and is capped at 60 minutes.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”Lease request.
| Name | Type | Required | Description |
|---|---|---|---|
ttl_ms | integer | No | Requested lifetime in milliseconds (default 15m, capped at 60m). |
Response fields
Section titled “Response fields”| Field | Type | Description |
|---|---|---|
lease_id | string | The lease id (send it on PATCH or DELETE to renew or release). |
expires_at | string | RFC3339 expiry; renew before it or the session may be reaped once idle. |
Error responses use the envelope below.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable error message. |
details | object | No | Optional structured detail payload, present only for codes that carry it. |
Responses
Section titled “Responses”Lease acquired.
Media type: application/json
{ "lease_id": "3f7c9a2b5d8e1f406a3b7c9d2e5f8a1b", "expires_at": "2026-03-04T11:42:00Z"}Bad request.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not empty, global, or a 24-hex id). | Pass a valid realm selector. |
Forbidden.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Not found.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Payload too large.
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured size limit (default 8 MiB). Reduce the request body. | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
Too many requests.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
Internal error.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
Service unavailable.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
Examples
Section titled “Examples”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}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const attachment = await client.agent.sessions.attachments.claim('{sessionId}', { 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_expiredonce 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
lease_id | path | string | Yes | The lease id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”Renewal.
| Name | Type | Required | Description |
|---|---|---|---|
ttl_ms | integer | No | New lifetime in milliseconds from now (default 15m, capped at 60m). |
Response fields
Section titled “Response fields”| Field | Type | Description |
|---|---|---|
lease_id | string | The lease id (send it on PATCH or DELETE to renew or release). |
expires_at | string | RFC3339 expiry; renew before it or the session may be reaped once idle. |
Error responses use the envelope below.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable error message. |
details | object | No | Optional structured detail payload, present only for codes that carry it. |
Responses
Section titled “Responses”Lease renewed.
Media type: application/json
{ "lease_id": "3f7c9a2b5d8e1f406a3b7c9d2e5f8a1b", "expires_at": "2026-03-04T11:57:00Z"}Bad request.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not empty, global, or a 24-hex id). | Pass a valid realm selector. |
Forbidden.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Not found.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
The lease expired.
Media type: application/json
{ "code": "attachment_expired", "message": "the attachment lease expired; acquire a new one"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
attachment_expired | Attachment lease expired | The attachment lease already lapsed; an expired lease is not revived by renewal. | Acquire a new lease (POST /api/v1/agent/sessions/{id}/attachments). |
Payload too large.
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the configured size limit (default 8 MiB). Reduce the request body. | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
Too many requests.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
Internal error.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
Service unavailable.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
Examples
Section titled “Examples”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}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const renewed = await client.agent.sessions.attachments.renew( '{sessionId}', '{lease_id}', { 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
lease_id | path | string | Yes | The lease id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted means local). Rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Response fields
Section titled “Response fields”| Field | Type | Description |
|---|---|---|
status | string | ok on success. |
released | boolean | Always true on a 200. |
Error responses use the envelope below.
| Field | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Stable machine-readable error code. |
message | string | Yes | Human-readable error message. |
details | object | No | Optional structured detail payload, present only for codes that carry it. |
Responses
Section titled “Responses”Lease released.
Media type: application/json
{ "status": "ok", "released": true}Bad request.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not empty, global, or a 24-hex id). | Pass a valid realm selector. |
Forbidden.
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Not found.
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Too many requests.
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded; the gateway throttled the request before dispatch. | Honor the Retry-After header and retry; reduce the request rate. |
Internal error.
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry; if persistent, inspect the daemon logs. |
Service unavailable.
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
Examples
Section titled “Examples”curl -X DELETE "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/{sessionId}/attachments/{lease_id}"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const released = await client.agent.sessions.attachments.release('{sessionId}', '{lease_id}');