Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

The Consul CLI and HTTP API

Learn how Consul's CLI wraps the HTTP API: endpoint families, environment variables, tokens, query parameters like stale and dc, and response headers.

Consul has one real interface: an HTTP API under /v1/. The consul command, the web UI and most integrations are clients of that API. Learn its shape once and you can read any Consul tool, script it with curl, or call it from your own code.

The requests below are read-only examples (there is no Consul on this site). Two runnable stand-ins build request URLs and read a sample response.

Endpoint families

Every endpoint starts with /v1/ followed by a family name:

Family Purpose Examples
/v1/agent/... The local agent: its services, checks, members, metrics /v1/agent/services, /v1/agent/service/register
/v1/catalog/... Cluster-wide registry (nodes and services) /v1/catalog/services, /v1/catalog/service/web
/v1/health/... Services with health information /v1/health/service/web?passing
/v1/kv/... Key-value store /v1/kv/app/config/color
/v1/status/... Raft leader and peers /v1/status/leader
/v1/session/... Sessions for locks /v1/session/create
/v1/acl/... Tokens, policies, roles /v1/acl/token
/v1/connect/... Mesh: CA roots, intentions /v1/connect/ca/roots
/v1/operator/... Raft, autopilot, keyring /v1/operator/raft/configuration
/v1/config/... Config entries /v1/config/service-defaults

The agent endpoints act on one machine; catalog and health endpoints query the cluster. You will use both in registering services and the catalog API.

Calling it with curl

Terminal
$ curl http://127.0.0.1:8500/v1/status/leader
$ curl "http://127.0.0.1:8500/v1/catalog/services?pretty"
$ curl --request PUT --data 'blue' http://127.0.0.1:8500/v1/kv/app/color

Rules to remember:

  • Reads are GET. Creating or changing things is PUT (and sometimes POST); removals are DELETE.
  • Bodies are JSON, except the KV store, whose values are raw bytes.
  • Add ?pretty to get indented JSON while exploring.
  • The reply status code carries meaning: 200 success, 404 not found (a missing KV key), 403 permission denied, 429 rate limited.

The CLI wraps the API

Most consul subcommands are thin wrappers, so the knowledge transfers both ways:

Terminal
$ consul kv put app/color blue          # PUT /v1/kv/app/color
$ consul kv get app/color               # GET /v1/kv/app/color
$ consul catalog services               # GET /v1/catalog/services
$ consul services register web.json     # PUT /v1/agent/service/register
$ consul members                        # GET /v1/agent/members

The CLI finds the agent through environment variables:

Variable Meaning
CONSUL_HTTP_ADDR Agent address, such as 127.0.0.1:8500 or https://consul.example.com:8501
CONSUL_HTTP_TOKEN ACL token sent with every request
CONSUL_HTTP_SSL Use TLS when set to true
CONSUL_CACERT CA certificate file used to verify the server
CONSUL_NAMESPACE Namespace (enterprise feature)

Query parameters that matter everywhere

Parameter Effect
dc=dc2 Ask another datacenter
stale Let any server answer: faster, possibly slightly old
consistent Force the leader to confirm it is still leader: slowest, strongest
index=N&wait=30s Blocking query: wait until data changes (see watches)
filter=... Filter results server-side with an expression
near=_agent Sort by network distance from the agent
token=... ACL token (prefer the header)

The default read mode is a middle path: it goes to the leader without the extra confirmation round.

Tokens and response headers

When ACLs are on, send the token in a header, never in a URL where logs might capture it:

Terminal
$ curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
       http://127.0.0.1:8500/v1/catalog/services

Replies include useful headers:

  • X-Consul-Index: a counter that increases when the queried data changes. Blocking queries use it.
  • X-Consul-KnownLeader: whether the answering server knows a leader.
  • X-Consul-LastContact: milliseconds since a follower last heard from the leader (relevant for stale reads).

Stand-in 1: build request URLs

This program builds Consul-style URLs from parameters so you can see how a query is assembled. It does not contact anything.

Python Stand-in: assemble API URLs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: read a sample catalog reply

The JSON below is invented for practice, but its field names mirror what /v1/catalog/service/web returns (Node, Address, ServiceID, ServiceName, ServiceAddress, ServicePort, ServiceTags). Extract what a caller needs.

Python Stand-in: parse a catalog-style reply

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The fallback to the node address is a real Consul convention: if a service has no address of its own, clients use the node's address.

The catalog endpoints return every registered instance regardless of health. To get only working ones, use the /v1/health/service/<name> family with ?passing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which HTTP verb creates or updates a KV entry?

    KV writes use PUT /v1/kv/<key> with the raw value as the body.
  2. 2. How should an ACL token normally be sent to the API?

    A header avoids leaking the token into access logs and browser history.
  3. 3. What does the stale query parameter do?

    Stale reads can be served by followers, so they scale better but may lag slightly.
  4. 4. Which endpoint family should you query to get only healthy instances of a service?

    The health endpoints combine instances with check results; ?passing filters to healthy ones.

Summary

  • Consul's interface is the /v1/ HTTP API; the CLI and UI are clients of it.
  • agent endpoints act on one machine, catalog and health endpoints query the cluster.
  • Set CONSUL_HTTP_ADDR and CONSUL_HTTP_TOKEN so tools find the agent and authenticate.
  • stale, consistent, dc, filter and blocking-query parameters shape reads.
  • Send tokens in the X-Consul-Token header.

Next: Configuring an Agent