API surface

Consul exposes three API protocols:

Protocol	Port (default)	Used by
HTTP	8500 (TLS: 8501)	CLI, Ember UI, integrations, language SDKs
DNS	8600	Any application; the most common service-discovery channel
gRPC	8502 (TLS: 8503)	Envoy (xDS), Consul Dataplane, public proto-public services

This page is the rough map. For deep dives see the canonical operator documentation at https://developer.hashicorp.com/consul/api-docs.

HTTP API

Every endpoint is registered in agent/http_register.go and implemented in a *_endpoint.go file alongside it. The base URL is /v1/....

Endpoint families

Prefix	Provided by
/v1/acl/...	agent/acl_endpoint.go
/v1/agent/...	agent/agent_endpoint.go
/v1/catalog/...	agent/catalog_endpoint.go
/v1/config/...	agent/config_endpoint.go
/v1/connect/ca/...	agent/connect_ca_endpoint.go
/v1/connect/intentions/...	agent/intentions_endpoint.go
/v1/coordinate/...	agent/coordinate_endpoint.go
/v1/discovery-chain/...	agent/discovery_chain_endpoint.go
/v1/event/...	agent/event_endpoint.go
/v1/exported-services, /v1/imported-services	agent/agent_endpoint.go
/v1/health/...	agent/health_endpoint.go
/v1/internal/federation-states/...	agent/federation_state_endpoint.go
/v1/internal/ui/...	agent/ui_endpoint.go
/v1/kv/...	agent/kvs_endpoint.go
/v1/operator/...	agent/operator_endpoint.go
/v1/peering/...	agent/peering_endpoint.go
/v1/query/...	agent/prepared_query_endpoint.go
/v1/session/...	agent/session_endpoint.go
/v1/snapshot	agent/snapshot_endpoint.go
/v1/status/...	agent/status_endpoint.go
/v1/txn	agent/txn_endpoint.go
/v1/agent/connect/authorize, /v1/agent/connect/ca/...	agent/agent_endpoint.go (Connect bits)
/api/.../v2/...	V2 resource API; routed through gRPC under the hood

Common conventions

• Authentication: X-Consul-Token header (preferred), ?token= query string (deprecated), or environment variables on the CLI side.
• Datacenter selection: ?dc=<name>. WAN federation forwards the request.
• Namespace / Partition (Enterprise): ?ns=<name>, ?partition=<name>.
• Blocking queries: ?index=<n>&wait=<duration>. Returns when the index changes or after wait (max 10m).
• Filtering: ?filter=<expr> on most read endpoints. Filter language defined in agent/structs/filter.go.
• Pretty output: ?pretty indents JSON.
• Stale reads: ?stale allows non-leader servers to answer.

Headers returned on every read

• X-Consul-Index — current Raft index for the data; pass back as ?index= to long-poll.
• X-Consul-LastContact — time since the responding server last saw the leader.
• X-Consul-KnownLeader — true if a leader is known to the responding server.
• X-Consul-Default-ACL-Policy — allow or deny, the cluster default.

Error responses

agent/http.go ((*HTTPHandlers).wrap) maps Go errors to HTTP statuses:

• acl.ErrPermissionDenied → 403
• structs.ErrNoLeader → 500 with body
• Validation errors → 400 with body
• Default → 500

DNS API

Run on UDP+TCP port 8600. See DNS interface for the full request format. The high-level shape:

Pattern	Resolves to
<service>.service.consul	Healthy instances of the service
<service>.service.<dc>.consul	Same, in a non-local DC
<tag>.<service>.service.consul	Filtered by tag
<service>.connect.consul	Connect proxies for the service
<service>.virtual.consul	Synthetic mesh-internal virtual IP
<service>.query.consul	Prepared query
<node>.node.consul	Node addresses
_<svc>._tcp.service.consul	RFC 2782 SRV style

DNS responses include both A/AAAA records and SRV records (when asked) so port information is available.

gRPC API

The agent runs a gRPC server on 8502 (or 8503 with TLS). Two flavors:

Internal services

• The internal RPC, implemented over the same TCP port via prefix multiplexing in agent/consul/rpc.go. Used for Consul-to-Consul traffic.
• Internal gRPC services like the streaming subscribe backend (pbsubscribe).

External services (under proto-public/)

Service	Path	Purpose
pbresource.ResourceService	/hashicorp.consul.resource.ResourceService/*	Generic v2 resource CRUD + Watch
pbconnectca.ConnectCAService		Sign leaf certs, watch CA roots
pbacl.ACLService		Login/logout, token issuance for non-CLI clients
pbdataplane.DataplaneService		Dataplane bootstrap parameters and feature negotiation
pbdns.DNSService		DNS-over-gRPC
pbserverdiscovery.ServerDiscoveryService		Watch authoritative server set (used by dataplane to find servers)

Server-side handlers live in agent/grpc-external/services/<x>/. Schemas in proto-public/.

Envoy xDS

Envoy proxies (sidecars and gateways) connect to the agent's xDS gRPC service on the same port. Implementation: agent/xds/. See xDS server.

Authentication and TLS

• HTTP and gRPC can be served over TLS independently. Configuration: tls.defaults, tls.https, tls.grpc, tls.internal_rpc blocks in agent config.
• mTLS is enforced when verify_incoming is set; clients must present a CA-signed cert.
• ACL token gets attached at every request; resolution is cached on the agent (acl/acl_cache.go).

Public Go client

api/ (in this repo) wraps the HTTP API. See Packages → api. The CLI uses it; external Go consumers should import it via:

import "github.com/hashicorp/consul/api"

Versioning

• The HTTP API has been stable since 1.0; new fields are additive. Removed endpoints are vanishingly rare and announced in the changelog.
• The gRPC public API is versioned per service (pbresource.v1 style); breaking changes go through major versions.
• The Envoy xDS resource shapes are tightly tied to a range of supported Envoy versions listed in envoyextensions/xdscommon/ENVOY_VERSIONS.