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