REST API and AI agents
Manage your cron jobs from scripts, deploy pipelines, and AI assistants such as Claude.
AI agents (MCP)
Cronit is a remote MCP server at https://cronit.app/mcp, so an AI assistant can create, check and fix your jobs for you. It explains schedules in plain English, tells you how many monthly runs a schedule needs before creating it, and explains failed runs with a fix. Everything it changes is listed under Settings → Activity.
- Claude (web and desktop): Settings → Connectors → Add custom connector, URL
https://cronit.app/mcp. You sign in to Cronit and approve access (OAuth); no token needed. - Claude Code:
claude mcp add --transport http cronit https://cronit.app/mcp --header "Authorization: Bearer YOUR_TOKEN" - Other clients: any MCP client that speaks Streamable HTTP, with OAuth 2.1 (dynamic client registration) or a token.
Tools: get_account, list_jobs, get_job, preview_schedule, test_request, create_job, update_job, set_job_enabled, run_job, list_runs, get_run, list_activity and delete_job. A short description for language models is at /llms.txt; the full API is described in /openapi.json (OpenAPI 3.1).
Authentication
Create a token in the app under Settings → API & AI agents. A token is read-only (look at jobs and runs) or read + write (also create, change, run and delete), and can expire after 7, 30, 90 or 365 days. It is shown once; keep it secret. Give every script or agent its own token, so the activity log shows who did what. Send it in the Authorization header of every request:
Authorization: Bearer YOUR_TOKEN
Accept: application/json
The base URL is https://cronit.app/api/v1. Requests and responses are JSON; send Content-Type: application/json with a body. Dates are ISO 8601 in UTC.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /me | Your account, plan, the token's access, limits, and usage: runs used this month, runs your switched-on jobs need a month, and when the runs run out at this pace. |
GET | /activity | Changes and who made them: you in the app, an API token, an AI agent, or Cronit itself (?job_id=). |
POST | /schedule/preview | Check a schedule without saving: plain English, next 5 runs, runs a month, whether it fits your plan. |
POST | /test-request | Send a request once, as a job would, without saving it or using monthly runs. Write access. |
GET | /jobs | List your jobs, 50 per page (?page=, ?per_page= up to 100, ?folder_id=, ?status=enabled|disabled|failing, ?search=). |
POST | /jobs | Create a job. Returns 201. With "dry_run": true nothing is saved and you get the validated job and its schedule preview. |
GET | /jobs/{id} | Get one job. |
PATCH | /jobs/{id} | Update some fields of a job. PUT replaces the whole job. |
DELETE | /jobs/{id} | Delete a job and its history. Returns 204. |
POST | /jobs/{id}/run | Call the job's URL now and return the execution. Does not count toward failure alerts. |
GET | /jobs/{id}/executions | Run history, newest first, plus predictions: the next 3 planned runs. |
GET | /jobs/{id}/executions/{executionId} | One run, with the saved response headers and body. |
GET | /folders | List your folders. |
POST | /folders | Create a folder: {"name": "Production"}. |
PATCH | /folders/{id} | Rename a folder. |
DELETE | /folders/{id} | Delete a folder. Its jobs are kept, without a folder. |
The job object
Send these fields to create or update a job. Only title, url and cron_expression are required (or schedule_type once with run_at).
| Field | Type | Description |
|---|---|---|
title | string | Up to 120 characters. |
description | string | Optional notes. |
enabled | boolean | Default true. Switching a job back on resets its failure count. |
folder_id | integer | One of your folders, or null. |
url | string | Public http:// or https:// URL. Private and local addresses are refused. |
method | string | GET (default), POST, PUT, PATCH, DELETE, HEAD or OPTIONS. |
headers | array or object | List of {"name": "…", "value": "…"}, or an object {"Name": "value"}; up to 30. |
body | string | Request body for POST, PUT, PATCH and DELETE. Sent as application/json when it is valid JSON, unless you set a Content-Type header. |
auth_user, auth_password | string | HTTP basic authentication. The password is never returned; has_auth_password tells whether one is set. |
timeout | integer | Seconds to wait for the response, 1 to 30. Default 30. |
redirect_success | boolean | Redirects are not followed. When true, a 3xx response counts as a success. |
save_responses | boolean | Keep response headers and the first 64 KB of the body in the history. |
schedule_type | string | cron (recurring, default) or once. |
cron_expression | string | Five fields: minute, hour, day of month, month, day of week. Example: */15 * * * *. @hourly, @daily, @weekly, @monthly and @yearly work too. |
timezone | string | IANA name such as Europe/Brussels. The schedule follows it, daylight saving time included. Default: your account's zone. |
run_at | string | For once jobs: date and time of the run. Without an offset it is read in the job's time zone. |
expires_at | string | Optional. No runs after this date; the job is then switched off. |
notify_on_failure | boolean | E-mail when the job fails. Default true. |
notify_failure_threshold | integer | Failed runs in a row before that e-mail, 1 to 100. Default 1. |
notify_on_recovery | boolean | E-mail when it works again after a failure alert. |
notify_on_disable | boolean | E-mail when it is switched off after 25 failed runs in a row. |
Responses also contain these read-only fields: id, next_run_at, last_run_at, last_status, last_http_status, last_duration_ms, last_error, last_explanation (see below), consecutive_failures, disabled_reason, schedule_description (plain English, e.g. “Every Monday at 9:00am (Europe/Brussels)”), runs_per_month, badge_url, created_at and updated_at.
The execution object
| Field | Description |
|---|---|
status | ok, http_error, timeout, dns_error, connection_error, ssl_error, too_large, blocked_url, failed or quota_exceeded (skipped: the month's runs were used up). Only ok is a success: a 2xx response, or a 3xx one when redirect_success is on. |
http_status | HTTP status code, when the server answered. |
error | The raw error, e.g. HTTP 401 Unauthorized. |
explanation | For failed runs: {"code", "title", "detail", "hint"}. The hint says what to change, e.g. which header to add or which URL to use instead of a redirect. null for successful runs. |
trigger | scheduled, manual (Run now in the app) or api. |
scheduled_for, started_at | Planned and actual start. jitter_ms is the difference. |
duration_ms | Total time of the request. |
timings | Milliseconds spent on dns, connect, tls, wait (server time to first byte), receive, and the total. |
response_size | Bytes received. |
response_headers, response_body | Only on the single-execution endpoint, and only if the job saves responses. |
History is kept for 30 days.
Check before you save
Every plan includes a number of runs a month across all jobs (the Free plan: 500). Every 5 minutes is about 8,760 runs a month, hourly about 730, daily about 30. Before creating a job, preview its schedule; the answer says whether it fits:
curl https://cronit.app/api/v1/schedule/preview \
-H "Authorization: Bearer $CRONIT_TOKEN" -H "Content-Type: application/json" \
-d '{"cron_expression": "0 * * * *", "timezone": "Europe/Brussels"}'
{"data": {"description": "Once an hour (Europe/Brussels)", "runs_per_month_text": "About 730 runs a month.",
"fits_plan": false, "warnings": ["This schedule alone needs about 730 runs a month, but the Free plan includes 500. Run it less often."], …}}
Send POST /test-request with a URL (and method, headers, body) to see whether the endpoint answers, before you create the job. To make retries safe, send an Idempotency-Key header with POST requests: repeating a request with the same key within 24 hours returns the first response (with Idempotent-Replayed: true) instead of creating a second job.
Examples
Create a job
curl https://cronit.app/api/v1/jobs \
-H "Authorization: Bearer $CRONIT_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"title": "Laravel scheduler",
"url": "https://example.com/cron/schedule-run",
"method": "GET",
"headers": [{"name": "X-Cron-Token", "value": "secret"}],
"schedule_type": "cron",
"cron_expression": "*/5 * * * *",
"timezone": "Europe/Brussels"
}'
Pause a job during a deploy
curl -X PATCH https://cronit.app/api/v1/jobs/42 \
-H "Authorization: Bearer $CRONIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
Run a job now and read the result
curl -X POST https://cronit.app/api/v1/jobs/42/run \
-H "Authorization: Bearer $CRONIT_TOKEN" -H "Accept: application/json"
{"data": {"id": 1817, "status": "ok", "http_status": 200, "duration_ms": 184, …}}
Errors and limits
401: missing, expired or revoked token.403: the token is read-only and the request changes something.404: the job or folder does not exist, or is not yours.422: invalid input. The body lists the problems per field, in words that say how to fix them:{"message": "…", "errors": {"cron_expression": ["This expression has 6 fields. Cronit uses 5 …"]}}.429: too many requests. The API accepts 60 requests a minute per account, and 10 manual runs a minute.
Every job also has a public status badge at its badge_url, an SVG you can embed in a README: it only shows whether the last run passed.
Run online cronjobs without server setup
Plan, schedule and run periodic tasks and scripts, from your browser with the first online cronjob platform.