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

id int

The job's id — use it on the update, delete, and run endpoints.

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).

Response — 200 OK
{
  "cron_jobs": [
    {
      "id": 7,
      "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/a1b2c3d4-…/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": {
    "id": 7,
    "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/{id}

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/a1b2c3d4-…/cron-jobs/7" \
  -H "X-API-KEY: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"@hourly","enabled":true}'

Response — 200 OK
{ "status": "ok", "id": 7 }

Delete a Cron Job

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

Remove a job by id. Returns 204 No Content. The schedule stops immediately.

Request
curl -X DELETE \
  "https://api.ngris.com/v1/applications/a1b2c3d4-…/cron-jobs/7" \
  -H "X-API-KEY: <your_api_key>"

Run a Cron Job Now

POST /v1/applications/{uuid}/cron-jobs/{id}/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/a1b2c3d4-…/cron-jobs/7/run" \
  -H "X-API-KEY: <your_api_key>"

Response — 200 OK
{ "status": "triggered", "id": 7 }