Cron Applications

List Cron Jobs

GET /v1/applications/{uuid}/cron-jobs

List an app's scheduled jobs. Each job fires an HTTP request to your deployed app on a schedule — nightly work, cache warming, digests, and the like. Cron Jobs require a paid plan and count against a per-account limit.

Job fields

uuid string (uuid)

The job's public id — the {cron_uuid} of the update, delete, and run endpoints.

application_uuid string (uuid)

The app the job belongs to.

account_uuid string (uuid)

The account that owns the app.

name string

A label for the job.

schedule string

A 5-field UTC cron expression (0 3 * * *) or a descriptor (@hourly, @daily).

method string

The HTTP method to fire. Default GET.

path string

The absolute path on your app to request. Default /.

enabled bool

Whether the schedule is active. A disabled job never fires on its schedule but can still be run manually.

last_run_at string

Timestamp of the most recent run (null until it first fires).

Deprecated: until the sunset each job also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.

Response — 200 OK
{
  "cron_jobs": [
    {
      "uuid": "019bfdb1-ec00-7002-8953-7f61c8a1f3e1",
      "application_uuid": "019be838-d261-7d9b-9499-71995a3a91c6",
      "account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
      "name": "nightly-digest",
      "schedule": "0 3 * * *",
      "method": "GET",
      "path": "/cron/digest",
      "enabled": true,
      "last_run_at": "2026-09-20T03:00:04Z"
    }
  ]
}

Create a Cron Job

POST /v1/applications/{uuid}/cron-jobs

Add a scheduled job. On each tick the platform fires method https://<your-app><path>. The app must have a live serving endpoint (it must be deployed and reachable), or the request has nowhere to land.

Request (application/json)

name string

Required. A label for the job.

schedule string

Required. A 5-field UTC cron expression (0 3 * * *) or a descriptor (@hourly, @daily).

method string

HTTP method. Default GET.

path string

Absolute path to request on your app. Default /.

enabled bool

Whether to schedule it immediately. Default true.

Authenticating the request

Set a CRON_SECRET environment variable on the app and the platform sends it as Authorization: Bearer <CRON_SECRET> on every cron request — so your handler can confirm the call is a genuine platform cron and not a public hit.

Request
curl -X POST "https://api.ngris.com/v1/applications/019be838-d261-7d9b-9499-71995a3a91c6/cron-jobs" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-digest","schedule":"0 3 * * *","method":"GET","path":"/cron/digest"}'

Response — 201 Created
{
  "cron_job": {
    "uuid": "019bfdb1-ec00-7002-8953-7f61c8a1f3e1",
    "application_uuid": "019be838-d261-7d9b-9499-71995a3a91c6",
    "account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
    "name": "nightly-digest",
    "schedule": "0 3 * * *",
    "method": "GET",
    "path": "/cron/digest",
    "enabled": true,
    "last_run_at": null
  }
}

Update a Cron Job

PUT /v1/applications/{uuid}/cron-jobs/{cron_uuid}

Change a job's schedule, target, or enabled state. Send only the fields you want to change; the same validation as create applies. Toggle enabled to pause a job without deleting it.

Request (application/json)

name string

A new label.

schedule string

A new 5-field UTC cron expression or descriptor.

method string

A new HTTP method.

path string

A new absolute path.

enabled bool

false pauses the schedule; true resumes it.

Request
curl -X PUT "https://api.ngris.com/v1/applications/019be838-d261-7d9b-9499-71995a3a91c6/cron-jobs/019bfdb1-ec00-7002-8953-7f61c8a1f3e1" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"@hourly","enabled":true}'

Response — 200 OK
{
  "cron_job": {
    "uuid": "019bfdb1-ec00-7002-8953-7f61c8a1f3e1",
    "name": "nightly-digest",
    "schedule": "@hourly",
    "enabled": true
  }
}

Delete a Cron Job

DELETE /v1/applications/{uuid}/cron-jobs/{cron_uuid}

Remove a job by its uuid. Returns 200 OK with {"deleted": true}. The schedule stops immediately. A job of another app or account is 404 cron job not found.

Request
curl -X DELETE \
  "https://api.ngris.com/v1/applications/019be838-d261-7d9b-9499-71995a3a91c6/cron-jobs/019bfdb1-ec00-7002-8953-7f61c8a1f3e1" \
  -H "X-API-KEY: <your_api_key>"

Run a Cron Job Now

POST /v1/applications/{uuid}/cron-jobs/{cron_uuid}/run

Fire the job immediately, off-schedule — the same request the scheduler would send (including the Authorization: Bearer <CRON_SECRET> header when CRON_SECRET is set). Use it to test a new job end to end without waiting for the next tick.

Request
curl -X POST \
  "https://api.ngris.com/v1/applications/019be838-d261-7d9b-9499-71995a3a91c6/cron-jobs/019bfdb1-ec00-7002-8953-7f61c8a1f3e1/run" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK
{ "ran": true, "status_code": 200 }