Timers · Daemon API

On this page

List timers

GET/agents/{id}/timers

Operation getAgentTimersAuthBearer token

Path parameters

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

Responses

Status Description Body

200 Timers (expired ones kept as history) TimersResponse

agentIdrequired

string

Agent id

timersrequired array<Timer>

13 fields of timers

idrequired integer

schedulerequired object | object | object

3 variants of schedule

Option 1 object

2 fields of Option 1

`mode`required	string	Value `once`
`at`required	integer

Option 2 object

5 fields of Option 2

`mode`required	string	Value `interval`
`every_ms`required	integer
`start_at`	integer
`end_at`	integer
`max_runs`	integer

Option 3 object

4 fields of Option 3

`mode`required	string	Value `cron`
`cron`required	string
`end_at`	integer
`max_runs`	integer

next_wake_atrequired integer

payload string

scoperequired

array<string>

One of system, agent

lambda string

warm boolean

run_countrequired integer

created_atrequired integer

last_fired_at integer

locked boolean

loop string

expired boolean

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/timers" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Add a timer

POST/agents/{id}/timers

Operation addAgentTimerAuthBearer token

Same body as Studio's timer creation. loop names the cognition loop an agent-scope wake dispatches to (absent = main; unknown = 404): this is how an inner loop runs on a schedule. A system-scope-only timer carries no loop.

Path parameters

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

Request bodyapplication/json · TimerMutationBody · required

Field	Type	Description
`mode`required	string	One of `once_at`, `once_delay`, `interval`, `cron`
`at`	integer	once_at: epoch ms
`delay_ms`	integer	once_delay
`every_ms`	integer	interval
`start_at`	integer
`end_at`	integer
`max_runs`	integer
`cron`	string	cron
`scope`	array<string>	One of `system`, `agent`
`lambda`	string
`warm`	boolean
`payload`	string
`locked`	boolean
`loop`	string	Cognition loop the agent-scope wake targets. Create: absent = main. Update: moves the timer (`main` moves it back); absent keeps its loop.

Responses

Status Description Body

200 Created TimerCreateResponse

`agentId`required	string	Agent id
`success`required	boolean	Value `true`
`id`required	integer

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/timers" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "interval",
  "every_ms": 3600000,
  "scope": [
    "agent"
  ],
  "payload": "hourly check-in"
}'

Replace a timer's schedule and target

PUT/agents/{id}/timers/{timerId}

Operation updateAgentTimerAuthBearer token

Same body as creation. With loop the timer moves to that loop in place (same id; "main" moves it back; unknown loop 404); without loop it keeps its loop.

Path parameters

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

Request bodyapplication/json · TimerMutationBody · required

Fields as in TimerMutationBody above.

Responses

Status Description Body

200 success is false when no such timer AgentSuccess

`agentId`required	string	Agent id
`success`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 PUT "http://127.0.0.1:7385/agents/agent-1/timers/3" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "interval",
  "every_ms": 3600000,
  "scope": [
    "agent"
  ],
  "payload": "hourly check-in"
}'

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Delete a timer

DELETE/agents/{id}/timers/{timerId}

Operation deleteAgentTimerAuthBearer token

Path parameters

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

Responses

Status Description Body

200 success is false when no such timer AgentSuccess

`agentId`required	string	Agent id
`success`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 DELETE "http://127.0.0.1:7385/agents/agent-1/timers/3" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Response 200

{
  "agentId": "Xk3v9QpLm2",
  "success": true
}