Scheduler

What it does

Creates a scheduled callback for a future time, retries delivery on a fixed cadence if it fails, and can cascade unrecoverable failures into the dead letter queue.

Endpoint

Request shape

• •callback_url: string
• •callback_payload?: object
• •fire_at: string
• •dlq_on_failure?: boolean

Example requests

Copy-pasteable examples for agents and automation.

curl -X POST https://www.agent-utils.com/v1/schedules \
  -H "x-agent-id: worker-1" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{
    "callback_url": "https://your-app.com/hooks/retry",
    "callback_payload": { "job_id": "job_42", "attempt": 1 },
    "fire_at": "2026-07-01T00:00:00Z",
    "dlq_on_failure": true
  }'

import requests

resp = requests.post(
    "https://www.agent-utils.com/v1/schedules",
    headers={
        "x-agent-id": "worker-1",
        "x-api-key": "agutil_agt_…",
        "content-type": "application/json",
    },
    json={
        "callback_url": "https://your-app.com/hooks/retry",
        "callback_payload": {"job_id": "job_42", "attempt": 1},
        "fire_at": "2026-07-01T00:00:00Z",
        "dlq_on_failure": True,
    },
)
schedule_id = resp.json()["data"]["id"]

const res = await fetch("https://www.agent-utils.com/v1/schedules", {
  method: "POST",
  headers: {
    "x-agent-id": "worker-1",
    "x-api-key": "agutil_agt_…",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    callback_url: "https://your-app.com/hooks/retry",
    callback_payload: { job_id: "job_42", attempt: 1 },
    fire_at: "2026-07-01T00:00:00Z",
    dlq_on_failure: true,
  }),
});
const { data } = await res.json();

How agents use it

When to use it

• ✓You need to defer a follow-up step until a future timestamp.
• ✓You want a callback delivery mechanism that survives process restarts.
• ✓The workflow should retry before escalating to the DLQ or a human.

When not to use it

• •The task can run immediately in the current request.
• •You need a recurring cron job rather than a one-off callback.

Failure modes

• •If the callback URL is invalid, the job will fail before it can resume.
• •If the fire time is in the past, scheduling should be rejected.
• •When retries are exhausted, the job should move to the DLQ or be surfaced to an operator.

Machine-readable summary

This JSON block is stable for crawlers, agents, and downstream documentation pipelines.

{
  "slug": "scheduler",
  "title": "Scheduler",
  "canonical": "/docs/scheduler",
  "endpoint": "POST /v1/schedules",
  "method": "POST",
  "auth": "x-agent-id + x-api-key",
  "machine_readable": true,
  "request_shape": [
    "callback_url: string",
    "callback_payload?: object",
    "fire_at: string",
    "dlq_on_failure?: boolean"
  ],
  "agent_workflows": [
    "A reminder agent schedules a callback to re-check a stalled workflow after a fixed delay.",
    "A backend worker defers delivery until a payment window opens and then continues processing.",
    "A retry coordinator uses the scheduler to re-attempt delivery before handing the task off to the DLQ."
  ],
  "failure_modes": [
    "If the callback URL is invalid, the job will fail before it can resume.",
    "If the fire time is in the past, scheduling should be rejected.",
    "When retries are exhausted, the job should move to the DLQ or be surfaced to an operator."
  ]
}

Related docs