Docs

cronservices calls HTTP endpoints on a schedule, or once at an exact time. A job pairs a schedule (a cron expression in any time zone, or a single run_at timestamp) with a chain of steps. Each step receives the previous step's output, so one job can fetch data, reshape it, and post it somewhere else. That's the work a scheduled serverless function usually does.

A step is one of three things:

• a request to any HTTP endpoint,
• a transform that reshapes JSON without making a request, or
• a built-in step for a known API, such as slack_send_message, stripe_list_subscriptions or smtp_send_email. You fill in a few fields and cronservices builds the request. See Integrations.

#Quickstart

1. Create an account. The Hobby plan is free and needs no card.
2. Create an API key in Settings → API keys.
3. Create a job:

curl -X POST https://api.cron.services/alarms \
  -H "Authorization: Bearer $CRONSERVICES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warm product cache",
    "cron": { "expression": "*/15 * * * *" },
    "nodes": [
      { "id": "warm", "request": { "method": "POST", "endpoint": "https://shop.example.com/api/cache/warm" } }
    ]
  }'

{ "id": "6f1c1f0e-2a4b-4d55-9a0e-7b1f3c2d9e10" }

cronservices now sends POST https://shop.example.com/api/cache/warm every 15 minutes and records every run. To try it immediately, call POST /alarms/{id}/run, which runs the job now and returns the run.

#Schedules

A repeating job has a cron object. expression is a standard 5-field cron expression, read as wall-clock time in time_zone (an IANA name such as America/New_York; defaults to UTC):

┌──────── minute        0-59
│ ┌────── hour          0-23
│ │ ┌──── day of month  1-31
│ │ │ ┌── month         1-12 or JAN-DEC
│ │ │ │ ┌ day of week   0-6 or SUN-SAT (0 is Sunday)
│ │ │ │ │
* * * * *

Each field takes *, a value, a range (1-5), a list (1,15), or a step (*/10, 0-30/5). A few extensions cover schedules plain cron can't express:

When both day-of-month and day-of-week are set (neither is *), the job fires on days that match either one, as in classic crontab.

{ "cron": { "expression": "0 9 * * 1-5", "time_zone": "Europe/Berlin" } }

Daylight saving time. A job at 09:00 in America/New_York fires at 09:00 local all year. A time skipped when the clocks go forward fires just after the change, and a time repeated when they go back fires once.

The fastest schedule is every minute (* * * * *). There's no seconds field, and @daily-style shortcuts aren't supported.

#One-time jobs

To fire once, send run_at instead of cron. It's an ISO 8601 timestamp with an offset, in the future and within a year:

curl -X POST https://api.cron.services/alarms \
  -H "Authorization: Bearer $CRONSERVICES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trial ends: acme",
    "run_at": "2026-12-01T09:00:00-05:00",
    "nodes": [
      { "id": "expire", "request": { "method": "POST", "endpoint": "https://api.example.com/trials/acme/expire", "credential_id": "YOUR_CREDENTIAL_ID" } }
    ]
  }'

The job fires within a few seconds of run_at, then sets complete_time and enabled: false. Its run stays in the job's history, and it no longer counts toward your plan's job limit. To run it again, PUT it with a new run_at.

#Steps

A job's nodes is a list of 1 to 20 steps, and at least one must make a request. Each step has an id (letters, digits, _ and -, unique within the job), an optional name, and exactly one kind:

The first step gets null as its input. A run stops at the first step that fails: a network error, a timeout, or a non-2xx status. The run records which step stopped it and why.

This job posts open pull requests to Slack every weekday at 09:00 Berlin time:

{
  "name": "Open PRs to #eng",
  "cron": { "expression": "0 9 * * 1-5", "time_zone": "Europe/Berlin" },
  "nodes": [
    { "id": "prs", "name": "Open PRs",
      "github_list_pull_requests": { "credential_id": "YOUR_GITHUB_CREDENTIAL_ID", "owner": "acme", "repo": "web", "state": "open" } },
    { "id": "lines", "name": "One line per PR",
      "transform": { "template": "{ \"count\": \"{{ $.length }}\", \"lines\": { \"{{#each $}}\": \"• <{{ $.html_url }}|#{{ $.number }}> {{ $.title }} ({{ $.user.login }})\" } }" } },
    { "id": "post", "name": "Post to Slack",
      "slack_send_message": { "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX", "text": "*{{ $.count }} open pull requests*\n{{ join($.lines, \"\\n\") }}" } }
  ]
}

The transform turns GitHub's array of pull requests into:

{
  "count": 2,
  "lines": [
    "• <https://github.com/acme/web/pull/412|#412> Fix retry backoff (ada)",
    "• <https://github.com/acme/web/pull/415|#415> Add pipeline editor (grace)"
  ]
}

and the Slack step posts:

*2 open pull requests*
• <https://github.com/acme/web/pull/412|#412> Fix retry backoff (ada)
• <https://github.com/acme/web/pull/415|#415> Add pipeline editor (grace)

The equivalent serverless function would need a deploy target, a cron trigger, secrets, a GitHub client, error handling, and logs. Here it's one JSON document, and every run is recorded.

#Request steps

A body that starts with { or [ is a JSON template and must be valid JSON once its placeholders are filled in, and it's sent as application/json unless you set Content-Type. Any other body is plain text with placeholders filled in, sent as text/plain.

#Transform steps

Use a transform to pick a few fields, rename them, or build a list that a later step sends or joins into text.

#Built-in steps

A built-in step takes only the fields its API needs, and cronservices builds and signs the request. Each one counts as a request: a non-2xx response stops the job.

Each service's page under Integrations lists its fields and a complete example job. Text fields such as a message or subject are filled in as text, so "Rain: {{ $.daily.precipitation_sum[0] }} mm" works anywhere.

#Templates

Placeholders use double braces and read from the previous step's output.

Where they work: request URLs, header values and bodies, transform templates, and the text fields of built-in steps.

Types are kept when a placeholder is the entire JSON value. "{{ $.count }}" and a bare {{ $.count }} both render as the number 2. A placeholder inside longer text becomes text: "Total: {{ $.count }}" renders as "Total: 2".

Lists: an object whose only key is {{#each <list>}} becomes an array. Its value is rendered once per item, with $ bound to the item:

{
  "store": "{{ $.store }}",
  "skus": { "{{#each $.rows}}": { "sku": "{{ $.sku }}", "store": "{{ $root.store }}" } }
}

{ "store": "nyc", "skus": [{ "sku": "a", "store": "nyc" }, { "sku": "b", "store": "nyc" }] }

To send a list as a chat message or an email, build a list of lines with #each in a transform step, then join it in the message, as in the pull request example.

Times. now() is when the job runs, in UTC. now:America/New_York is that same instant written in an IANA time zone, offset included. Add or subtract a duration, with spaces around + and -: now() - days(14), now:America/Los_Angeles + hours(9). days and months follow that time zone's calendar. A field that is already an ISO 8601 timestamp shifts the same way.

#Formats

format(now(), "YYYY-MM-DD") writes a layout instead of ISO 8601, and an optional third argument picks the zone: format(now(), "dddd, MMMM DD", "America/Los_Angeles"). format(now:America/Los_Angeles - days(1), "MM/DD/YYYY") is yesterday in that zone.

Text in [brackets] is copied as is: "ddd [at] hh:mm A" writes Wed at 02:05 PM.

Missing values render as null (or an empty string inside text) and are flagged in the editor preview. They don't fail the run.

#Credentials

A credential is a saved secret that any number of jobs can use. Steps refer to it by credential_id, so the secret never appears in a job, a template, or the run history. Create credentials in Settings → Credentials, or through the API:

curl -X POST https://api.cron.services/credentials \
  -H "Authorization: Bearer $CRONSERVICES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "GitHub (acme)", "bearer_token": { "token": "ghp_your_token" } }'

{ "id": "Xq3vK8mB2nT5wR7yL1pA" }

Secret fields (tokens, passwords, keys) are write-only. They're encrypted at rest and never returned, and reads show last4 instead. Updating a credential with an empty secret keeps the stored one. Editing a credential changes what every job using it sends, starting with its next run. A credential can't be deleted while a job uses it.

#API

Base URL: https://api.cron.services. Send JSON, and authenticate every request with Authorization: Bearer <API key>. The machine-readable spec is at /openapi.json. In the API, jobs are called alarms and steps are nodes.

#Job fields

#Run fields

Fields that are empty, zero, or unset are left out of responses.

#Errors

Errors return JSON with a stable code:

{
  "code": "validation_failed",
  "message": "Some fields are invalid",
  "fields": { "alarm.cron.expression": "hour must be 0-23, *, or a list, range or step of those" }
}

#Limits

A request that takes longer than 10 seconds is recorded with status 0. For longer work, have the endpoint accept the request, return 202, and finish in the background.