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

MethodPathDescription
GET/meYour 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/activityChanges and who made them: you in the app, an API token, an AI agent, or Cronit itself (?job_id=).
POST/schedule/previewCheck a schedule without saving: plain English, next 5 runs, runs a month, whether it fits your plan.
POST/test-requestSend a request once, as a job would, without saving it or using monthly runs. Write access.
GET/jobsList your jobs, 50 per page (?page=, ?per_page= up to 100, ?folder_id=, ?status=enabled|disabled|failing, ?search=).
POST/jobsCreate 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}/runCall the job's URL now and return the execution. Does not count toward failure alerts.
GET/jobs/{id}/executionsRun 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/foldersList your folders.
POST/foldersCreate 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).

FieldTypeDescription
titlestringUp to 120 characters.
descriptionstringOptional notes.
enabledbooleanDefault true. Switching a job back on resets its failure count.
folder_idintegerOne of your folders, or null.
urlstringPublic http:// or https:// URL. Private and local addresses are refused.
methodstringGET (default), POST, PUT, PATCH, DELETE, HEAD or OPTIONS.
headersarray or objectList of {"name": "…", "value": "…"}, or an object {"Name": "value"}; up to 30.
bodystringRequest 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_passwordstringHTTP basic authentication. The password is never returned; has_auth_password tells whether one is set.
timeoutintegerSeconds to wait for the response, 1 to 30. Default 30.
redirect_successbooleanRedirects are not followed. When true, a 3xx response counts as a success.
save_responsesbooleanKeep response headers and the first 64 KB of the body in the history.
schedule_typestringcron (recurring, default) or once.
cron_expressionstringFive fields: minute, hour, day of month, month, day of week. Example: */15 * * * *. @hourly, @daily, @weekly, @monthly and @yearly work too.
timezonestringIANA name such as Europe/Brussels. The schedule follows it, daylight saving time included. Default: your account's zone.
run_atstringFor once jobs: date and time of the run. Without an offset it is read in the job's time zone.
expires_atstringOptional. No runs after this date; the job is then switched off.
notify_on_failurebooleanE-mail when the job fails. Default true.
notify_failure_thresholdintegerFailed runs in a row before that e-mail, 1 to 100. Default 1.
notify_on_recoverybooleanE-mail when it works again after a failure alert.
notify_on_disablebooleanE-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

FieldDescription
statusok, 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_statusHTTP status code, when the server answered.
errorThe raw error, e.g. HTTP 401 Unauthorized.
explanationFor 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.
triggerscheduled, manual (Run now in the app) or api.
scheduled_for, started_atPlanned and actual start. jitter_ms is the difference.
duration_msTotal time of the request.
timingsMilliseconds spent on dns, connect, tls, wait (server time to first byte), receive, and the total.
response_sizeBytes received.
response_headers, response_bodyOnly 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.

Try for free