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