HTTP API

The main interface to Nomad is a RESTful HTTP API. The API can query the current state of the system as well as modify the state of the system. The Nomad CLI actually invokes Nomad's HTTP for many commands.

Version Prefix

All API routes are prefixed with /v1/.

Addressing and Ports

Nomad binds to a specific set of addresses and ports. The HTTP API is served via the http address and port. This address:port must be accessible locally. If you bind to 127.0.0.1:4646, the API is only available from that host. If you bind to a private internal IP, the API will be available from within that network. If you bind to a public IP, the API will be available from the public Internet (not recommended).

The default port for the Nomad HTTP API is 4646. This can be overridden via the Nomad configuration block. Here is an example curl request to query a Nomad server with the default configuration:

$ curl http://127.0.0.1:4646/v1/agent/members

The conventions used in the API documentation do not list a port and use the standard URL localhost:4646. Be sure to replace this with your Nomad agent URL when using the examples.

Data Model and Layout

There are five primary nouns in Nomad:

• jobs
• nodes
• allocations
• deployments
• evaluations