The Schedule Management API lets you list every registered @schedule directive, trigger an immediate fire, reload registrations from disk, and inspect the recent fire history recorded in fires.log. Use these endpoints to operationalize cron-style workloads in Hoody — for example, to surface upcoming jobs in dashboards, run one-off ad-hoc fires for testing, or recover after editing @schedule directives without restarting the worker.

List Schedules

GET /api/v1/exec/schedules/list

Returns every currently registered @schedule directive with computed next-fire timestamps and last-fire metadata.

This endpoint takes no parameters.

cURL

curl -X GET https://api.example.com/api/v1/exec/schedules/list \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.schedules.listSchedules();

200

{
  "total": 2,
  "schedules": [
    {
      "scriptPath": "/srv/scripts/default/jobs/cleanup.ts",
      "scriptRel": "default/jobs/cleanup.ts",
      "subdomain": "default",
      "execId": null,
      "vmCacheKey": "default:jobs/cleanup.ts",
      "expression": "@hourly",
      "timeoutMs": 30000,
      "registeredAt": "2026-01-15T10:00:00.000Z",
      "nextFire": "2026-01-15T11:00:00.000Z",
      "lastFireAt": "2026-01-15T10:00:00.420Z",
      "lastFireStatus": "ok",
      "lastFireRunId": "7c1f4e2a-9b3d-4f0e-8a11-2c5e7a9f1b22"
    },
    {
      "scriptPath": "/srv/scripts/default/jobs/nightly-report.ts",
      "scriptRel": "default/jobs/nightly-report.ts",
      "subdomain": "default",
      "execId": null,
      "vmCacheKey": "default:jobs/nightly-report.ts",
      "expression": "0 2 * * *",
      "timeoutMs": 0,
      "registeredAt": "2026-01-15T09:55:11.000Z",
      "nextFire": "2026-01-16T02:00:00.000Z",
      "lastFireAt": null,
      "lastFireStatus": null,
      "lastFireRunId": null
    }
  ]
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

503

{
  "error": "Scheduler not ready",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Schedule History

GET /api/v1/exec/schedules/history

Reads newest-first NDJSON entries from fires.log, returning per-fire completion records with status, duration, and error previews.

Parameters

Name	In	Type	Required	Description
scriptPath	query	string	No	Filter entries to a specific script (relative to scripts-dir). Optional.
since	query	string	No	ISO 8601 lower bound on ts. Optional.
limit	query	integer	No	Max entries to return. Default 100, hard max 1000.
includeRotated	query	boolean	No	When true, also scan rotated fires.log.* files (slower).

cURL

curl -X GET "https://api.example.com/api/v1/exec/schedules/history?scriptPath=default/jobs/cleanup.ts&limit=50" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.schedules.scheduleHistory({
  scriptPath: "default/jobs/cleanup.ts",
  limit: 50
});

200

{
  "total": 2,
  "limit": 50,
  "includeRotated": false,
  "entries": [
    {
      "ts": "2026-01-15T10:00:00.420Z",
      "scriptPath": "default/jobs/cleanup.ts",
      "expression": "@hourly",
      "runId": "7c1f4e2a-9b3d-4f0e-8a11-2c5e7a9f1b22",
      "status": "ok",
      "durationMs": 412,
      "returnPreview": "{\"rowsAffected\":3}"
    },
    {
      "ts": "2026-01-15T09:00:00.398Z",
      "scriptPath": "default/jobs/cleanup.ts",
      "expression": "@hourly",
      "runId": "1a8b3c0d-2e4f-4a55-bb71-9d2f0e6c1a44",
      "status": "error",
      "durationMs": 87,
      "error": "TypeError: Cannot read properties of undefined (reading 'id')"
    }
  ]
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

503

{
  "error": "History log unavailable",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Note

The entries array is capped at the resolved limit. The returnPreview field is only present when status is ok, and error is present for error, timeout, load_error, and incompatible outcomes.

Reload Schedules

POST /api/v1/exec/schedules/reload

Re-scans the scripts directory and reconciles the live schedule registry against the current filesystem. Returns a diff describing what was added, kept, removed, and failed.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
dry_run	boolean	No	false	When true, compute the diff against the filesystem but do not apply. Returns the same shape with added, kept, and removed lists.

cURL

curl -X POST https://api.example.com/api/v1/exec/schedules/reload \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "dry_run": true }'

SDK

const result = await client.exec.schedules.reloadSchedules({
  dry_run: true
});

200

{
  "dry_run": true,
  "added": ["default/jobs/cleanup.ts", "default/jobs/nightly-report.ts"],
  "kept": ["default/jobs/healthcheck.ts"],
  "removed": ["legacy/jobs/old-sync.ts"],
  "failed": [
    {
      "path": "default/jobs/stream-and-cron.ts",
      "reason": "@websocket and @schedule cannot coexist on the same script"
    }
  ]
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

503

{
  "error": "Scheduler not ready",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Tip

Run a dry_run reload first when editing multiple @schedule directives — the failed array is populated in both dry-run and apply responses, so you can spot bad cron expressions or @websocket + @schedule conflicts before they hit production.

Trigger Schedule

POST /api/v1/exec/schedules/trigger

Fires a registered @schedule script immediately, returning the outcome without waiting for the next cron tick.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Description
scriptPath	string	Yes	Script path (absolute or relative to scripts-dir) of a script with a valid @schedule directive.
force	boolean	No	When true, bypass the @token refusal. Use with care — this fires the script as cron (no token auth).

cURL

curl -X POST https://api.example.com/api/v1/exec/schedules/trigger \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "scriptPath": "default/jobs/cleanup.ts" }'

SDK

const result = await client.exec.schedules.triggerSchedule({
  scriptPath: "default/jobs/cleanup.ts"
});

200

{
  "triggered": true,
  "scriptPath": "default/jobs/cleanup.ts",
  "runId": "8d2e5f1b-7c4a-4d0e-bb22-1f3a6c9e2d55",
  "status": "ok",
  "durationMs": 388
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "ERROR_400",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

403

{
  "error": "FORBIDDEN",
  "code": "ERROR_403",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Error Code	Title	Description	Resolution
FORBIDDEN	Access denied	Insufficient permissions for this operation	Contact administrator for access

404

{
  "error": "NOT_FOUND",
  "code": "ERROR_404",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Error Code	Title	Description	Resolution
NOT_FOUND	Resource not found	The requested resource does not exist	Verify the resource identifier

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

503

{
  "error": "Scheduler not ready",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T10:05:23.000Z"
}

Caution

The triggered field is false when the fire is skipped — for example, when the in-flight cap is hit, the schedule was unregistered between trigger and fire, or the registration generation went stale. Inspect status for the precise reason (stale_generation, unregistered, skipped_overload, or scheduler_not_ready).