Home/API Documentation

API Documentation

Complete reference for the CronOwl REST API v1

Quick Start

1. Get your API key

Go to Settings and create a new API key in the "API Keys" section.

2. Make your first request

List all checks

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cronowl.com/api/v1/checks

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxx

Important: Keep your API keys secret. Never expose them in client-side code or public repositories.

Response Format

All responses are JSON with this structure:

Success

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid field",
    "details": { ... }
  }
}

API Keys

GET/api/v1/auth/keys

List all API keys for your account

Response

{
  "success": true,
  "data": [
    {
      "id": "abc123",
      "name": "Production",
      "prefix": "sk_live_xxxx...",
      "createdAt": "2024-01-15T10:00:00Z",
      "lastUsedAt": "2024-01-20T15:30:00Z"
    }
  ]
}

POST/api/v1/auth/keys

Create a new API key

Request body

{
  "name": "CI/CD Pipeline"
}

Response (key shown only once!)

{
  "success": true,
  "data": {
    "id": "def456",
    "name": "CI/CD Pipeline",
    "key": "sk_live_xxxxxxxxxxxxxxxxxxxx",
    "prefix": "sk_live_xxxx...",
    "createdAt": "2024-01-20T16:00:00Z"
  }
}

DELETE/api/v1/auth/keys/:id

Revoke an API key

Response

{
  "success": true,
  "data": { "revoked": true }
}

Checks

GET/api/v1/checks

List all checks with optional filtering

Query Parameters

Parameter	Description
`page`	Page number (default: 1)
`limit`	Results per page (default: 20, max: 100)
`status`	Filter by status: up, down, new
`tag`	Filter by tag

Example

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://cronowl.com/api/v1/checks?status=up&limit=10"

POST/api/v1/checks

Create a new check

Request Body

Field	Type	Description
`name`	string	Check name (required)
`schedule`	string	Preset: "every 5 minutes", "every hour", "every day", etc.
`cronExpression`	string	Cron syntax: "/5 * * *" (overrides schedule)
`timezone`	string	Timezone (default: UTC)
`gracePeriod`	number	Grace period in minutes (0-60)
`tags`	string[]	Tags for organization
`webhookUrl`	string	Webhook URL for alerts
`maxDuration`	number	Slow job threshold in milliseconds

Example

curl -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Backup",
    "cronExpression": "0 2 * * *",
    "timezone": "Europe/Moscow",
    "gracePeriod": 10,
    "tags": ["production", "critical"],
    "maxDuration": 300000
  }' \
  https://cronowl.com/api/v1/checks

GET/api/v1/checks/:id

Get a single check by ID

Response

{
  "success": true,
  "data": {
    "id": "abc123",
    "name": "Database Backup",
    "slug": "db-backup-xyz",
    "schedule": "cron",
    "scheduleType": "cron",
    "cronExpression": "0 2 * * *",
    "timezone": "Europe/Moscow",
    "gracePeriod": 10,
    "status": "up",
    "paused": false,
    "lastPing": "2024-01-20T02:00:15Z",
    "lastDuration": 45000,
    "tags": ["production", "critical"],
    "maxDuration": 300000,
    "createdAt": "2024-01-01T10:00:00Z"
  }
}

PATCH/api/v1/checks/:id

Update a check

Example - Update name and add tag

curl -X PATCH \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Daily Backup", "tags": ["prod", "db"]}' \
  https://cronowl.com/api/v1/checks/abc123

DELETE/api/v1/checks/:id

Delete a check

Response

{
  "success": true,
  "data": { "deleted": true }
}

POST/api/v1/checks/:id/pause

Pause monitoring for a check

Paused checks won't trigger down alerts even if they miss pings.

Response

{
  "success": true,
  "data": { "paused": true, "id": "abc123" }
}

POST/api/v1/checks/:id/resume

Resume monitoring for a paused check

Response

{
  "success": true,
  "data": { "paused": false, "id": "abc123" }
}

HTTP Monitors

Monitor your HTTP endpoints for availability and performance. Get alerted when your services go down or become slow.

GET/api/v1/http-monitors

List all HTTP monitors with optional filtering

Query Parameters

Parameter	Description
`page`	Page number (default: 1)
`limit`	Results per page (default: 20, max: 100)
`status`	Filter by status: up, down, degraded, pending
`tag`	Filter by tag

Example

curl -H "Authorization: Bearer sk_live_xxx" \
  "https://cronowl.com/api/v1/http-monitors?status=up"

POST/api/v1/http-monitors

Create a new HTTP monitor

Request Body

Field	Type	Description
`name`	string	Monitor name (required)
`url`	string	URL to monitor (required, https recommended)
`method`	string	HTTP method: GET, HEAD, POST, PUT (default: GET)
`expectedStatusCodes`	number[]	Expected status codes (default: [200, 201, 204])
`timeoutMs`	number	Request timeout in ms (1000-30000, default: 10000)
`intervalSeconds`	number	Check interval in seconds (plan dependent)
`headers`	object	Custom headers (sensitive values encrypted)
`body`	string	Request body for POST/PUT
`contentType`	string	Content-Type: application/json, text/plain, etc.
`assertions`	object	Response assertions (see below)
`alertAfterFailures`	number	Failures before alerting (1-10, default: 2)
`tags`	string[]	Tags for organization (max 10)
`webhookUrl`	string	Webhook URL for alerts

Assertions Object

Field	Description
`maxResponseTimeMs`	Max response time before marking as degraded
`bodyContains`	Response body must contain this string
`bodyNotContains`	Response body must NOT contain this string

Example

curl -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "url": "https://api.example.com/health",
    "method": "GET",
    "intervalSeconds": 60,
    "expectedStatusCodes": [200],
    "assertions": {
      "maxResponseTimeMs": 2000,
      "bodyContains": ""status":"ok""
    },
    "alertAfterFailures": 2,
    "tags": ["production", "api"]
  }' \
  https://cronowl.com/api/v1/http-monitors

GET/api/v1/http-monitors/:id

Get a single HTTP monitor by ID

Response

{
  "success": true,
  "data": {
    "id": "mon_abc123",
    "name": "Production API",
    "url": "https://api.example.com/health",
    "method": "GET",
    "expectedStatusCodes": [200],
    "timeoutMs": 10000,
    "intervalSeconds": 60,
    "headers": { "Authorization": "Bear****" },
    "body": "[REDACTED]",
    "status": "up",
    "lastCheckedAt": "2024-01-20T15:30:00Z",
    "lastResponseTimeMs": 145,
    "lastStatusCode": 200,
    "uptimePercent24h": 99.9,
    "avgResponseTime24h": 156,
    "isEnabled": true,
    "tags": ["production", "api"],
    "createdAt": "2024-01-01T10:00:00Z"
  }
}

PATCH/api/v1/http-monitors/:id

Update an HTTP monitor

Example - Update interval and add assertion

curl -X PATCH \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "intervalSeconds": 120,
    "assertions": { "maxResponseTimeMs": 3000 }
  }' \
  https://cronowl.com/api/v1/http-monitors/mon_abc123

DELETE/api/v1/http-monitors/:id

Delete an HTTP monitor

Response

{
  "success": true,
  "data": { "deleted": true, "id": "mon_abc123" }
}

HTTP Monitor Plan Limits

Feature	Free	Starter ($8/mo)	Pro ($19/mo)
HTTP Monitors	1	10	50
Min Check Interval	5 minutes	2 minutes	1 minute
Check History	24 hours	7 days	30 days

Ping History

GET/api/v1/checks/:id/pings

Get ping history for a check

Query Parameters

Parameter	Description
`limit`	Number of pings to return (default: 20, max: 100)

Response

{
  "success": true,
  "data": [
    {
      "id": "ping1",
      "timestamp": "2024-01-20T02:00:15Z",
      "ip": "203.0.113.50",
      "userAgent": "curl/8.0",
      "duration": 45000,
      "exitCode": 0,
      "status": "success"
    }
  ],
  "meta": {
    "checkId": "abc123",
    "checkName": "Database Backup",
    "count": 1
  }
}

GET/api/v1/checks/:id/status

Get status change history

Response

{
  "success": true,
  "data": [
    {
      "id": "event1",
      "status": "up",
      "timestamp": "2024-01-20T02:00:15Z",
      "duration": 86400
    },
    {
      "id": "event2",
      "status": "down",
      "timestamp": "2024-01-19T02:05:00Z",
      "duration": 300
    }
  ],
  "meta": {
    "checkId": "abc123",
    "checkName": "Database Backup",
    "currentStatus": "up",
    "count": 2
  }
}

Ping Endpoint

The ping endpoint is public and doesn't require authentication. Use the check's slug from the dashboard.

GET/api/ping/:slug

Send a ping to indicate your job is running

Query Parameters

Parameter	Description
`duration`	Job duration in milliseconds
`exit_code`	Exit code (0 = success)
`status`	"success" or "failure"
`output`	Job output (max 1KB)
`start`	Set to "1" to signal job start (no status change)

Examples

# Simple ping
curl https://cronowl.com/api/ping/your-slug

# With duration (for slow job detection)
curl "https://cronowl.com/api/ping/your-slug?duration=45000"

# With exit code
curl "https://cronowl.com/api/ping/your-slug?exit_code=0"

# Signal job start
curl "https://cronowl.com/api/ping/your-slug?start=1"

# Full example in bash script
START_TIME=$(date +%s%3N)
# ... your job here ...
END_TIME=$(date +%s%3N)
DURATION=$((END_TIME - START_TIME))
curl "https://cronowl.com/api/ping/your-slug?duration=$DURATION&exit_code=$?"

Testing with Postman

Create a new request in Postman
Set the method (GET, POST, etc.) and URL
Go to the Authorization tab
Select Bearer Token from the Type dropdown
Paste your API key in the Token field
For POST/PATCH requests, go to Body tab, select raw and JSON
Send your request!

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid Authorization header
`INVALID_API_KEY`	401	Invalid or revoked API key
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request data
`LIMIT_EXCEEDED`	400	Plan limit reached
`RATE_LIMIT_EXCEEDED`	429	Too many requests (60/min)
`INTERNAL_ERROR`	500	Server error

Rate Limits

• API requests: 60 requests per minute per API key
• Ping endpoint: 100 requests per minute per IP
• Maximum API keys per user: 10

Need help? Contact us at support@cronowl.com