API

The Engine API is the HTTP API the daemon exposes. It's the contract between the Docker CLI, third-party tooling, the client Go module, and the daemon itself.

The wire definition is api/swagger.yaml. This page summarizes the surface; for the canonical reference, render the swagger or use make swagger-docs.

Per-version differences are tracked in api/docs/CHANGELOG.md. Version constants and the comparison helpers live in daemon/internal/versions/. The minimum supported API version is enforced by the version middleware.

Versioning

Every endpoint is mounted twice: at /v{version}/path and at /path. Handlers can vary behavior per version by reading the version mux variable.

Constant	Value (current)
Default API version	Latest the daemon supports; bumped per release. See api/types/common/.
Min API version	1.24 historically. Lower versions get a plain-text "API version too old" error from the server dispatcher.

Endpoint groups

Group	Path prefix	Router
System	/_ping, /info, /version, /auth, /events, /df	router/system/
Containers	/containers/..., /exec/...	router/container/
Images	/images/..., /distribution/...	router/image/
Build	/build, /build/prune, /build/cancel	router/build/
Networks	/networks/...	router/network/
Volumes	/volumes/...	router/volume/
Plugins	/plugins/...	router/plugin/
Swarm	/swarm, /services, /tasks, /nodes, /secrets, /configs	router/swarm/
Session	/session (hijacked HTTP/2)	router/session/
gRPC	/grpc (BuildKit gRPC over HTTP/2)	router/grpc/
Checkpoint	/containers/{id}/checkpoints/... (experimental)	router/checkpoint/
Debug	/debug/pprof/... (when --debug)	router/debug/

For the request lifecycle and middleware chain, see API server.

Streaming endpoints

A subset of the API streams responses:

• Chunked JSON lines — /images/create (pull), /images/{name}/push, /build, /events. Each chunk is a JSON object; the schema is in api/types/jsonstream/.
• Hijacked TCP — /containers/{name}/attach, /exec/{id}/start, /session. The HTTP connection is upgraded and the daemon hands the raw bytes back and forth.
• Server-sent JSON — /containers/{id}/stats, /containers/{id}/logs?follow=1. Long-poll JSON streams.

Error format

Errors are returned as JSON common.ErrorResponse (see api/types/common/) with the appropriate HTTP status code:

{ "message": "No such container: foo" }

The status code is derived from errdefs predicates; see daemon/server/httpstatus/ and Patterns and conventions.

Filters

Many list endpoints accept a filters query parameter — a URL-encoded JSON map from filter name to allowed values. The evaluator is in daemon/internal/filters/; the wire encoding helpers are in api/types/filters/.

Editing the API

See Development workflow for the full editing flow. Short version:

1. Update api/swagger.yaml.
2. Update or add types in api/types/<group>/.
3. Update the router and the backend interface.
4. Add an integration test under integration/<group>/.
5. Update api/docs/CHANGELOG.md.
6. Run make validate-swagger and make test-integration.