Jobs HTTP API

The /jobs endpoints are used to query for and interact with jobs.

List Jobs

This endpoint lists all known jobs in the system registered with Nomad.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• prefix (string: "") - Specifies a string to filter jobs on based on an index prefix. This is specified as a query string parameter.

• namespace (string: "default") - Specifies the target namespace. Specifying * would return all jobs across all the authorized namespaces.

Sample Request

$ curl https://localhost:4646/v1/jobs

$ curl https://localhost:4646/v1/jobs?prefix=team

$ curl https://localhost:4646/v1/jobs?namespace=*&prefix=team

Sample Response

[
  {
    "ID": "example",
    "ParentID": "",
    "Name": "example",
    "Type": "service",
    "Priority": 50,
    "Status": "pending",
    "StatusDescription": "",
    "JobSummary": {
      "JobID": "example",
      "Namespace": "default",
      "Summary": {
        "cache": {
          "Queued": 1,
          "Complete": 1,
          "Failed": 0,
          "Running": 0,
          "Starting": 0,
          "Lost": 0
        }
      },
      "Children": {
        "Pending": 0,
        "Running": 0,
        "Dead": 0
      },
      "CreateIndex": 52,
      "ModifyIndex": 96
    },
    "CreateIndex": 52,
    "ModifyIndex": 93,
    "JobModifyIndex": 52
  }
]

Create Job

This endpoint creates (aka "registers") a new job in the system.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• Job (Job: <required>) - Specifies the JSON definition of the job.

• EnforceIndex (bool: false) - If set, the job will only be registered if the passed JobModifyIndex matches the current job's index. If the index is zero, the register only occurs if the job is new. This paradigm allows check-and-set style job updating.

• JobModifyIndex (int: 0) - Specifies the JobModifyIndex to enforce the current job is at.

• PolicyOverride (bool: false) - If set, any soft mandatory Sentinel policies will be overridden. This allows a job to be registered when it would be denied by policy.

• PreserveCounts (bool: false) - If set, existing task group counts are preserved, over those specified in the new job spec.

Sample Payload

{
  "Job": {
    "Datacenters": ["dc1"],
    "ID": "cache",
    "TaskGroups": [
      {
        "Name": "cache",
        "Networks": [
          {
            "DynamicPorts": [
              {
                "Label": "db",
                "To": 6379
              }
            ]
          }
        ],
        "Services": [
          {
            "Name": "redis-cache",
            "PortLabel": "db"
          }
        ],
        "Tasks": [
          {
            "Config": {
              "image": "redis:3.2",
              "ports": ["db"]
            },
            "Driver": "docker",
            "Name": "redis"
          }
        ]
      }
    ]
  }
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/jobs

Sample Response

{
  "EvalID": "",
  "EvalCreateIndex": 0,
  "JobModifyIndex": 109,
  "Warnings": "",
  "Index": 0,
  "LastContact": 0,
  "KnownLeader": false
}

Parse Job

This endpoint will parse a HCL jobspec and produce the equivalent JSON encoded job.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• JobHCL (string: <required>) - Specifies the HCL definition of the job encoded in a JSON string.

• Canonicalize (bool: false) - Flag to enable setting any unset fields to their default values.

• HCLv1 (bool: false) - Use the legacy v1 HCL parser.

Sample Payload

{
  "JobHCL": "job \"example\" {\n  type = \"service\"\n  group \"cache\" {}\n}",
  "Canonicalize": true
}

You can use a tool such as jq to generate the payload from a local HCL file:

$ jq -Rsc '{ JobHCL: ., Canonicalize: true }' example.nomad > payload.json

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/jobs/parse

Sample Response

{
  "AllAtOnce": false,
  "Constraints": null,
  "Affinities": null,
  "CreateIndex": 0,
  "Datacenters": null,
  "ID": "my-job",
  "JobModifyIndex": 0,
  "Meta": null,
  "Migrate": null,
  "ModifyIndex": 0,
  "Name": "my-job",
  "Namespace": "default",
  "ParameterizedJob": null,
  "ParentID": "",
  "Payload": null,
  "Periodic": null,
  "Priority": 50,
  "Region": "global",
  "Reschedule": null,
  "Stable": false,
  "Status": "",
  "StatusDescription": "",
  "Stop": false,
  "SubmitTime": null,
  "TaskGroups": null,
  "Type": "service",
  "Update": null,
  "VaultToken": "",
  "Version": 0
}

Read Job

This endpoint reads information about a single job for its specification and status.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• :job_id (string: <required>) - Specifies the ID of the job (as specified in the job file during submission). This is specified as part of the path.
• namespace (string: "default") - Specifies the namespace of the job. If not specified, defaults to "default". This is specified as a URL query parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/job/my-job