API Docs

v1

Programmatically manage your CronBeats jobs and workspaces

Business Plan Required: Management API access requires the Business plan ($99/month). Upgrade now

Quick Navigation

→ Authentication → Rate Limits → Jobs API → Integrations API → Bulk Operations → Error Codes

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

X-API-Key: cb_your_api_key_here

Security: Never expose your API keys in client-side code or public repositories. Store them securely as environment variables.

Generate API Keys

API keys are workspace-scoped. Each workspace can have its own API keys, and only workspace owners can create and manage them. To get started:

1. Switch to the workspace you want to create an API key for
2. Navigate to Workspace → API Keys in the sidebar
3. Click "Generate New Key" and give it a descriptive name
4. Copy and save the key immediately (it's only shown once!)

Manage API Keys

Note: API keys are tied to a specific workspace. All API requests authenticate to that workspace automatically - no need for a separate workspace ID header.

Code sample

curl -X GET "https://cronbeats.com/api/v1/jobs" \
  -H "X-API-Key: cb_your_api_key_here"

<?php
$ch = curl_init('https://cronbeats.com/api/v1/jobs');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: cb_your_api_key_here',
    'X-Workspace-ID: 123'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

import requests

response = requests.get(
    'https://cronbeats.com/api/v1/jobs',
    headers={
        'X-API-Key': 'cb_your_api_key_here',
        'X-Workspace-ID': '123'
    }
)

const axios = require('axios');

const { data } = await axios.get('https://cronbeats.com/api/v1/jobs', {
  headers: {
    'X-API-Key': 'cb_your_api_key_here'
  }
});

req, _ := http.NewRequest("GET", "https://cronbeats.com/api/v1/jobs", nil)
req.Header.Set("X-API-Key", "cb_your_api_key_here")
http.DefaultClient.Do(req)

Rate Limits

Per-Workspace Limits: Rate limits apply per workspace, not per user. All API keys for a workspace share the same rate limit pool.

Per Minute

60

requests per minute per workspace

Per Day

20,000

requests per day per workspace

Response Headers

Every response includes rate limit information for both per-minute and per-day limits:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 45
X-RateLimit-Reset-Minute: 1708185600

X-RateLimit-Limit-Day: 20000
X-RateLimit-Remaining-Day: 15234
X-RateLimit-Reset-Day: 1708214400

HTTP 429 Response

When rate limit is exceeded, you'll receive:

{
  "success": false,
  "message": "Rate limit exceeded",
  "error": {
    "type": "per_minute",
    "limit": 60,
    "reset_at": "2026-02-21 15:30:00"
  }
}

Jobs API

Create, read, update, and delete monitoring jobs programmatically.

Create Job

POST /api/v1/jobs

Create a new monitoring job with schedule configuration.

Request Body

{
  "name": "Daily Database Backup",
  "expected_interval_seconds": 86400,
  "grace_seconds": 600,
  "description": "PostgreSQL backup to S3",
  "timezone": "UTC"
}

Parameters

Field	Type	Description
name	string	Job name (required, max 200 chars)
expected_interval_seconds	integer	Required. Expected interval in seconds (how often the job runs)
grace_seconds	integer	Grace period before marking as late
description	string	Optional description (max 255 chars)

Response (201 Created)

{
  "success": true,
  "data": {
    "id": 456,
    "job_key": "abc123XyZ",
    "name": "Daily Database Backup",
    "ping_url": "https://cronbeats.io/ping/abc123XyZ",
    "is_enabled": true,
    "created_at": "2026-02-20T15:42:00Z"
  }
}

Code sample

curl -X POST "https://cronbeats.com/api/v1/jobs" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Database Backup",
    "expected_interval_seconds": 86400,
    "grace_seconds": 600
  }'

<?php
$ch = curl_init('https://cronbeats.com/api/v1/jobs');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: cb_your_api_key_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Daily Database Backup',
    'expected_interval_seconds' => 86400,
    'grace_seconds' => 600
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

import requests

response = requests.post(
    'https://cronbeats.com/api/v1/jobs',
    headers={'X-API-Key': 'cb_your_api_key_here'},
    json={
        'name': 'Daily Database Backup',
        'expected_interval_seconds': 86400,
        'grace_seconds': 600
    }
)

const axios = require('axios');

await axios.post('https://cronbeats.com/api/v1/jobs', {
  name: 'Daily Database Backup',
  expected_interval_seconds: 86400,
  grace_seconds: 600
}, {
  headers: { 'X-API-Key': 'cb_your_api_key_here' }
});

body := []byte(`{"name":"Daily Database Backup","expected_interval_seconds":86400,"grace_seconds":600}`)
req, _ := http.NewRequest("POST", "https://cronbeats.com/api/v1/jobs", bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "cb_your_api_key_here")
http.DefaultClient.Do(req)

List Jobs

GET /api/v1/jobs

Retrieve all jobs in your workspace with pagination and filtering.

Query Parameters

page	Page number (default: 1)
per_page	Items per page (default: 50, max: 100)
status	Filter: all, enabled, disabled, healthy, late, down

Example Request

GET /api/v1/jobs?page=1&per_page=50&status=healthy

Code sample

curl -X GET "https://cronbeats.com/api/v1/jobs?page=1&per_page=50&status=healthy" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1"

<?php
$ch = curl_init('https://cronbeats.com/api/v1/jobs?page=1&per_page=50&status=healthy');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: cb_your_api_key_here',
    'X-Workspace-ID: 1'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

import requests

response = requests.get(
    'https://cronbeats.com/api/v1/jobs',
    params={'page': 1, 'per_page': 50, 'status': 'healthy'},
    headers={
        'X-API-Key': 'cb_your_api_key_here',
        'X-Workspace-ID': '1'
    }
)

const axios = require('axios');

await axios.get('https://cronbeats.com/api/v1/jobs', {
  params: { page: 1, per_page: 50, status: 'healthy' },
  headers: {
    'X-API-Key': 'cb_your_api_key_here',
    'X-Workspace-ID': '1'
  }
});

req, _ := http.NewRequest("GET", "https://cronbeats.com/api/v1/jobs?page=1&per_page=50&status=healthy", nil)
req.Header.Set("X-API-Key", "cb_your_api_key_here")
req.Header.Set("X-Workspace-ID", "1")
http.DefaultClient.Do(req)

GET /api/v1/jobs/{id}

Get job details including current state

PUT /api/v1/jobs/{id}/update

Update job configuration

POST /api/v1/jobs/{id}/delete

Delete job (soft delete)

POST /api/v1/jobs/{id}/pause

Pause job monitoring

POST /api/v1/jobs/{id}/resume

Resume job monitoring

GET /api/v1/jobs/{id}/signals

Get signal/ping history

Integrations API

Configure and test notification integrations for your workspace.

GET /api/v1/integrations

List all integrations

PUT /api/v1/integrations/slack

Configure Slack integration

PUT /api/v1/integrations/discord

Configure Discord integration

PUT /api/v1/integrations/telegram

Configure Telegram integration

PUT /api/v1/integrations/webhook

Configure custom webhook

POST /api/v1/integrations/{type}/test

Test integration (slack/discord/telegram/webhook)

GET /api/v1/integrations/alert-rules

Get alert rules

PUT /api/v1/integrations/alert-rules

Update alert rules

List integrations — Code sample

curl -X GET "https://cronbeats.com/api/v1/integrations" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1"

<?php
$ch = curl_init('https://cronbeats.com/api/v1/integrations');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: cb_your_api_key_here',
    'X-Workspace-ID: 1'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

import requests

response = requests.get(
    'https://cronbeats.com/api/v1/integrations',
    headers={
        'X-API-Key': 'cb_your_api_key_here',
        'X-Workspace-ID': '1'
    }
)

const axios = require('axios');

await axios.get('https://cronbeats.com/api/v1/integrations', {
  headers: {
    'X-API-Key': 'cb_your_api_key_here',
    'X-Workspace-ID': '1'
  }
});

req, _ := http.NewRequest("GET", "https://cronbeats.com/api/v1/integrations", nil)
req.Header.Set("X-API-Key", "cb_your_api_key_here")
req.Header.Set("X-Workspace-ID", "1")
http.DefaultClient.Do(req)

Configure Slack

PUT /api/v1/integrations/slack — Set or update the Slack webhook. Requires workspace owner or admin.

Request body (JSON):

Field	Type	Description
webhook_url	string	Slack Incoming Webhook URL (from Slack App). Empty to clear.
is_enabled	boolean	Turn notifications on (true) or off (false).

curl -X PUT "https://cronbeats.com/api/v1/integrations/slack" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://hooks.slack.com/services/...", "is_enabled": true}'

Configure Discord

PUT /api/v1/integrations/discord — Set or update the Discord webhook. Requires workspace owner or admin.

Request body (JSON):

Field	Type	Description
webhook_url	string	Discord channel Webhook URL (Server Settings → Integrations → Webhooks). Empty to clear.
is_enabled	boolean	Turn notifications on (true) or off (false).

curl -X PUT "https://cronbeats.com/api/v1/integrations/discord" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://discord.com/api/webhooks/...", "is_enabled": true}'

Configure Telegram

PUT /api/v1/integrations/telegram — Set or update the Telegram bot and chat. Requires workspace owner or admin.

Request body (JSON):

Field	Type	Description
bot_token	string	Bot token from @BotFather. Empty to clear.
chat_id	string	Chat or group ID (e.g. from @userinfobot or group URL). Empty to clear.
is_enabled	boolean	Turn notifications on (true) or off (false).

curl -X PUT "https://cronbeats.com/api/v1/integrations/telegram" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{"bot_token": "123456:ABC...", "chat_id": "123456789", "is_enabled": true}'

Configure Custom Webhook

PUT /api/v1/integrations/webhook — Set or update a custom HTTP webhook URL. Requires workspace owner or admin.

Request body (JSON):

Field	Type	Description
url	string	Your endpoint URL (HTTPS). Empty to clear.
secret	string	Optional secret for request signing (e.g. X-Webhook-Signature header). Max 64 chars.
is_enabled	boolean	Turn notifications on (true) or off (false).

curl -X PUT "https://cronbeats.com/api/v1/integrations/webhook" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/alerts", "secret": "your-secret", "is_enabled": true}'

Test an integration

POST /api/v1/integrations/{type}/test — Sends a test message. Replace {type} with slack, discord, telegram, or webhook. No request body.

curl -X POST "https://cronbeats.com/api/v1/integrations/slack/test" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1"

Alert rules

GET /api/v1/integrations/alert-rules — Returns current rules. PUT to the same path to update. Requires workspace owner or admin for PUT.

PUT request body (JSON) — all fields optional:

Field	Type	Description
alert_on_down	boolean	Notify when a job is marked down.
alert_on_recovery	boolean	Notify when a job recovers from down.

curl -X PUT "https://cronbeats.com/api/v1/integrations/alert-rules" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "X-Workspace-ID: 1" \
  -H "Content-Type: application/json" \
  -d '{"alert_on_down": true, "alert_on_recovery": true}'

Bulk Operations

Perform operations on multiple jobs at once (max 100 jobs per request).

POST /api/v1/jobs/bulk/pause

Pause multiple jobs

POST /api/v1/jobs/bulk/resume

Resume multiple jobs

POST /api/v1/jobs/bulk/delete

Delete multiple jobs

Example Request

{
  "job_ids": [123, 456, 789]
}

Example Response

{
  "success": true,
  "data": {
    "total_requested": 3,
    "successfully_paused": 2,
    "failed": [
      {
        "id": 789,
        "error": "Job is already disabled"
      }
    ]
  }
}

Code sample — Bulk pause

curl -X POST "https://cronbeats.com/api/v1/jobs/bulk/pause" \
  -H "X-API-Key: cb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"job_ids": [123, 456]}'

<?php
$ch = curl_init('https://cronbeats.com/api/v1/jobs/bulk/pause');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: cb_your_api_key_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['job_ids' => [123, 456]]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

import requests

response = requests.post(
    'https://cronbeats.com/api/v1/jobs/bulk/pause',
    headers={'X-API-Key': 'cb_your_api_key_here'},
    json={'job_ids': [123, 456]}
)

const axios = require('axios');

await axios.post('https://cronbeats.com/api/v1/jobs/bulk/pause', { job_ids: [123, 456] }, {
  headers: { 'X-API-Key': 'cb_your_api_key_here' }
});

body := []byte(`{"job_ids":[123,456]}`)
req, _ := http.NewRequest("POST", "https://cronbeats.com/api/v1/jobs/bulk/pause", bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "cb_your_api_key_here")
http.DefaultClient.Do(req)

Error Handling

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request (invalid input)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient permissions)
404	Not Found
422	Validation Error
429	Rate Limit Exceeded

Error Response Format

{
  "success": false,
  "error": "invalid_api_key",
  "message": "Invalid or expired API key",
  "meta": {
    "timestamp": "2026-02-20T15:42:00Z"
  }
}

Get Started with the API

Generate API Key Create your first workspace API key Upgrade Plan Get Business plan access Read Guides Learn the basics