Cron Jobs

Cron jobs schedule recurring agent executions on a time-based trigger. Each job defines a cron expression, a target agent, and a task template that is instantiated on each run.

Base path: /api/cron-jobs

All endpoints require Authorization: Bearer <token>.

---

List Cron Jobs

GET /api/cron-jobs

Query parameters: agentName, status, limit, offset

Response:

{
  "success": true,
  "data": [
    {
      "id": "cj_01J...",
      "name": "daily-digest",
      "schedule": "0 9 * * *",
      "agentName": "digest-agent",
      "status": "active",
      "lastRunAt": "2026-04-03T09:00:00Z",
      "nextRunAt": "2026-04-04T09:00:00Z",
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 4 }
}

curl:

curl "https://api.cortex.acrobi.com/api/cron-jobs" \
  -H "Authorization: Bearer <token>"

---

Create Cron Job

POST /api/cron-jobs

Request body:

{
  "name": "daily-digest",
  "schedule": "0 9 * * *",
  "agentName": "digest-agent",
  "taskTemplate": {
    "title": "Generate daily digest for {{date}}",
    "description": "Summarize all completed tasks and agent activity from the past 24 hours",
    "priority": "medium"
  },
  "timezone": "America/New_York",
  "status": "active"
}

Field	Type	Required	Description
name	string	Yes	Human-readable job name
schedule	string	Yes	Cron expression (5-field standard format)
agentName	string	Yes	Agent to execute on each trigger
taskTemplate	object	Yes	Task fields used when creating each run's task
timezone	string	No	IANA timezone (default UTC)
status	string	No	active (default), paused

Cron expression reference:

┌──── minute (0-59)
│  ┌─── hour (0-23)
│  │  ┌── day of month (1-31)
│  │  │  ┌─ month (1-12)
│  │  │  │  ┌ day of week (0-7, 0 and 7 = Sunday)
│  │  │  │  │
*  *  *  *  *

Common schedules:

Expression	Meaning
0 9 * * *	Every day at 09:00
0 */6 * * *	Every 6 hours
0 9 * * 1	Every Monday at 09:00
*/15 * * * *	Every 15 minutes
0 9 1 * *	First of every month at 09:00

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "cj_01J...",
    "name": "daily-digest",
    "schedule": "0 9 * * *",
    "agentName": "digest-agent",
    "status": "active",
    "nextRunAt": "2026-04-04T09:00:00Z",
    "createdAt": "2026-04-03T12:00:00Z"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/cron-jobs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-digest",
    "schedule": "0 9 * * *",
    "agentName": "digest-agent",
    "taskTemplate": {
      "title": "Generate daily digest",
      "priority": "medium"
    }
  }'

---

Update Cron Job

PATCH /api/cron-jobs/:id

Partial update. Changing schedule recalculates nextRunAt immediately.

Request body:

{
  "schedule": "0 8 * * 1-5",
  "status": "active"
}

Response: 200 OK — returns updated cron job object.

curl:

curl -X PATCH "https://api.cortex.acrobi.com/api/cron-jobs/cj_01J..." \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"schedule": "0 8 * * 1-5"}'

---

Delete Cron Job

DELETE /api/cron-jobs/:id

Stops and permanently removes the cron job. In-progress runs are not interrupted.

Response:

{ "success": true }

Pausing instead of deleting

To temporarily stop a job without losing its configuration, use PATCH to set status: "paused" rather than deleting it.