Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Tasks API

9 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

POST/services/{serviceId}/run

Run a one-off command

Runs the command (argv, no shell) in a throwaway container of the service's current image with its environment, on the service's server, with the service's resource limits and a timeout (default 30 minutes). Requires deployments:write; audited. Returns 202 with the queued run; follow the output through GET /task-runs/{runId}/logs?follow=true.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
serviceIdrequiredpathstring
Request body · application/json · required
RunCommandInputBody
  • commandstring[] | nullrequired
    Argv, run without a shell. Wrap in ["sh","-c",…] for shell syntax.
  • timeoutSecondsinteger (int64)
    Default 1800 (30 minutes).
Response 202 · Accepted · application/json
RunView
  • actorLabelstring
  • commandstring[] | nullrequired
  • createdAtstring (date-time)required
  • errorstring
    Why the run failed, timed out or was skipped.
  • exitCodeinteger (int64)
  • finishedAtstring (date-time)
  • idstringrequired
  • logLinesinteger (int64)required
  • namestringrequired
    The task's name, or "one-off" for a command.
  • scheduledForstring (date-time)
  • serviceIdstringrequired
  • sourcestringrequired
    cron, manual (Run now), one_off (run command) or a feature such as preview_seed.
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | timed_out | skippedrequired
  • taskIdstring
  • timeoutSecondsinteger (int64)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/task-runs

Run history of a service's tasks and one-off commands

ParameterInTypeDescription
serviceIdrequiredpathstring
taskIdquerystring (uuid)Only the runs of this task.
limitqueryinteger (int64)
Response 200 · OK · application/json
RunListOutputBody
  • RunView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/tasks

List a service's cron tasks

ParameterInTypeDescription
serviceIdrequiredpathstring
Response 200 · OK · application/json
TaskListOutputBody
  • TaskView[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/services/{serviceId}/tasks

Schedule a recurring command

A cron task runs its command in a throwaway container of the service's current image, with the service's environment and networks, on the service's server. The schedule is evaluated in timezone (IANA name, default UTC); one run at most per minute. Keeps the last 50 runs.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
serviceIdrequiredpathstring
Request body · application/json · required
CreateTaskInputBody
  • commandstring[] | nullrequired
    Argv, run without a shell in a container of the service's current image. Wrap in ["sh","-c",…] for shell syntax.
  • concurrencyenum: forbid | allow
    forbid (default) skips a tick while the previous run is still active.
  • enabledboolean
    Default true.
  • namestringrequired
  • schedulestringrequired
    5-field cron expression (minute hour day-of-month month day-of-week) or @hourly/@daily/@weekly/@monthly/@yearly, evaluated in timezone.
  • timeoutSecondsinteger (int64)
    Default 1800 (30 minutes).
  • timezonestring
    IANA time zone the schedule is evaluated in, e.g. Europe/Berlin. Default UTC.
Response 201 · Created · application/json
TaskView
  • commandstring[] | nullrequired
    Argv, run without a shell.
  • concurrencyenum: forbid | allowrequired
  • createdAtstring (date-time)required
  • enabledbooleanrequired
  • idstringrequired
  • RunView
  • lastRunAtstring (date-time)
  • namestringrequired
  • nextRunAtstring (date-time)
  • schedulestringrequired
    5-field cron expression or @macro, evaluated in timezone.
  • serviceIdstringrequired
  • timeoutSecondsinteger (int64)required
  • timezonestringrequired
    IANA time zone the schedule is evaluated in (default UTC). A daylight-saving gap skips that day's run; a repeated hour runs once.
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/task-runs/{runId}

Get a task run

ParameterInTypeDescription
runIdrequiredpathstring
Response 200 · OK · application/json
RunView
  • actorLabelstring
  • commandstring[] | nullrequired
  • createdAtstring (date-time)required
  • errorstring
    Why the run failed, timed out or was skipped.
  • exitCodeinteger (int64)
  • finishedAtstring (date-time)
  • idstringrequired
  • logLinesinteger (int64)required
  • namestringrequired
    The task's name, or "one-off" for a command.
  • scheduledForstring (date-time)
  • serviceIdstringrequired
  • sourcestringrequired
    cron, manual (Run now), one_off (run command) or a feature such as preview_seed.
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | timed_out | skippedrequired
  • taskIdstring
  • timeoutSecondsinteger (int64)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/task-schedules/preview

Describe a cron expression

Validates the expression and returns a plain-English summary (naming the time zone) and the next runs as UTC instants, computed in timezone (default UTC). An invalid expression or zone answers 200 with valid: false and the reason in error.

Request body · application/json · required
PreviewInputBody
  • countinteger (int64)
    How many upcoming runs to return (default 5).
  • schedulestringrequired
  • timezonestring
    IANA zone the schedule is evaluated in (default UTC).
Response 200 · OK · application/json
SchedulePreview
  • descriptionstring
    Human-readable summary naming the time zone.
  • errorstring
  • nextRunsstring (date-time)[] | nullrequired
    The next runs as UTC instants.
  • timezonestring
    The normalized zone the preview was computed in.
  • validbooleanrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/tasks/{taskId}

Update a cron task

ParameterInTypeDescription
taskIdrequiredpathstring
Request body · application/json · required
PatchTaskInputBody
  • commandstring[]
  • concurrencyenum: forbid | allow
  • enabledboolean
  • namestring
  • schedulestring
  • timeoutSecondsinteger (int64)
  • timezonestring
    IANA zone; changing it recomputes the next run.
Response 200 · OK · application/json
TaskView
  • commandstring[] | nullrequired
    Argv, run without a shell.
  • concurrencyenum: forbid | allowrequired
  • createdAtstring (date-time)required
  • enabledbooleanrequired
  • idstringrequired
  • RunView
  • lastRunAtstring (date-time)
  • namestringrequired
  • nextRunAtstring (date-time)
  • schedulestringrequired
    5-field cron expression or @macro, evaluated in timezone.
  • serviceIdstringrequired
  • timeoutSecondsinteger (int64)required
  • timezonestringrequired
    IANA time zone the schedule is evaluated in (default UTC). A daylight-saving gap skips that day's run; a repeated hour runs once.
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/tasks/{taskId}

Delete a cron task and its run history

ParameterInTypeDescription
taskIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/tasks/{taskId}/run

Run a cron task now

Starts a run immediately, whatever the schedule and concurrency policy. Returns 202 with the queued run; follow it through GET /task-runs/{runId}/logs?follow=true. 409 not_deployed / server_offline when it can not start.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
taskIdrequiredpathstring
Response 202 · Accepted · application/json
RunView
  • actorLabelstring
  • commandstring[] | nullrequired
  • createdAtstring (date-time)required
  • errorstring
    Why the run failed, timed out or was skipped.
  • exitCodeinteger (int64)
  • finishedAtstring (date-time)
  • idstringrequired
  • logLinesinteger (int64)required
  • namestringrequired
    The task's name, or "one-off" for a command.
  • scheduledForstring (date-time)
  • serviceIdstringrequired
  • sourcestringrequired
    cron, manual (Run now), one_off (run command) or a feature such as preview_seed.
  • startedAtstring (date-time)
  • statusenum: queued | running | succeeded | failed | timed_out | skippedrequired
  • taskIdstring
  • timeoutSecondsinteger (int64)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictnot_deployed
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.