github.com/smintz/nomad@v0.8.3/website/source/api/jobs.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Jobs - HTTP API
     4  sidebar_current: api-jobs
     5  description: |-
     6    The /jobs endpoints are used to query for and interact with jobs.
     7  ---
     8  
     9  # Jobs HTTP API
    10  
    11  The `/jobs` endpoints are used to query for and interact with jobs.
    12  
    13  ## List Jobs
    14  
    15  This endpoint lists all known jobs in the system registered with Nomad.
    16  
    17  | Method | Path                      | Produces                   |
    18  | ------ | ------------------------- | -------------------------- |
    19  | `GET`  | `/v1/jobs`                | `application/json`         |
    20  
    21  The table below shows this endpoint's support for
    22  [blocking queries](/api/index.html#blocking-queries) and
    23  [required ACLs](/api/index.html#acls).
    24  
    25  | Blocking Queries | ACL Required                |
    26  | ---------------- | --------------------------- |
    27  | `YES`            | `namespace:list-jobs`       |
    28  
    29  ### Parameters
    30  
    31  - `prefix` `(string: "")` - Specifies a string to filter jobs on based on
    32    an index prefix. This is specified as a querystring parameter.
    33  
    34  ### Sample Request
    35  
    36  ```text
    37  $ curl \
    38      https://localhost:4646/v1/jobs
    39  ```
    40  
    41  ```text
    42  $ curl \
    43      https://localhost:4646/v1/jobs?prefix=team
    44  ```
    45  
    46  ### Sample Response
    47  
    48  ```json
    49  [
    50    {
    51      "ID": "example",
    52      "ParentID": "",
    53      "Name": "example",
    54      "Type": "service",
    55      "Priority": 50,
    56      "Status": "pending",
    57      "StatusDescription": "",
    58      "JobSummary": {
    59        "JobID": "example",
    60        "Summary": {
    61          "cache": {
    62            "Queued": 1,
    63            "Complete": 1,
    64            "Failed": 0,
    65            "Running": 0,
    66            "Starting": 0,
    67            "Lost": 0
    68          }
    69        },
    70        "Children": {
    71          "Pending": 0,
    72          "Running": 0,
    73          "Dead": 0
    74        },
    75        "CreateIndex": 52,
    76        "ModifyIndex": 96
    77      },
    78      "CreateIndex": 52,
    79      "ModifyIndex": 93,
    80      "JobModifyIndex": 52
    81    }
    82  ]
    83  ```
    84  
    85  ## Create Job
    86  
    87  This endpoint creates (aka "registers") a new job in the system.
    88  
    89  | Method  | Path                      | Produces                   |
    90  | ------- | ------------------------- | -------------------------- |
    91  | `POST`  | `/v1/jobs`                | `application/json`         |
    92  
    93  The table below shows this endpoint's support for
    94  [blocking queries](/api/index.html#blocking-queries) and
    95  [required ACLs](/api/index.html#acls).
    96  
    97  | Blocking Queries | ACL Required |
    98  | ---------------- | ------------ |
    99  | `NO`             | `namespace:submit-job`<br>`namespace:sentinel-override` if `PolicyOverride` set |
   100  
   101  ### Parameters
   102  
   103  - `Job` `(Job: <required>)` - Specifies the JSON definition of the job.
   104  
   105  - `EnforceIndex` `(bool: false)` - If set, the job will only be registered if the
   106    passed `JobModifyIndex` matches the current job's index. If the index is zero,
   107    the register only occurs if the job is new. This paradigm allows check-and-set
   108    style job updating.
   109  
   110  - `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the
   111    current job is at.
   112  
   113  - `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
   114    will be overridden. This allows a job to be registered when it would be denied
   115    by policy.
   116  
   117  ### Sample Payload
   118  
   119  ```json
   120  {
   121      "Job": {
   122          "ID": "example",
   123          "Name": "example",
   124          "Type": "service",
   125          "Priority": 50,
   126          "Datacenters": [
   127              "dc1"
   128          ],
   129          "TaskGroups": [{
   130              "Name": "cache",
   131              "Count": 1,
   132              "Tasks": [{
   133                  "Name": "redis",
   134                  "Driver": "docker",
   135                  "User": "",
   136                  "Config": {
   137                      "image": "redis:3.2",
   138                      "port_map": [{
   139                          "db": 6379
   140                      }]
   141                  },
   142                  "Services": [{
   143                      "Id": "",
   144                      "Name": "redis-cache",
   145                      "Tags": [
   146                          "global",
   147                          "cache"
   148                      ],
   149                      "PortLabel": "db",
   150                      "AddressMode": "",
   151                      "Checks": [{
   152                          "Id": "",
   153                          "Name": "alive",
   154                          "Type": "tcp",
   155                          "Command": "",
   156                          "Args": null,
   157                          "Path": "",
   158                          "Protocol": "",
   159                          "PortLabel": "",
   160                          "Interval": 10000000000,
   161                          "Timeout": 2000000000,
   162                          "InitialStatus": "",
   163                          "TLSSkipVerify": false
   164                      }]
   165                  }],
   166                  "Resources": {
   167                      "CPU": 500,
   168                      "MemoryMB": 256,
   169                      "Networks": [{
   170                          "Device": "",
   171                          "CIDR": "",
   172                          "IP": "",
   173                          "MBits": 10,
   174                          "DynamicPorts": [{
   175                              "Label": "db",
   176                              "Value": 0
   177                          }]
   178                      }]
   179                  },
   180                  "Leader": false
   181              }],
   182              "RestartPolicy": {
   183                  "Interval": 300000000000,
   184                  "Attempts": 10,
   185                  "Delay": 25000000000,
   186                  "Mode": "delay"
   187              },
   188              "ReschedulePolicy": {
   189                  "Attempts": 10,
   190                  "Delay": 30000000000,
   191                  "DelayFunction": "exponential",
   192                  "Interval": 0,
   193                  "MaxDelay": 3600000000000,
   194                  "Unlimited": true
   195              },
   196              "EphemeralDisk": {
   197                  "SizeMB": 300
   198              }
   199          }],
   200          "Update": {
   201              "MaxParallel": 1,
   202              "MinHealthyTime": 10000000000,
   203              "HealthyDeadline": 180000000000,
   204              "AutoRevert": false,
   205              "Canary": 0
   206          }
   207      }
   208  }
   209  ```
   210  
   211  ### Sample Request
   212  
   213  ```text
   214  $ curl \
   215      --request POST \
   216      --data @my-job.nomad \
   217      https://localhost:4646/v1/jobs
   218  ```
   219  
   220  ### Sample Response
   221  
   222  ```json
   223  {
   224    "EvalID": "",
   225    "EvalCreateIndex": 0,
   226    "JobModifyIndex": 109,
   227    "Warnings": "",
   228    "Index": 0,
   229    "LastContact": 0,
   230    "KnownLeader": false
   231  }
   232  ```
   233  
   234  ## Parse Job
   235  
   236  This endpoint will parse a HCL jobspec and produce the equivalent JSON encoded
   237  job.
   238  
   239  | Method | Path                      | Produces                   |
   240  | ------ | ------------------------- | -------------------------- |
   241  | `POST` | `/v1/jobs/parse`          | `application/json`         |
   242  
   243  The table below shows this endpoint's support for
   244  [blocking queries](/api/index.html#blocking-queries) and
   245  [required ACLs](/api/index.html#acls).
   246  
   247  | Blocking Queries | ACL Required |
   248  | ---------------- | ------------ |
   249  | `NO`             | `none`       |
   250  
   251  ### Parameters
   252  
   253  - `JobHCL` `(string: <required>)` - Specifies the HCL definition of the job
   254    encoded in a JSON string.
   255  - `Canonicalize` `(bool: false)` - Flag to enable setting any unset fields to
   256    their default values.
   257  
   258  ## Sample Payload
   259  
   260  ```json
   261  {
   262      "JobHCL":"job \"example\" { type = \"service\" group \"cache\" {} }",
   263      "Canonicalize": true
   264  }
   265  ```
   266  
   267  ### Sample Request
   268  
   269  ```text
   270  $ curl \
   271      --request POST \
   272      --data '{"Canonicalize": true, "JobHCL": "job \"my-job\" {}"}' \
   273      https://localhost:4646/v1/jobs/parse
   274  ```
   275  
   276  ### Sample Response
   277  
   278  ```json
   279  {
   280      "AllAtOnce": false,
   281      "Constraints": null,
   282      "CreateIndex": 0,
   283      "Datacenters": null,
   284      "ID": "my-job",
   285      "JobModifyIndex": 0,
   286      "Meta": null,
   287      "Migrate": null,
   288      "ModifyIndex": 0,
   289      "Name": "my-job",
   290      "Namespace": "default",
   291      "ParameterizedJob": null,
   292      "ParentID": "",
   293      "Payload": null,
   294      "Periodic": null,
   295      "Priority": 50,
   296      "Region": "global",
   297      "Reschedule": null,
   298      "Stable": false,
   299      "Status": "",
   300      "StatusDescription": "",
   301      "Stop": false,
   302      "SubmitTime": null,
   303      "TaskGroups": null,
   304      "Type": "service",
   305      "Update": null,
   306      "VaultToken": "",
   307      "Version": 0
   308  }
   309  ```
   310  
   311  ## Read Job
   312  
   313  This endpoint reads information about a single job for its specification and
   314  status.
   315  
   316  | Method | Path                      | Produces                   |
   317  | ------ | ------------------------- | -------------------------- |
   318  | `GET`  | `/v1/job/:job_id`         | `application/json`         |
   319  
   320  The table below shows this endpoint's support for
   321  [blocking queries](/api/index.html#blocking-queries) and
   322  [required ACLs](/api/index.html#acls).
   323  
   324  | Blocking Queries | ACL Required               |
   325  | ---------------- | -------------------------- |
   326  | `YES`            | `namespace:read-job`       |
   327  
   328  ### Parameters
   329  
   330  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
   331    the job file during submission). This is specified as part of the path.
   332  
   333  ### Sample Request
   334  
   335  ```text
   336  $ curl \
   337      https://localhost:4646/v1/job/my-job
   338  ```
   339  
   340  ### Sample Response
   341  
   342  ```json
   343  {
   344    "Region": "global",
   345    "ID": "example",
   346    "ParentID": "",
   347    "Name": "example",
   348    "Type": "batch",
   349    "Priority": 50,
   350    "AllAtOnce": false,
   351    "Datacenters": [
   352      "dc1"
   353    ],
   354    "Constraints": [
   355      {
   356        "LTarget": "${attr.kernel.name}",
   357        "RTarget": "linux",
   358        "Operand": "="
   359      }
   360    ],
   361    "TaskGroups": [
   362      {
   363        "Name": "cache",
   364        "Count": 1,
   365        "Constraints": [
   366          {
   367            "LTarget": "${attr.os.signals}",
   368            "RTarget": "SIGUSR1",
   369            "Operand": "set_contains"
   370          }
   371        ],
   372        "RestartPolicy": {
   373          "Attempts": 10,
   374          "Interval": 300000000000,
   375          "Delay": 25000000000,
   376          "Mode": "delay"
   377        },
   378        "Tasks": [
   379          {
   380            "Name": "redis",
   381            "Driver": "docker",
   382            "User": "foo-user",
   383            "Config": {
   384              "image": "redis:latest",
   385              "port_map": [
   386                {
   387                  "db": 6379
   388                }
   389              ]
   390            },
   391            "Env": {
   392              "foo": "bar",
   393              "baz": "pipe"
   394            },
   395            "Services": [
   396              {
   397                "Name": "cache-redis",
   398                "PortLabel": "db",
   399                "Tags": [
   400                  "global",
   401                  "cache"
   402                ],
   403                "Checks": [
   404                  {
   405                    "Name": "alive",
   406                    "Type": "tcp",
   407                    "Command": "",
   408                    "Args": null,
   409                    "Path": "",
   410                    "Protocol": "",
   411                    "PortLabel": "",
   412                    "Interval": 10000000000,
   413                    "Timeout": 2000000000,
   414                    "InitialStatus": ""
   415                  }
   416                ]
   417              }
   418            ],
   419            "Vault": null,
   420            "Templates": [
   421              {
   422                "SourcePath": "local/config.conf.tpl",
   423                "DestPath": "local/config.conf",
   424                "EmbeddedTmpl": "",
   425                "ChangeMode": "signal",
   426                "ChangeSignal": "SIGUSR1",
   427                "Splay": 5000000000,
   428                "Perms": ""
   429              }
   430            ],
   431            "Constraints": null,
   432            "Resources": {
   433              "CPU": 500,
   434              "MemoryMB": 256,
   435              "DiskMB": 0,
   436              "IOPS": 0,
   437              "Networks": [
   438                {
   439                  "Device": "",
   440                  "CIDR": "",
   441                  "IP": "",
   442                  "MBits": 10,
   443                  "ReservedPorts": [
   444                    {
   445                      "Label": "rpc",
   446                      "Value": 25566
   447                    }
   448                  ],
   449                  "DynamicPorts": [
   450                    {
   451                      "Label": "db",
   452                      "Value": 0
   453                    }
   454                  ]
   455                }
   456              ]
   457            },
   458            "DispatchPayload": {
   459              "File": "config.json"
   460            },
   461            "Meta": {
   462              "foo": "bar",
   463              "baz": "pipe"
   464            },
   465            "KillTimeout": 5000000000,
   466            "LogConfig": {
   467              "MaxFiles": 10,
   468              "MaxFileSizeMB": 10
   469            },
   470            "Artifacts": [
   471              {
   472                "GetterSource": "http://foo.com/artifact.tar.gz",
   473                "GetterOptions": {
   474                  "checksum": "md5:c4aa853ad2215426eb7d70a21922e794"
   475                },
   476                "RelativeDest": "local/"
   477              }
   478            ],
   479            "Leader": false
   480          }
   481        ],
   482        "EphemeralDisk": {
   483          "Sticky": false,
   484          "SizeMB": 300,
   485          "Migrate": false
   486        },
   487        "Meta": {
   488          "foo": "bar",
   489          "baz": "pipe"
   490        }
   491      }
   492    ],
   493    "Update": {
   494      "Stagger": 10000000000,
   495      "MaxParallel": 1
   496    },
   497    "Periodic": {
   498      "Enabled": true,
   499      "Spec": "* * * * *",
   500      "SpecType": "cron",
   501      "ProhibitOverlap": true
   502    },
   503    "ParameterizedJob": {
   504      "Payload": "required",
   505      "MetaRequired": [
   506        "foo"
   507      ],
   508      "MetaOptional": [
   509        "bar"
   510      ]
   511    },
   512    "Payload": null,
   513    "Meta": {
   514      "foo": "bar",
   515      "baz": "pipe"
   516    },
   517    "VaultToken": "",
   518    "Status": "running",
   519    "StatusDescription": "",
   520    "CreateIndex": 7,
   521    "ModifyIndex": 7,
   522    "JobModifyIndex": 7
   523  }
   524  ```
   525  
   526  ## List Job Versions
   527  
   528  This endpoint reads information about all versions of a job.
   529  
   530  | Method | Path                       | Produces                   |
   531  | ------ | -------------------------- | -------------------------- |
   532  | `GET`  | `/v1/job/:job_id/versions` | `application/json`         |
   533  
   534  The table below shows this endpoint's support for
   535  [blocking queries](/api/index.html#blocking-queries) and
   536  [required ACLs](/api/index.html#acls).
   537  
   538  | Blocking Queries | ACL Required               |
   539  | ---------------- | -------------------------- |
   540  | `YES`            | `namespace:read-job`       |
   541  
   542  ### Parameters
   543  
   544  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
   545    the job file during submission). This is specified as part of the path.
   546  
   547  ### Sample Request
   548  
   549  ```text
   550  $ curl \
   551      https://localhost:4646/v1/job/my-job/versions
   552  ```
   553  
   554  ### Sample Response
   555  
   556  ```json
   557  [
   558    {
   559      "Stop": false,
   560      "Region": "global",
   561      "ID": "example",
   562      "ParentID": "",
   563      "Name": "example",
   564      "Type": "service",
   565      "Priority": 50,
   566      "AllAtOnce": false,
   567      "Datacenters": [
   568        "dc1"
   569      ],
   570      "Constraints": null,
   571      "TaskGroups": [
   572        {
   573          "Name": "cache",
   574          "Count": 1,
   575          "Update": {
   576            "Stagger": 0,
   577            "MaxParallel": 1,
   578            "HealthCheck": "checks",
   579            "MinHealthyTime": 10000000000,
   580            "HealthyDeadline": 300000000000,
   581            "AutoRevert": false,
   582            "Canary": 0
   583          },
   584          "Constraints": null,
   585          "RestartPolicy": {
   586            "Attempts": 10,
   587            "Interval": 300000000000,
   588            "Delay": 25000000000,
   589            "Mode": "delay"
   590          },
   591          "Tasks": [
   592            {
   593              "Name": "redis",
   594              "Driver": "docker",
   595              "User": "",
   596              "Config": {
   597                "image": "redis:3.2",
   598                "port_map": [
   599                  {
   600                    "db": 6379
   601                  }
   602                ]
   603              },
   604              "Env": null,
   605              "Services": [
   606                {
   607                  "Name": "redis-cache",
   608                  "PortLabel": "db",
   609                  "Tags": [
   610                    "global",
   611                    "cache"
   612                  ],
   613                  "Checks": [
   614                    {
   615                      "Name": "alive",
   616                      "Type": "tcp",
   617                      "Command": "",
   618                      "Args": null,
   619                      "Path": "",
   620                      "Protocol": "",
   621                      "PortLabel": "",
   622                      "Interval": 10000000000,
   623                      "Timeout": 2000000000,
   624                      "InitialStatus": "",
   625                      "TLSSkipVerify": false
   626                    }
   627                  ]
   628                }
   629              ],
   630              "Vault": null,
   631              "Templates": null,
   632              "Constraints": null,
   633              "Resources": {
   634                "CPU": 500,
   635                "MemoryMB": 256,
   636                "DiskMB": 0,
   637                "IOPS": 0,
   638                "Networks": [
   639                  {
   640                    "Device": "",
   641                    "CIDR": "",
   642                    "IP": "",
   643                    "MBits": 10,
   644                    "ReservedPorts": null,
   645                    "DynamicPorts": [
   646                      {
   647                        "Label": "db",
   648                        "Value": 0
   649                      }
   650                    ]
   651                  }
   652                ]
   653              },
   654              "DispatchPayload": null,
   655              "Meta": null,
   656              "KillTimeout": 5000000000,
   657              "LogConfig": {
   658                "MaxFiles": 10,
   659                "MaxFileSizeMB": 10
   660              },
   661              "Artifacts": null,
   662              "Leader": false
   663            }
   664          ],
   665          "EphemeralDisk": {
   666            "Sticky": false,
   667            "SizeMB": 300,
   668            "Migrate": false
   669          },
   670          "Meta": null
   671        }
   672      ],
   673      "Update": {
   674        "Stagger": 10000000000,
   675        "MaxParallel": 1,
   676        "HealthCheck": "",
   677        "MinHealthyTime": 0,
   678        "HealthyDeadline": 0,
   679        "AutoRevert": false,
   680        "Canary": 0
   681      },
   682      "Periodic": null,
   683      "ParameterizedJob": null,
   684      "Payload": null,
   685      "Meta": null,
   686      "VaultToken": "",
   687      "Status": "pending",
   688      "StatusDescription": "",
   689      "Stable": false,
   690      "Version": 0,
   691      "CreateIndex": 7,
   692      "ModifyIndex": 7,
   693      "JobModifyIndex": 7
   694    }
   695  ]
   696  ```
   697  
   698  ## List Job Allocations
   699  
   700  This endpoint reads information about a single job's allocations.
   701  
   702  | Method | Path                          | Produces                   |
   703  | ------ | ----------------------------- | -------------------------- |
   704  | `GET`  | `/v1/job/:job_id/allocations` | `application/json`         |
   705  
   706  The table below shows this endpoint's support for
   707  [blocking queries](/api/index.html#blocking-queries) and
   708  [required ACLs](/api/index.html#acls).
   709  
   710  | Blocking Queries | ACL Required               |
   711  | ---------------- | -------------------------- |
   712  | `YES`            | `namespace:read-job`       |
   713  
   714  ### Parameters
   715  
   716  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
   717    the job file during submission). This is specified as part of the path.
   718  
   719  - `all` `(bool: false)` - Specifies whether the list of allocations should
   720    include allocations from a previously registered job with the same ID. This is
   721    possible if the job is deregistered and reregistered.
   722  
   723  ### Sample Request
   724  
   725  ```text
   726  $ curl \
   727      https://localhost:4646/v1/job/my-job/allocations
   728  ```
   729  
   730  ### Sample Response
   731  
   732  ```json
   733  [
   734    {
   735      "ID": "ed344e0a-7290-d117-41d3-a64f853ca3c2",
   736      "EvalID": "a9c5effc-2242-51b2-f1fe-054ee11ab189",
   737      "Name": "example.cache[0]",
   738      "NodeID": "cb1f6030-a220-4f92-57dc-7baaabdc3823",
   739      "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
   740         "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
   741         "RescheduleTracker": {
   742            "Events": [
   743               {
   744                 "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
   745                 "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
   746                 "RescheduleTime": 1517434161192946200,
   747                 "Delay":5000000000,
   748                },
   749              ]
   750      },
   751      "JobID": "example",
   752      "TaskGroup": "cache",
   753      "DesiredStatus": "run",
   754      "DesiredDescription": "",
   755      "ClientStatus": "running",
   756      "ClientDescription": "",
   757      "TaskStates": {
   758        "redis": {
   759          "State": "running",
   760          "Failed": false,
   761          "StartedAt": "2017-05-25T23:41:23.240184101Z",
   762          "FinishedAt": "0001-01-01T00:00:00Z",
   763          "Events": [
   764            {
   765              "Type": "Received",
   766              "Time": 1495755675956923000,
   767              "FailsTask": false,
   768              "RestartReason": "",
   769              "SetupError": "",
   770              "DriverError": "",
   771              "ExitCode": 0,
   772              "Signal": 0,
   773              "Message": "",
   774              "KillTimeout": 0,
   775              "KillError": "",
   776              "KillReason": "",
   777              "StartDelay": 0,
   778              "DownloadError": "",
   779              "ValidationError": "",
   780              "DiskLimit": 0,
   781              "FailedSibling": "",
   782              "VaultError": "",
   783              "TaskSignalReason": "",
   784              "TaskSignal": "",
   785              "DriverMessage": ""
   786            },
   787            {
   788              "Type": "Task Setup",
   789              "Time": 1495755675957466400,
   790              "FailsTask": false,
   791              "RestartReason": "",
   792              "SetupError": "",
   793              "DriverError": "",
   794              "ExitCode": 0,
   795              "Signal": 0,
   796              "Message": "Building Task Directory",
   797              "KillTimeout": 0,
   798              "KillError": "",
   799              "KillReason": "",
   800              "StartDelay": 0,
   801              "DownloadError": "",
   802              "ValidationError": "",
   803              "DiskLimit": 0,
   804              "FailedSibling": "",
   805              "VaultError": "",
   806              "TaskSignalReason": "",
   807              "TaskSignal": "",
   808              "DriverMessage": ""
   809            },
   810            {
   811              "Type": "Driver",
   812              "Time": 1495755675970286800,
   813              "FailsTask": false,
   814              "RestartReason": "",
   815              "SetupError": "",
   816              "DriverError": "",
   817              "ExitCode": 0,
   818              "Signal": 0,
   819              "Message": "",
   820              "KillTimeout": 0,
   821              "KillError": "",
   822              "KillReason": "",
   823              "StartDelay": 0,
   824              "DownloadError": "",
   825              "ValidationError": "",
   826              "DiskLimit": 0,
   827              "FailedSibling": "",
   828              "VaultError": "",
   829              "TaskSignalReason": "",
   830              "TaskSignal": "",
   831              "DriverMessage": "Downloading image redis:3.2"
   832            },
   833            {
   834              "Type": "Started",
   835              "Time": 1495755683227522000,
   836              "FailsTask": false,
   837              "RestartReason": "",
   838              "SetupError": "",
   839              "DriverError": "",
   840              "ExitCode": 0,
   841              "Signal": 0,
   842              "Message": "",
   843              "KillTimeout": 0,
   844              "KillError": "",
   845              "KillReason": "",
   846              "StartDelay": 0,
   847              "DownloadError": "",
   848              "ValidationError": "",
   849              "DiskLimit": 0,
   850              "FailedSibling": "",
   851              "VaultError": "",
   852              "TaskSignalReason": "",
   853              "TaskSignal": "",
   854              "DriverMessage": ""
   855            }
   856          ]
   857        }
   858      },
   859      "CreateIndex": 9,
   860      "ModifyIndex": 13,
   861      "CreateTime": 1495755675944527600,
   862      "ModifyTime": 1495755675944527600
   863    }
   864  ]
   865  ```
   866  
   867  ## List Job Evaluations
   868  
   869  This endpoint reads information about a single job's evaluations
   870  
   871  | Method | Path                          | Produces                   |
   872  | ------ | ----------------------------- | -------------------------- |
   873  | `GET`  | `/v1/job/:job_id/evaluations` | `application/json`         |
   874  
   875  The table below shows this endpoint's support for
   876  [blocking queries](/api/index.html#blocking-queries) and
   877  [required ACLs](/api/index.html#acls).
   878  
   879  | Blocking Queries | ACL Required               |
   880  | ---------------- | -------------------------- |
   881  | `YES`            | `namespace:read-job`       |
   882  
   883  ### Parameters
   884  
   885  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
   886    the job file during submission). This is specified as part of the path.
   887  
   888  ### Sample Request
   889  
   890  ```text
   891  $ curl \
   892      https://localhost:4646/v1/job/my-job/evaluations
   893  ```
   894  
   895  ### Sample Response
   896  
   897  ```json
   898  [
   899    {
   900      "ID": "a9c5effc-2242-51b2-f1fe-054ee11ab189",
   901      "Priority": 50,
   902      "Type": "service",
   903      "TriggeredBy": "job-register",
   904      "JobID": "example",
   905      "JobModifyIndex": 7,
   906      "NodeID": "",
   907      "NodeModifyIndex": 0,
   908      "Status": "complete",
   909      "StatusDescription": "",
   910      "Wait": 0,
   911      "NextEval": "",
   912      "PreviousEval": "",
   913      "BlockedEval": "",
   914      "FailedTGAllocs": null,
   915      "ClassEligibility": null,
   916      "EscapedComputedClass": false,
   917      "AnnotatePlan": false,
   918      "QueuedAllocations": {
   919        "cache": 0
   920      },
   921      "SnapshotIndex": 8,
   922      "CreateIndex": 8,
   923      "ModifyIndex": 10
   924    }
   925  ]
   926  ```
   927  
   928  ## List Job Deployments
   929  
   930  This endpoint lists a single job's deployments
   931  
   932  | Method | Path                          | Produces                   |
   933  | ------ | ----------------------------- | -------------------------- |
   934  | `GET`  | `/v1/job/:job_id/deployments` | `application/json`         |
   935  
   936  The table below shows this endpoint's support for
   937  [blocking queries](/api/index.html#blocking-queries) and
   938  [required ACLs](/api/index.html#acls).
   939  
   940  | Blocking Queries | ACL Required               |
   941  | ---------------- | -------------------------- |
   942  | `YES`            | `namespace:read-job`       |
   943  
   944  ### Parameters
   945  
   946  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
   947    the job file during submission). This is specified as part of the path.
   948  
   949  ### Sample Request
   950  
   951  ```text
   952  $ curl \
   953      https://localhost:4646/v1/job/my-job/deployments
   954  ```
   955  
   956  ### Sample Response
   957  
   958  ```json
   959  [
   960    {
   961      "ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61",
   962      "JobID": "my-job",
   963      "JobVersion": 1,
   964      "JobModifyIndex": 19,
   965      "JobCreateIndex": 7,
   966      "TaskGroups": {
   967        "cache": {
   968          "AutoRevert": true,
   969          "Promoted": false,
   970          "PlacedCanaries": [
   971            "d0ad0808-2765-abf6-1e15-79fb7fe5a416",
   972            "38c70cd8-81f2-1489-a328-87bb29ec0e0f"
   973          ],
   974          "DesiredCanaries": 2,
   975          "DesiredTotal": 3,
   976          "PlacedAllocs": 2,
   977          "HealthyAllocs": 2,
   978          "UnhealthyAllocs": 0
   979        }
   980      },
   981      "Status": "running",
   982      "StatusDescription": "Deployment is running",
   983      "CreateIndex": 21,
   984      "ModifyIndex": 25
   985    },
   986    {
   987      "ID": "fb6070fb-4a44-e255-4e6f-8213eba3871a",
   988      "JobID": "my-job",
   989      "JobVersion": 0,
   990      "JobModifyIndex": 7,
   991      "JobCreateIndex": 7,
   992      "TaskGroups": {
   993        "cache": {
   994          "AutoRevert": true,
   995          "Promoted": false,
   996          "PlacedCanaries": null,
   997          "DesiredCanaries": 0,
   998          "DesiredTotal": 3,
   999          "PlacedAllocs": 3,
  1000          "HealthyAllocs": 3,
  1001          "UnhealthyAllocs": 0
  1002        }
  1003      },
  1004      "Status": "successful",
  1005      "StatusDescription": "Deployment completed successfully",
  1006      "CreateIndex": 9,
  1007      "ModifyIndex": 17
  1008    }
  1009  ]
  1010  ```
  1011  
  1012  
  1013  ## Read Job's Most Recent Deployment
  1014  
  1015  This endpoint returns a single job's most recent deployment.
  1016  
  1017  | Method | Path                          | Produces                   |
  1018  | ------ | ----------------------------- | -------------------------- |
  1019  | `GET`  | `/v1/job/:job_id/deployment`  | `application/json`         |
  1020  
  1021  The table below shows this endpoint's support for
  1022  [blocking queries](/api/index.html#blocking-queries) and
  1023  [required ACLs](/api/index.html#acls).
  1024  
  1025  | Blocking Queries | ACL Required               |
  1026  | ---------------- | -------------------------- |
  1027  | `YES`            | `namespace:read-job`       |
  1028  
  1029  ### Parameters
  1030  
  1031  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
  1032    the job file during submission). This is specified as part of the path.
  1033  
  1034  ### Sample Request
  1035  
  1036  ```text
  1037  $ curl \
  1038      https://localhost:4646/v1/job/my-job/deployment
  1039  ```
  1040  
  1041  ### Sample Response
  1042  
  1043  ```json
  1044  {
  1045    "ID": "85ee4a9a-339f-a921-a9ef-0550d20b2c61",
  1046    "JobID": "my-job",
  1047    "JobVersion": 1,
  1048    "JobModifyIndex": 19,
  1049    "JobCreateIndex": 7,
  1050    "TaskGroups": {
  1051      "cache": {
  1052        "AutoRevert": true,
  1053        "Promoted": false,
  1054        "PlacedCanaries": [
  1055          "d0ad0808-2765-abf6-1e15-79fb7fe5a416",
  1056          "38c70cd8-81f2-1489-a328-87bb29ec0e0f"
  1057        ],
  1058        "DesiredCanaries": 2,
  1059        "DesiredTotal": 3,
  1060        "PlacedAllocs": 2,
  1061        "HealthyAllocs": 2,
  1062        "UnhealthyAllocs": 0
  1063      }
  1064    },
  1065    "Status": "running",
  1066    "StatusDescription": "Deployment is running",
  1067    "CreateIndex": 21,
  1068    "ModifyIndex": 25
  1069  }
  1070  ```
  1071  
  1072  
  1073  ## Read Job Summary
  1074  
  1075  This endpoint reads summary information about a job.
  1076  
  1077  | Method | Path                       | Produces                   |
  1078  | ------ | -------------------------- | -------------------------- |
  1079  | `GET`  | `/v1/job/:job_id/summary`  | `application/json`         |
  1080  
  1081  The table below shows this endpoint's support for
  1082  [blocking queries](/api/index.html#blocking-queries) and
  1083  [required ACLs](/api/index.html#acls).
  1084  
  1085  | Blocking Queries | ACL Required               |
  1086  | ---------------- | -------------------------- |
  1087  | `YES`            | `namespace:read-job`       |
  1088  
  1089  ### Parameters
  1090  
  1091  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
  1092    the job file during submission). This is specified as part of the path.
  1093  
  1094  ### Sample Request
  1095  
  1096  ```text
  1097  $ curl \
  1098      https://localhost:4646/v1/job/my-job/summary
  1099  ```
  1100  
  1101  ### Sample Response
  1102  
  1103  ```json
  1104  {
  1105    "JobID": "example",
  1106    "Summary": {
  1107      "cache": {
  1108        "Queued": 0,
  1109        "Complete": 0,
  1110        "Failed": 0,
  1111        "Running": 1,
  1112        "Starting": 0,
  1113        "Lost": 0
  1114      }
  1115    },
  1116    "Children": {
  1117      "Pending": 0,
  1118      "Running": 0,
  1119      "Dead": 0
  1120    },
  1121    "CreateIndex": 7,
  1122    "ModifyIndex": 13
  1123  }
  1124  ```
  1125  
  1126  ## Update Existing Job
  1127  
  1128  This endpoint registers a new job or updates an existing job.
  1129  
  1130  | Method  | Path                       | Produces                   |
  1131  | ------- | -------------------------- | -------------------------- |
  1132  | `POST`  | `/v1/job/:job_id`          | `application/json`         |
  1133  
  1134  The table below shows this endpoint's support for
  1135  [blocking queries](/api/index.html#blocking-queries) and
  1136  [required ACLs](/api/index.html#acls).
  1137  
  1138  | Blocking Queries | ACL Required |
  1139  | ---------------- | ------------ |
  1140  | `NO`             | `namespace:submit-job`<br>`namespace:sentinel-override` if `PolicyOverride` set |
  1141  
  1142  ### Parameters
  1143  
  1144  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
  1145    the job file during submission). This is specified as part of the path.
  1146  
  1147  - `Job` `(Job: <required>)` - Specifies the JSON definition of the job.
  1148  
  1149  - `EnforceIndex` `(bool: false)` - If set, the job will only be registered if the
  1150    passed `JobModifyIndex` matches the current job's index. If the index is zero,
  1151    the register only occurs if the job is new. This paradigm allows check-and-set
  1152    style job updating.
  1153  
  1154  - `JobModifyIndex` `(int: 0)` - Specifies the `JobModifyIndex` to enforce the
  1155    current job is at.
  1156  
  1157  - `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
  1158    will be overridden. This allows a job to be registered when it would be denied
  1159    by policy.
  1160  
  1161  ### Sample Payload
  1162  
  1163  ```javascript
  1164  {
  1165    "Job": {
  1166      // ...
  1167    },
  1168    "EnforceIndex": true,
  1169    "JobModifyIndex": 4
  1170  }
  1171  ```
  1172  
  1173  ### Sample Request
  1174  
  1175  ```text
  1176  $ curl \
  1177      --request POST \
  1178      --data @payload.json \
  1179      https://localhost:4646/v1/job/my-job
  1180  ```
  1181  
  1182  ### Sample Response
  1183  
  1184  ```json
  1185  {
  1186    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  1187    "EvalCreateIndex": 35,
  1188    "JobModifyIndex": 34,
  1189  }
  1190  ```
  1191  
  1192  ## Dispatch Job
  1193  
  1194  This endpoint dispatches a new instance of a parameterized job.
  1195  
  1196  | Method  | Path                       | Produces                   |
  1197  | ------- | -------------------------- | -------------------------- |
  1198  | `POST`  | `/v1/job/:job_id/dispatch` | `application/json`         |
  1199  
  1200  The table below shows this endpoint's support for
  1201  [blocking queries](/api/index.html#blocking-queries) and
  1202  [required ACLs](/api/index.html#acls).
  1203  
  1204  | Blocking Queries | ACL Required                   |
  1205  | ---------------- | ------------------------------ |
  1206  | `NO`             | `namespace:dispatch-job`       |
  1207  
  1208  ### Parameters
  1209  
  1210  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified
  1211    in the job file during submission). This is specified as part of the path.
  1212  
  1213  - `Payload` `(string: "")` - Specifies a base64 encoded string containing the
  1214    payload. This is limited to 15 KB.
  1215  
  1216  - `Meta` `(meta<string|string>: nil)` - Specifies arbitrary metadata to pass to
  1217    the job.
  1218  
  1219  ### Sample Payload
  1220  
  1221  ```json
  1222  {
  1223    "Payload": "A28C3==",
  1224    "Meta": {
  1225      "key": "Value"
  1226    }
  1227  }
  1228  ```
  1229  
  1230  ### Sample Request
  1231  
  1232  ```text
  1233  $ curl \
  1234      --request POST \
  1235      --payload @payload.json \
  1236      https://localhost:4646/v1/job/my-job/dispatch
  1237  ```
  1238  
  1239  ### Sample Response
  1240  
  1241  ```json
  1242  {
  1243    "Index": 13,
  1244    "JobCreateIndex": 12,
  1245    "EvalCreateIndex": 13,
  1246    "EvalID": "e5f55fac-bc69-119d-528a-1fc7ade5e02c",
  1247    "DispatchedJobID": "example/dispatch-1485408778-81644024"
  1248  }
  1249  ```
  1250  
  1251  ## Revert to older Job Version
  1252  
  1253  This endpoint reverts the job to an older version.
  1254  
  1255  | Method  | Path                       | Produces                   |
  1256  | ------- | -------------------------- | -------------------------- |
  1257  | `POST`  | `/v1/job/:job_id/revert` | `application/json`         |
  1258  
  1259  The table below shows this endpoint's support for
  1260  [blocking queries](/api/index.html#blocking-queries) and
  1261  [required ACLs](/api/index.html#acls).
  1262  
  1263  | Blocking Queries | ACL Required                 |
  1264  | ---------------- | ---------------------------- |
  1265  | `NO`             | `namespace:submit-job`       |
  1266  
  1267  ### Parameters
  1268  
  1269  - `JobID` `(string: <required>)` - Specifies the ID of the job (as specified
  1270    in the job file during submission). This is specified as part of the path.
  1271  
  1272  - `JobVersion` `(integer: 0)` - Specifies the job version to revert to.
  1273  
  1274  - `EnforcePriorVersion` `(integer: nil)` - Optional value specifying the current
  1275    job's version. This is checked and acts as a check-and-set value before
  1276    reverting to the specified job.
  1277  
  1278  ### Sample Payload
  1279  
  1280  ```json
  1281  {
  1282    "JobID": "my-job",
  1283    "JobVersion": 2,
  1284  }
  1285  ```
  1286  
  1287  ### Sample Request
  1288  
  1289  ```text
  1290  $ curl \
  1291      --request POST \
  1292      --payload @payload.json \
  1293      https://localhost:4646/v1/job/my-job/revert
  1294  ```
  1295  
  1296  ### Sample Response
  1297  
  1298  ```json
  1299  {
  1300    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  1301    "EvalCreateIndex": 35,
  1302    "JobModifyIndex": 34,
  1303  }
  1304  ```
  1305  
  1306  
  1307  ## Set Job Stability
  1308  
  1309  This endpoint sets the job's stability.
  1310  
  1311  | Method  | Path                       | Produces                   |
  1312  | ------- | -------------------------- | -------------------------- |
  1313  | `POST`  | `/v1/job/:job_id/stable`   | `application/json`         |
  1314  
  1315  The table below shows this endpoint's support for
  1316  [blocking queries](/api/index.html#blocking-queries) and
  1317  [required ACLs](/api/index.html#acls).
  1318  
  1319  | Blocking Queries | ACL Required                 |
  1320  | ---------------- | ---------------------------- |
  1321  | `NO`             | `namespace:submit-job`       |
  1322  
  1323  ### Parameters
  1324  
  1325  - `JobID` `(string: <required>)` - Specifies the ID of the job (as specified
  1326    in the job file during submission). This is specified as part of the path.
  1327  
  1328  - `JobVersion` `(integer: 0)` - Specifies the job version to set the stability on.
  1329  
  1330  - `Stable` `(bool: false)` - Specifies whether the job should be marked as
  1331    stable or not.
  1332  
  1333  ### Sample Payload
  1334  
  1335  ```json
  1336  {
  1337    "JobID": "my-job",
  1338    "JobVersion": 2,
  1339    "Stable": true
  1340  }
  1341  ```
  1342  
  1343  ### Sample Request
  1344  
  1345  ```text
  1346  $ curl \
  1347      --request POST \
  1348      --payload @payload.json \
  1349      https://localhost:4646/v1/job/my-job/stable
  1350  ```
  1351  
  1352  ### Sample Response
  1353  
  1354  ```json
  1355  {
  1356    "JobModifyIndex": 34,
  1357  }
  1358  ```
  1359  
  1360  
  1361  ## Create Job Evaluation
  1362  
  1363  This endpoint creates a new evaluation for the given job. This can be used to
  1364  force run the scheduling logic if necessary.
  1365  
  1366  | Method  | Path                       | Produces                   |
  1367  | ------- | -------------------------- | -------------------------- |
  1368  | `POST`  | `/v1/job/:job_id/evaluate` | `application/json`         |
  1369  
  1370  The table below shows this endpoint's support for
  1371  [blocking queries](/api/index.html#blocking-queries) and
  1372  [required ACLs](/api/index.html#acls).
  1373  
  1374  | Blocking Queries | ACL Required               |
  1375  | ---------------- | -------------------------- |
  1376  | `NO`             | `namespace:read-job`       |
  1377  
  1378  ### Parameters
  1379  
  1380  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
  1381    the job file during submission). This is specified as part of the path.
  1382  
  1383  ### Sample Request
  1384  
  1385  ```text
  1386  $ curl \
  1387      --request POST \
  1388      https://localhost:4646/v1/job/my-job/evaluate
  1389  ```
  1390  
  1391  ### Sample Response
  1392  
  1393  ```json
  1394  {
  1395    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  1396    "EvalCreateIndex": 35,
  1397    "JobModifyIndex": 34,
  1398  }
  1399  ```
  1400  
  1401  ## Create Job Plan
  1402  
  1403  This endpoint invokes a dry-run of the scheduler for the job.
  1404  
  1405  | Method  | Path                       | Produces                   |
  1406  | ------- | -------------------------- | -------------------------- |
  1407  | `POST`  | `/v1/job/:job_id/plan`     | `application/json`         |
  1408  
  1409  The table below shows this endpoint's support for
  1410  [blocking queries](/api/index.html#blocking-queries) and
  1411  [required ACLs](/api/index.html#acls).
  1412  
  1413  | Blocking Queries | ACL Required |
  1414  | ---------------- | ------------ |
  1415  | `NO`             | `namespace:submit-job`<br>`namespace:sentinel-override` if `PolicyOverride` set |
  1416  
  1417  ### Parameters
  1418  
  1419  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
  1420  - the job file during submission). This is specified as part of the path.
  1421  
  1422  - `Job` `(string: <required>)` - Specifies the JSON definition of the job.
  1423  
  1424  - `Diff` `(bool: false)` - Specifies whether the diff structure between the
  1425    submitted and server side version of the job should be included in the
  1426    response.
  1427  
  1428  - `PolicyOverride` `(bool: false)` - If set, any soft mandatory Sentinel policies
  1429    will be overridden. This allows a job to be registered when it would be denied
  1430    by policy.
  1431  
  1432  ### Sample Payload
  1433  
  1434  ```json
  1435  {
  1436    "Job": "...",
  1437    "Diff": true,
  1438    "PolicyOverride": false
  1439  }
  1440  ```
  1441  
  1442  ### Sample Request
  1443  
  1444  ```text
  1445  $ curl \
  1446      --request POST \
  1447      --payload @payload.json \
  1448      https://localhost:4646/v1/job/my-job/plan
  1449  ```
  1450  
  1451  ### Sample Response
  1452  
  1453  ```json
  1454  {
  1455    "Index": 0,
  1456    "NextPeriodicLaunch": "0001-01-01T00:00:00Z",
  1457    "Warnings": "",
  1458    "Diff": {
  1459      "Type": "Added",
  1460      "TaskGroups": [
  1461        {
  1462          "Updates": {
  1463            "create": 1
  1464          },
  1465          "Type": "Added",
  1466          "Tasks": [
  1467            {
  1468              "Type": "Added",
  1469              "Objects": [
  1470                "..."
  1471              ],
  1472              "Name": "redis",
  1473              "Fields": [
  1474                {
  1475                  "Type": "Added",
  1476                  "Old": "",
  1477                  "New": "docker",
  1478                  "Name": "Driver",
  1479                  "Annotations": null
  1480                },
  1481                {
  1482                  "Type": "Added",
  1483                  "Old": "",
  1484                  "New": "5000000000",
  1485                  "Name": "KillTimeout",
  1486                  "Annotations": null
  1487                }
  1488              ],
  1489              "Annotations": [
  1490                "forces create"
  1491              ]
  1492            }
  1493          ],
  1494          "Objects": [
  1495            "..."
  1496          ],
  1497          "Name": "cache",
  1498          "Fields": [
  1499            "..."
  1500          ]
  1501        }
  1502      ],
  1503      "Objects": [
  1504        {
  1505          "Type": "Added",
  1506          "Objects": null,
  1507          "Name": "Datacenters",
  1508          "Fields": [
  1509            "..."
  1510          ]
  1511        },
  1512        {
  1513          "Type": "Added",
  1514          "Objects": null,
  1515          "Name": "Constraint",
  1516          "Fields": [
  1517            "..."
  1518          ]
  1519        },
  1520        {
  1521          "Type": "Added",
  1522          "Objects": null,
  1523          "Name": "Update",
  1524          "Fields": [
  1525            "..."
  1526          ]
  1527        }
  1528      ],
  1529      "ID": "example",
  1530      "Fields": [
  1531        "..."
  1532      ]
  1533    },
  1534    "CreatedEvals": [
  1535      {
  1536        "ModifyIndex": 0,
  1537        "CreateIndex": 0,
  1538        "SnapshotIndex": 0,
  1539        "AnnotatePlan": false,
  1540        "EscapedComputedClass": false,
  1541        "NodeModifyIndex": 0,
  1542        "NodeID": "",
  1543        "JobModifyIndex": 0,
  1544        "JobID": "example",
  1545        "TriggeredBy": "job-register",
  1546        "Type": "batch",
  1547        "Priority": 50,
  1548        "ID": "312e6a6d-8d01-0daf-9105-14919a66dba3",
  1549        "Status": "blocked",
  1550        "StatusDescription": "created to place remaining allocations",
  1551        "Wait": 0,
  1552        "NextEval": "",
  1553        "PreviousEval": "80318ae4-7eda-e570-e59d-bc11df134817",
  1554        "BlockedEval": "",
  1555        "FailedTGAllocs": null,
  1556        "ClassEligibility": {
  1557          "v1:7968290453076422024": true
  1558        }
  1559      }
  1560    ],
  1561    "JobModifyIndex": 0,
  1562    "FailedTGAllocs": {
  1563      "cache": {
  1564        "CoalescedFailures": 3,
  1565        "AllocationTime": 46415,
  1566        "Scores": null,
  1567        "NodesEvaluated": 1,
  1568        "NodesFiltered": 0,
  1569        "NodesAvailable": {
  1570          "dc1": 1
  1571        },
  1572        "ClassFiltered": null,
  1573        "ConstraintFiltered": null,
  1574        "NodesExhausted": 1,
  1575        "ClassExhausted": null,
  1576        "DimensionExhausted": {
  1577          "cpu": 1
  1578        }
  1579      }
  1580    },
  1581    "Annotations": {
  1582      "DesiredTGUpdates": {
  1583        "cache": {
  1584          "DestructiveUpdate": 0,
  1585          "InPlaceUpdate": 0,
  1586          "Stop": 0,
  1587          "Migrate": 0,
  1588          "Place": 11,
  1589          "Ignore": 0
  1590        }
  1591      }
  1592    }
  1593  }
  1594  ```
  1595  
  1596  #### Field Reference
  1597  
  1598  - `Diff` - A diff structure between the submitted job and the server side
  1599    version. The top-level object is a Job Diff which contains Task Group Diffs,
  1600    which in turn contain Task Diffs. Each of these objects then has Object and
  1601    Field Diff structures embedded.
  1602  
  1603  - `NextPeriodicLaunch` - If the job being planned is periodic, this field will
  1604    include the next launch time for the job.
  1605  
  1606  - `CreatedEvals` - A set of evaluations that were created as a result of the
  1607    dry-run. These evaluations can signify a follow-up rolling update evaluation
  1608    or a blocked evaluation.
  1609  
  1610  - `JobModifyIndex` - The `JobModifyIndex` of the server side version of this job.
  1611  
  1612  - `FailedTGAllocs` - A set of metrics to understand any allocation failures that
  1613    occurred for the Task Group.
  1614  
  1615  - `Annotations` - Annotations include the `DesiredTGUpdates`, which tracks what
  1616  - the scheduler would do given enough resources for each Task Group.
  1617  
  1618  
  1619  ## Force New Periodic Instance
  1620  
  1621  This endpoint forces a new instance of the periodic job. A new instance will be
  1622  created even if it violates the job's
  1623  [`prohibit_overlap`](/docs/job-specification/periodic.html#prohibit_overlap)
  1624  settings. As such, this should be only used to immediately run a periodic job.
  1625  
  1626  | Method  | Path                             | Produces                   |
  1627  | ------- | -------------------------------- | -------------------------- |
  1628  | `POST`  | `/v1/job/:job_id/periodic/force` | `application/json`         |
  1629  
  1630  The table below shows this endpoint's support for
  1631  [blocking queries](/api/index.html#blocking-queries) and
  1632  [required ACLs](/api/index.html#acls).
  1633  
  1634  | Blocking Queries | ACL Required           |
  1635  | ---------------- | ---------------------- |
  1636  | `NO`             | `namespace:submit-job` |
  1637  
  1638  ### Parameters
  1639  
  1640  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
  1641    the job file during submission). This is specified as part of the path.
  1642  
  1643  ### Sample Request
  1644  
  1645  ```text
  1646  $ curl \
  1647      --request POST \
  1648      https://localhost:4646/v1/job/my-job/periodic/force
  1649  ```
  1650  
  1651  ### Sample Response
  1652  
  1653  ```json
  1654  {
  1655    "EvalCreateIndex": 7,
  1656    "EvalID": "57983ddd-7fcf-3e3a-fd24-f699ccfb36f4"
  1657  }
  1658  ```
  1659  
  1660  ## Stop a Job
  1661  
  1662  This endpoint deregisters a job, and stops all allocations part of it.
  1663  
  1664  | Method   | Path                       | Produces                   |
  1665  | -------- | -------------------------- | -------------------------- |
  1666  | `DELETE` | `/v1/job/:job_id`          | `application/json`         |
  1667  
  1668  The table below shows this endpoint's support for
  1669  [blocking queries](/api/index.html#blocking-queries) and
  1670  [required ACLs](/api/index.html#acls).
  1671  
  1672  | Blocking Queries | ACL Required                 |
  1673  | ---------------- | ---------------------------- |
  1674  | `NO`             | `namespace:submit-job`       |
  1675  
  1676  ### Parameters
  1677  
  1678  - `:job_id` `(string: <required>)` - Specifies the ID of the job (as specified in
  1679    the job file during submission). This is specified as part of the path.
  1680  
  1681  - `Purge` `(bool: false)` - Specifies that the job should stopped and purged
  1682    immediately. This means the job will not be queryable after being stopped. If
  1683    not set, the job will be purged by the garbage collector.
  1684  
  1685  ### Sample Request
  1686  
  1687  ```text
  1688  $ curl \
  1689      --request DELETE \
  1690      https://localhost:4646/v1/job/my-job?purge=true
  1691  ```
  1692  
  1693  ### Sample Response
  1694  
  1695  ```json
  1696  {
  1697    "EvalID": "d092fdc0-e1fd-2536-67d8-43af8ca798ac",
  1698    "EvalCreateIndex": 35,
  1699    "JobModifyIndex": 34,
  1700  }
  1701  ```