deploy.jobs.create

Add a scheduled job to an app

POST /deploy/api/apps/{id}/jobsIAM deploy:CreateJobChanges state

schedule is a five-field cron expression in UTC (minute hour day-of-month month day-of-week, or @hourly/@daily/@weekly/@monthly/@yearly). The command runs with /bin/sh -c in the app’s image with its full environment, on one of the app’s machines, which keeps the schedule itself. concurrency "skip" (default) records a due run as skipped while the previous one is still going.

Request syntax

POST /deploy/api/apps/{id}/jobs
{
  "name": "string",
  "schedule": "string",
  "command": "string",
  "service": "string",
  "enabled": "boolean",
  "timeoutSec": "number",
  "concurrency": "enum",
  "timezone": "object"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • nameRequired

    string

    Name of the job, unique within the app

    Constraints: 1-63 chars, /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/

  • scheduleRequired

    string

    When it runs: a five-field cron expression in UTC, or @hourly, @daily, @weekly, @monthly, @yearly

    Constraints: 1-200 chars

  • commandRequired

    string

    Command run with /bin/sh -c in the app’s image, with the app’s environment

    Constraints: 1-4096 chars

  • serviceOptional

    string

    Compose apps only: the service whose image and environment the job runs with; omitted or null, the published service

    Constraints: 1-63 chars

    May be null.

  • enabledOptional

    boolean

    Whether the job runs on its schedule; a new job is enabled unless this is false

  • timeoutSecOptional

    number

    Seconds a run may take before it is stopped; a new job gets 3600

    Constraints: integer, 10-86400

  • concurrencyOptional

    enum

    What happens when a run is due while the previous one is still going: skip (a new job’s default) records it as skipped, allow starts it anyway

    One of: skip, allow

  • timezoneOptional

    object

    Time zone of the schedule; only UTC

    Constraints: JSON

Response

201 with `data`: the new job, as list returns it (lastRun null).

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Fields of data

  • idAlways

    string

    Job id
  • nameAlways

    string

    Name, unique in the app
  • scheduleAlways

    string

    Cron expression, in UTC
  • scheduleDescriptionAlways

    string

    The schedule in words, or why it cannot be read
  • commandAlways

    string

    Command run with /bin/sh -c
  • serviceAlways

    string, may be null

    Compose apps: the service it runs in; null: the published service
  • timezoneAlways

    string

    Time zone of the schedule (UTC)
  • enabledAlways

    boolean

    Whether it runs on its schedule
  • timeoutSecAlways

    number

    Seconds a run may take before it is stopped
  • concurrencyAlways

    one of skip, allow

    skip: a due run is skipped while the previous one runs; allow: it starts anyway
  • nextRunAtAlways

    string, may be null

    When it runs next; null when disabled
  • lastRunAlways

    object, may be null

    Its newest run; null if it never ran
  • lastRun.​idAlways

    string

    Run id
  • lastRun.​statusAlways

    one of requested, running, succeeded, failed, timed_out, skipped, lost

    requested, running, succeeded, failed, timed_out, skipped or lost
  • lastRun.​triggerAlways

    one of schedule, manual

    schedule or manual (run now)
  • lastRun.​exitCodeAlways

    number, may be null

    Exit code; null until it finished
  • lastRun.​startedAtAlways

    string, may be null

    When it started
  • lastRun.​finishedAtAlways

    string, may be null

    When it finished
  • lastRun.​createdAtAlways

    string

    When the run was recorded
  • createdAtAlways

    string

    When it was created
  • updatedAtAlways

    string

    When it was last changed

Checked against the handlers: every route test validates their answers against this schema.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow deploy:CreateJob on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud deploy jobs create id --name example --schedule example --command example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_deploy_jobs_create.