Agent: Jobs

The Agent Jobs endpoints manage async job lifecycle for the agent. Use these routes to poll a job’s status, fetch a terminal result, and cancel a pending or running job (or delete a finished record). Dispatch and workflow runs are also observable on the session stream — these endpoints are the canonical way to track a job by id.

Note

All endpoints in this group are container-scoped. Use the container hostname template https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com and authenticate by reaching the agent through hoody-proxy, not by connecting to the container directly.

GET /api/v1/agent/jobs/{id}

Returns the status of an async job (dispatch, workflow run, or long tool call). The run_id field is null during the brief dispatch window for workflow runs.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Response

200

{
  "job_id": "job_01HMZK3X4F2N9P7QY8WT6VDRAB",
  "kind": "session.workflow",
  "session_id": "sess_01HMZK2XR9TJ6M3K0QW5BVPEFN",
  "run_id": "run_01HMZK3X9C8W4PQ6Y2TBN5VKDA",
  "status": "running",
  "result": {},
  "created_at": "2025-01-15T18:42:11.804Z",
  "updated_at": "2025-01-15T18:42:14.217Z"
}

400

{
  "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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
forbidden	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "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.

429

{
  "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.

500

{
  "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.

SDK Usage

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/jobs/job_01HMZK3X4F2N9P7QY8WT6VDRAB" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /workspace/project" \
  -H "X-Hoody-Config-Dir: /home/user/.hoody" \
  -H "X-Hoody-Container: {projectId}-{containerId}" \
  -H "X-Hoody-Realm: global"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.jobs.getJob('job_01HMZK3X4F2N9P7QY8WT6VDRAB', {
  X-Hoody-Cwd: '/workspace/project',
  'X-Hoody-Config-Dir': '/home/user/.hoody',
  'X-Hoody-Container': '{projectId}-{containerId}',
  'X-Hoody-Realm': 'global',
  realm: 'global',
});

GET /api/v1/agent/jobs/{id}/result

Returns the result of a completed job, or the running status. Dispatch jobs are observed on the session stream — the result endpoint reports the terminal status only.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Response

200

{
  "status": "succeeded",
  "result": {
    "answer_assist_suggestion": "The user is asking for the current build status. Reply: 'Build #482 passed all checks 3 minutes ago.'"
  },
  "session_id": "sess_01HMZK2XR9TJ6M3K0QW5BVPEFN"
}

400

{
  "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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
forbidden	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "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.

429

{
  "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.

500

{
  "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.

SDK Usage

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/jobs/job_01HMZK3X4F2N9P7QY8WT6VDRAB/result" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /workspace/project" \
  -H "X-Hoody-Config-Dir: /home/user/.hoody" \
  -H "X-Hoody-Container: {projectId}-{containerId}" \
  -H "X-Hoody-Realm: global"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.jobs.getJobResult('job_01HMZK3X4F2N9P7QY8WT6VDRAB', {
  X-Hoody-Cwd: '/workspace/project',
  'X-Hoody-Config-Dir': '/home/user/.hoody',
  'X-Hoody-Container': '{projectId}-{containerId}',
  'X-Hoody-Realm': 'global',
  realm: 'global',
});

DELETE /api/v1/agent/jobs/{id}

Cancels a PENDING/RUNNING async job, or deletes a TERMINAL (succeeded / failed / canceled) job’s immutable historical record — the kit /jobs convention.

A pending or running job transitions to canceled and its work is stopped at the source:

• A sessionless run (headless / long tool call) has its bounded context cancelled; the daemon honors the cancelled context.
• A session dispatch / workflow turn is stopped via session.cancel; the active turn is cancelled, the session and its background tasks are spared.

A terminal job’s record is removed. The endpoint returns 200 {"status":"ok","canceled":true} on a cancel and 200 {"status":"ok","deleted":true} on a terminal-record delete. Returns 404 when the job id is unknown. The cancel is authoritative — a late terminator never flips a canceled job back to succeeded / failed.

Caution

An in-flight answer:assist job is NOT independently cancellable. The daemon helper is bound to the question lifecycle with no per-assist cancel on the wire. DELETE returns 409 job_not_cancellable rather than falsely reporting a cancel. Let it complete, or cancel it indirectly by answering the question or cancelling the session turn (POST /sessions/{id}/cancel).

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent).

Response

200

{
  "status": "ok",
  "canceled": true
}

400

{
  "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 realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
forbidden	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "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.

409

{
  "code": "job_not_cancellable",
  "message": "this job is not independently cancellable"
}

Error Code	Title	Description	Resolution
job_not_cancellable	Job not cancellable	This async job is not independently cancellable: an answer:assist helper runs bound to the question lifecycle and has no per-job cancel path, so the gateway cannot stop it at source.	Let it complete (its suggestion arrives on the session stream / poll the job), or cancel it indirectly by answering the question or cancelling the session turn (POST /sessions/{id}/cancel).

429

{
  "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.

500

{
  "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.

SDK Usage

cURL

curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/jobs/job_01HMZK3X4F2N9P7QY8WT6VDRAB" \
  -H "Authorization: Bearer <token>" \
  -H "X-Hoody-Cwd: /workspace/project" \
  -H "X-Hoody-Config-Dir: /home/user/.hoody" \
  -H "X-Hoody-Container: {projectId}-{containerId}" \
  -H "X-Hoody-Realm: global"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.jobs.deleteJob('job_01HMZK3X4F2N9P7QY8WT6VDRAB', {
  X-Hoody-Cwd: '/workspace/project',
  'X-Hoody-Config-Dir': '/home/user/.hoody',
  'X-Hoody-Container': '{projectId}-{containerId}',
  'X-Hoody-Realm': 'global',
  realm: 'global',
});