Cron API Reference

All endpoints are on the public API (https://api.universalapi.co) and require authentication with a Bearer token (uapi_ut_* or your Cognito session token).

All responses use the standard envelope:

{
  "data": { ... },
  "requestId": "...",
  "rootRequestId": "...",
  "parentRequestId": null
}

Create Cron Job

POST /cron

Request Body

Field	Type	Required	Description
name	string	Yes	Display name for the cron job (e.g. daily-report)
agentId	string	Yes	UUID of the agent to invoke on each run
schedule	string	Yes	rate(N unit) or cron(min hr dom mon dow yr) expression
scheduleTimezone	string	No	IANA timezone for cron expressions (default: UTC)
inputMessage	string	No	Prompt sent to the agent on each run
agentName	string	No	Agent display name (for reference in listings)

Example

curl -X POST https://api.universalapi.co/cron \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-report",
    "agentId": "agent-uuid",
    "schedule": "cron(0 9 * * ? *)",
    "scheduleTimezone": "America/New_York",
    "inputMessage": "Generate the daily report."
  }'

Response

{
  "data": {
    "cronId": "uuid",
    "name": "daily-report",
    "agentId": "agent-uuid",
    "schedule": "cron(0 9 * * ? *)",
    "scheduleTimezone": "America/New_York",
    "inputMessage": "Generate the daily report.",
    "status": "active",
    "consecutiveFailures": 0,
    "createdAt": "2026-06-11T12:00:00Z"
  }
}

Errors

Status	Cause
400	Missing name, agentId, or schedule; invalid schedule expression
400	Cron job limit reached (20 per user)
401	Missing or invalid Bearer token

List Cron Jobs

GET /cron

Returns all cron jobs for the authenticated user.

curl https://api.universalapi.co/cron \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN"

Response

{
  "data": {
    "crons": [
      {
        "cronId": "uuid",
        "name": "daily-report",
        "agentId": "agent-uuid",
        "schedule": "cron(0 9 * * ? *)",
        "scheduleTimezone": "America/New_York",
        "status": "active",
        "lastRunAt": "2026-06-11T13:00:02Z",
        "lastRunStatus": "success",
        "lastRunError": "",
        "consecutiveFailures": 0
      }
    ],
    "count": 1
  }
}

Get Cron Job

GET /cron/{cronId}

Returns full details for a single cron job, including last run info and failure count.

curl https://api.universalapi.co/cron/CRON_ID \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN"

Update Cron Job

PUT /cron/{cronId}

Only include fields you want to change. Updating schedule or scheduleTimezone rewrites the underlying EventBridge schedule. Setting status to active from paused or error resets consecutiveFailures to 0 and re-enables the schedule.

Request Body (all optional)

Field	Type	Description
name	string	New display name
agentId	string	New target agent UUID
schedule	string	New schedule expression
scheduleTimezone	string	New timezone
inputMessage	string	New prompt
status	string	active (resume) or paused (pause)

Example — Pause

curl -X PUT https://api.universalapi.co/cron/CRON_ID \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

Example — Change Schedule

curl -X PUT https://api.universalapi.co/cron/CRON_ID \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schedule": "rate(6 hours)"}'

Delete Cron Job

DELETE /cron/{cronId}

Permanently deletes the cron job and its EventBridge schedule. This cannot be undone.

curl -X DELETE https://api.universalapi.co/cron/CRON_ID \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN"

Field Reference

Field	Type	Description
cronId	string	Unique cron job ID
name	string	Display name
agentId	string	Target agent UUID
agentName	string	Agent display name (informational)
schedule	string	EventBridge schedule expression
scheduleTimezone	string	IANA timezone (cron expressions only)
inputMessage	string	Prompt sent to agent each run
status	string	active | paused | error
lastRunAt	string	ISO timestamp of last execution
lastRunStatus	string	success | error
lastRunError	string	Error message from last failed run
consecutiveFailures	number	Failures since last success; 3 → auto-pause
createdAt	string	ISO creation timestamp

See Also

• Scheduled Agents Overview — concepts, schedule formats, patterns
• Agents API Reference — the chat endpoint cron invokes