POST /api/crons

Create a recurring HTTP cron job. The job fires on the given cron expression and is immediately active unless you pass is_active: false.

Endpoint

POST /api/crons

Authentication

Pass your API token as a Bearer token. Generate one from Settings → API.

Authorization: Bearer YOUR_API_TOKEN

Request body

{
  "name": "Health Check",
  "url": "https://api.yourapp.com/health",
  "method": "GET",
  "cron_expression": "*/5 * * * *",
  "timeout_seconds": 30,
  "alert_threshold": 3
}

Parameters

Field	Type	Required	Description
name	string	Yes	Display name for the cron job
url	string	Yes	The URL to send the HTTP request to
cron_expression	string	Yes	Standard 5-field cron expression (e.g. */5 * * * *)
method	string	No	HTTP method: GET, POST, PUT, PATCH, DELETE. Defaults to POST
headers	object	No	Key-value pairs sent as request headers
payload	string	No	Raw string body sent with the request
timeout_seconds	integer	No	Request timeout in seconds (1–300). Defaults to 30
alert_threshold	integer	No	Consecutive failures before an alert fires: 1, 2, or 3
is_active	boolean	No	Whether the cron starts active. Defaults to true

Response

201 Created

{
  "id": 42,
  "name": "Health Check",
  "cron_expression": "*/5 * * * *",
  "next_run_at": "2026-02-27T14:15:00+00:00",
  "is_active": true
}

Field	Type	Description
id	integer	ID of the created cron job
name	string	Display name
cron_expression	string	The cron expression
next_run_at	string | null	ISO 8601 timestamp of the next scheduled run
is_active	boolean	Whether the cron is currently active

Error responses

401 Unauthorized — missing or invalid token

{ "error": "Missing authorization token" }

422 Unprocessable Entity — validation error

{
  "message": "A cron expression is required.",
  "errors": {
    "cron_expression": ["A cron expression is required."]
  }
}

Examples

Simple health check

Ping your health endpoint every minute:

curl -X POST https://app.recurohq.com/api/crons \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Health Check",
    "url": "https://api.yourapp.com/health",
    "method": "GET",
    "cron_expression": "* * * * *",
    "alert_threshold": 3
  }'

Nightly data sync

POST to a sync endpoint every night at 2 AM with a custom header:

curl -X POST https://app.recurohq.com/api/crons \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Sync",
    "url": "https://warehouse.internal/sync",
    "method": "POST",
    "cron_expression": "0 2 * * *",
    "headers": { "X-Sync-Source": "recuro" },
    "timeout_seconds": 120
  }'

Create inactive (paused) cron

curl -X POST https://app.recurohq.com/api/crons \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Report",
    "url": "https://reports.internal/generate",
    "cron_expression": "0 8 * * 1",
    "is_active": false
  }'