API reference · v1

Six endpoints. That's the API.

Base URL https://supercrontab.com/v1. Authenticate with Authorization: Bearer <token>. Tokens are made on the account page and can be scoped read-only. All bodies are JSON. Rate limit is 600 requests per minute per token; the remaining count is in X-RateLimit-Remaining.

GET/jobs

List jobs

Every job on the account, paginated 100 at a time.

Field	Type	Notes
cursor	string	from previous response
status	enum	active \| paused

Request

curl https://supercrontab.com/v1/jobs \
  -H "Authorization: Bearer tk_live_..."

Response 200

{
  "data": [{
    "id": "job_8f2k1abcd0ef",
    "name": "Warm homepage cache",
    "url": "https://shop.example.com/cron/warm",
    "method": "GET",
    "schedule": "*/5 * * * *",
    "timezone": "UTC",
    "status": "active",
    "next_run_at": "2026-09-16T09:05:00Z"
  }],
  "next_cursor": null
}

POST/jobs

Create a job

Returns the job with its first next_run_at. Fails with 422 if the schedule is shorter than your plan allows.

Field	Type	Notes
name	string	required
url	string	https only
schedule	string	5-field cron
timezone	string	IANA, default UTC
method	enum	GET \| POST \| PUT \| DELETE
headers, body	object, string	optional
notify	object	email \| webhook
auth	object	none \| basic \| bearer \| api_key \| oauth2_cc \| hmac

Request

curl -X POST https://supercrontab.com/v1/jobs \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly invoice export",
    "url": "https://api.example.com/tasks/export",
    "method": "POST",
    "schedule": "0 2 * * *",
    "timezone": "Europe/Berlin",
    "auth": { "type": "bearer", "token": "tk_..." },
    "notify": { "webhook": "https://hooks.example.com/sc" }
  }'

Response 201

{
  "id": "job_9a1zzq7r2m4n",
  "status": "active",
  "next_run_at": "2026-09-17T00:00:00Z"
}

GET/jobs/{id}/runs

Run history

Executions newest first, with status, timing and the stored response.

Field	Type	Notes
since	ISO-8601	optional
status	enum	ok \| failed

Request

curl "https://supercrontab.com/v1/jobs/job_8f2k1abcd0ef/runs?status=failed" \
  -H "Authorization: Bearer tk_live_..."

Response 200

{
  "data": [{
    "id": "run_01j8xk3m9p2q",
    "started_at": "2026-09-16T08:55:00Z",
    "duration_ms": 30000,
    "status": "failed",
    "http_status": null,
    "error": "timeout",
    "attempts": 3,
    "response_body": ""
  }],
  "next_cursor": null
}

POST/jobs/{id}/run

Run now

Queues an immediate execution outside the schedule. Idempotent within 5 seconds.

Field	Type	Notes
none		no body

Request

curl -X POST https://supercrontab.com/v1/jobs/job_8f2k1abcd0ef/run \
  -H "Authorization: Bearer tk_live_..."

Response 202

{ "run_id": "run_01j8yq2w8c5d", "status": "queued" }

Authentication for jobs

Pass auth when creating a job and Supercrontab attaches the credentials on every call. Secrets are encrypted at rest and never returned: reads show ••••••••. Send the masked value back to keep it.

basic: Authorization: Basic base64(u:p)

{ "type": "basic", "username": "u", "password": "p" }

bearer: Authorization: Bearer ...

{ "type": "bearer", "token": "..." }

api_key: in = header | query

{ "type": "api_key", "in": "header", "name": "X-Api-Key", "value": "..." }

oauth2_cc: Client credentials grant; the token is cached until it expires

{ "type": "oauth2_cc", "tokenUrl": "https://auth.example.com/token", "clientId": "...", "clientSecret": "...", "scope": "read" }

hmac: HMAC-SHA256 of the raw body, hex

{ "type": "hmac", "secret": "...", "header": "X-Signature", "prefix": "sha256=" }

POST/endpoints

Create a mock endpoint

Returns the endpoint with its URL, served at {slug}.supercrontab.com. Limits are per account: Free 3 endpoints, 30 requests a minute and 500 a day; Pro 25, 300/min, 10,000/day; Team 100, 1,000/min, 50,000/day. Over the limit the endpoint answers 429 with Retry-After.

Field	Type	Notes
name	string	required
methods	string	ANY or GET,POST,...
status_code	int	default 200
content_type	string	default application/json
body	string	up to 64 KB
response_headers	object	optional
delay_ms, error_rate, error_status	int	optional
auth	object	inbound auth: basic \| bearer \| api_key \| hmac
log_requests	bool	default true

Request

curl -X POST https://supercrontab.com/v1/endpoints \
  -H "Authorization: Bearer tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Order webhook", "status_code": 202, "body": "{\"received\":true}", "auth": { "type": "bearer", "token": "s3cret" } }'

Response 201

{
  "data": {
    "id": "ep_7hx2k9q4m1p3",
    "slug": "kq7mx2p9tz",
    "url": "https://kq7mx2p9tz.supercrontab.com/",
    "status_code": 202,
    "auth": { "type": "bearer", "token": "••••••••" }
  }
}

GET/endpoints/{id}/requests

Request log

Requests received by the endpoint, newest first. Authorization, Cookie and API key headers are redacted.

Field	Type	Notes
cursor	string	from previous response

Request

curl https://supercrontab.com/v1/endpoints/ep_7hx2k9q4m1p3/requests \
  -H "Authorization: Bearer tk_live_..."

Response 200

{
  "data": [{
    "received_at": "2026-09-17T10:12:03Z",
    "method": "POST",
    "path": "/",
    "headers": { "content-type": "application/json", "authorization": "[redacted]" },
    "body": "{\"order\":42}",
    "status": 202
  }],
  "next_cursor": null
}

Webhook on failure

Set notify.webhook on a job and we POST this after the third failed retry, and again once the job recovers. Signed with HMAC-SHA256 in X-Supercrontab-Signature.

POST https://hooks.example.com/sc
X-Supercrontab-Signature: sha256=3f1c...

{
  "event": "job.failed",
  "job": { "id": "job_8f2k1abcd0ef", "name": "Warm homepage cache" },
  "run": { "id": "run_01j8xk3m9p2q", "http_status": 504, "duration_ms": 30000, "attempts": 3 },
  "response_excerpt": "<html>504 Gateway Time-out</html>",
  "dashboard_url": "https://supercrontab.com/dashboard"
}