Tasks & approvals · Daemon API

On this page

List tasks and approvals

GET/agents/{id}/tasks

Operation getAgentTasksAuthBearer token

limit default 200 (clamped 1–1000). pending_approval rows carry the live Always-approve affordance (canAlwaysApprove, alwaysApproveBlockedReason), derived from the executor holding the request and never persisted.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Query parameters

Name	Type	Description
`status`	string	Only this status One of `pending`, `pending_approval`, `running`, `completed`, `failed`, `denied`, `cancelled`
`limit`	integer	Maximum rows to return

Responses

Status Description Body

200 Tasks TasksResponse

agentIdrequired

string

Agent id

tasksrequired array<Task>

14 fields of tasks

idrequired string

toolrequired string

argsrequired

string

JSON text of the tool arguments

statusrequired

string

One of pending, pending_approval, running, completed, failed, denied, cancelled

result string

error string

created_atrequired integer

completed_at integer

origin string

requires_authorization boolean

executor_managed boolean

approval_meta object

2 fields of approval_meta

reasonrequired

string

One of restricted, protection

protection object

4 fields of protection

`kind`required	string
`target`required	string
`level`required	string
`description`	string

canAlwaysApprove

boolean

pending_approval rows: whether POST …/always-approve would be accepted

alwaysApproveBlockedReason

string

Why canAlwaysApprove is false

Errors 400 · 401 · 403 · 404

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/tasks" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Read one task

GET/agents/{id}/tasks/{taskId}

Operation getAgentTaskAuthBearer token

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`taskId`required	string	Task id (GET …/tasks)

Responses

Status Description Body

200 Task TaskResponse

agentIdrequired

string

Agent id

taskrequired object

14 fields of task · Task

idrequired string

toolrequired string

argsrequired

string

JSON text of the tool arguments

statusrequired

string

One of pending, pending_approval, running, completed, failed, denied, cancelled

result string

error string

created_atrequired integer

completed_at integer

origin string

requires_authorization boolean

executor_managed boolean

approval_meta object

2 fields of approval_meta

reasonrequired

string

One of restricted, protection

protection object

4 fields of protection

`kind`required	string
`target`required	string
`level`required	string
`description`	string

canAlwaysApprove

boolean

pending_approval rows: whether POST …/always-approve would be accepted

alwaysApproveBlockedReason

string

Why canAlwaysApprove is false

Errors 401 · 403 · 404

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/tasks/TASK_ID" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Approve or deny a pending task

POST/agents/{id}/tasks/{taskId}/resolve

Operation resolveAgentTaskAuthBearer token

approve lets it run (optionally with modifiedArgs); deny refuses it: reason is stored as the task's error and handed back to the agent as the owner's feedback (a blocking call's tool result reads Tool call "<tool>" was rejected by authorizer. Feedback: <reason>); pending_approval marks a pending task as awaiting approval. Only pending / pending_approval tasks resolve; others answer 409. At load the runtime sweeps orphans from a crash: running tasks become failed and the executor's own pending_approval tasks cancelled, so resolving one of those is a 409. Requests parked by an inner loop are answered on that loop's executor.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`taskId`required	string	Task id (GET …/tasks)

Request bodyapplication/json · TaskResolveBody · required

Field	Type	Description
`action`required	string	One of `approve`, `deny`, `pending_approval`
`reason`	string	On deny: stored as the task error and handed back to the agent as the owner's feedback
`modifiedArgs`	object	Approve with these arguments instead (alias: modified_args)
`modified_args`	object

Responses

Status Description Body

200 Resolved TaskResolutionResponse

agentIdrequired

string

Agent id

taskIdrequired string

resolutionrequired

any

What the executor or task store returned

taskrequired Task | null

14 fields of task

idrequired string

toolrequired string

argsrequired

string

JSON text of the tool arguments

statusrequired

string

One of pending, pending_approval, running, completed, failed, denied, cancelled

result string

error string

created_atrequired integer

completed_at integer

origin string

requires_authorization boolean

executor_managed boolean

approval_meta object

2 fields of approval_meta

reasonrequired

string

One of restricted, protection

protection object

4 fields of protection

`kind`required	string
`target`required	string
`level`required	string
`description`	string

canAlwaysApprove

boolean

pending_approval rows: whether POST …/always-approve would be accepted

alwaysApproveBlockedReason

string

Why canAlwaysApprove is false

Errors 400 · 401 · 403 · 404 · 409 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	The resource is in a state that does not allow this now
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/agents/agent-1/tasks/TASK_ID/resolve" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"approve"}'

Always approve: un-restrict the tool and approve the request

POST/agents/{id}/tasks/{taskId}/always-approve

Operation alwaysApproveAgentTaskAuthBearer token

Studio's Approve ▸ Always approve. The host tool declaration (taken from the pending request, never the client) becomes enabled and unrestricted, persisted like PUT …/config; then the request is approved. 409 for protection overrides, one-shot approvals, locked declarations or a request no executor holds. No body.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`taskId`required	string	Task id (GET …/tasks)

Responses

Status Description Body

200 Approved TaskAlwaysApproveResponse

agentIdrequired

string

Agent id

taskIdrequired string

looprequired

string

Loop whose executor held the request

toolrequired

string

Tool whose host declaration was un-restricted

resolutionrequired any

taskrequired Task | null

14 fields of task

idrequired string

toolrequired string

argsrequired

string

JSON text of the tool arguments

statusrequired

string

One of pending, pending_approval, running, completed, failed, denied, cancelled

result string

error string

created_atrequired integer

completed_at integer

origin string

requires_authorization boolean

executor_managed boolean

approval_meta object

2 fields of approval_meta

reasonrequired

string

One of restricted, protection

protection object

4 fields of protection

`kind`required	string
`target`required	string
`level`required	string
`description`	string

canAlwaysApprove

boolean

pending_approval rows: whether POST …/always-approve would be accepted

alwaysApproveBlockedReason

string

Why canAlwaysApprove is false

Errors 401 · 403 · 404 · 409 · 500

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	The resource is in a state that does not allow this now
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/agents/agent-1/tasks/TASK_ID/always-approve" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Approve every pending gated approval

POST/agents/{id}/tasks/approve-all

Operation approveAllAgentTasksAuthBearer token

Studio's Approve all: main and every running inner loop (or only loop, from the body or query). Protection overrides are never approved; they are counted in skippedProtection.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Query parameters

Name	Type	Description
`loop`	string	Cognition loop to address. Absent = main. Unknown loops answer 404.

Request bodyapplication/json · ApproveAllBody · optional

Field	Type	Description
`loop`	string	Only this loop's approvals

Responses

Status Description Body

200 Counts ApproveAllResponse

`agentId`required	string	Agent id
`loop`	string
`approved`required	integer
`skippedProtection`required	integer

Errors 400 · 401 · 403 · 404 · 409 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	The resource is in a state that does not allow this now
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/agents/agent-1/tasks/approve-all" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "approved": 2,
  "skippedProtection": 1
}

List pending ask requests

GET/agents/{id}/asks

Operation getAgentAsksAuthBearer token

Every loop's (main and each running inner loop); loop names the loop whose turn is waiting.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Asks AsksResponse

agentIdrequired

string

Agent id

asksrequired array<object>

3 fields of asks

`requestId`required	string
`question`required	string
`loop`required	string	The loop waiting on the answer

Errors 401 · 403 · 404

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/asks" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Answer an ask request

POST/agents/{id}/asks/{requestId}/respond

Operation answerAgentAskAuthBearer token

Request ids are numbered per loop: pass the loop from GET …/asks when two loops ask at once; without it the first loop holding the id is answered. An id no loop holds (already answered, or never asked) answers 404 ask_not_found.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`requestId`required	string	Ask request id (GET …/asks)

Request bodyapplication/json · AskRespondBody · required

Field	Type	Description
`answer`required	string
`loop`	string	The loop that asked (GET …/asks lists it); absent = the first loop holding the id

Responses

Status Description Body

200 answered is false when no loop held the request AskRespondResponse

`agentId`required	string	Agent id
`requestId`required	string
`loop`required	string
`answered`required	boolean

Errors 400 · 401 · 403 · 404 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (`not_found`), or no loop holds this ask (`ask_not_found`)`ask_not_foundnot_found`
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/agents/agent-1/asks/REQUEST_ID/respond" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"answer":"Yes, go ahead."}'

Resume or stop after a suspend prompt

POST/agents/{id}/suspend/respond

Operation respondAgentSuspendAuthBearer token

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Request bodyapplication/json · SuspendRespondBody · required

Field	Type	Description
`resume`required	boolean

Responses

Status Description Body

200 Resolved SuspendRespondResponse

`agentId`required	string	Agent id
`resume`required	boolean
`resolved`required	boolean

Errors 400 · 401 · 403 · 404 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/agents/agent-1/suspend/respond" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resume":true}'