Search or ask Docker

Docker Engine API v1.57 reference

Reference documentation for Docker Engine API v1.57, including endpoints, schemas, and examples.

View Markdown

User-operated API

API 1.57 · 108 operations · 160 named schemas

Overview

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. docker ps is GET /containers/json). The notable exception is running containers, which consists of several API calls.

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "message": "page not found"
}
Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call /v1.30/info to use the v1.30 version of the /info endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP 400 Bad Request error message is returned.

If you omit the version-prefix, the current version of the API is used. For example, calling /info is the same as calling /v1.57/info. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means the server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as POST /images/(name)/push. These are sent as X-Registry-Auth header as a base64url encoded (JSON) string with the following structure:

{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}

The serveraddress is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the /auth endpoint, you can just pass this instead of credentials:

{
  "identitytoken": "9cbaf023786cd7..."
}

Connecting to Docker Engine

curl --unix-socket /var/run/docker.sock http://localhost/v1.57/version

Develop with Docker Engine SDKs

Containers

Create and manage containers.

Networks

Networks are user-defined networks that containers can be attached to. See the networking documentation for more information.

Volumes

Create and manage persistent storage that can be attached to containers.

Exec

Run new commands inside running containers. Refer to the command-line reference for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, docker exec.

Swarm

Engines can be clustered together in a swarm. Refer to the swarm mode documentation for more information.

Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

Operations

GET/_pingPing HEAD/_pingPing POST/authCheck auth configuration POST/buildBuild an image POST/build/pruneDelete builder cache POST/commitCreate a new image from a container GET/configsList configs POST/configs/createCreate a config GET/configs/{id}Inspect a config DELETE/configs/{id}Delete a config POST/configs/{id}/updateUpdate a Config POST/containers/createCreate a container GET/containers/jsonList containers POST/containers/pruneDelete stopped containers DELETE/containers/{id}Remove a container GET/containers/{id}/archiveGet an archive of a filesystem resource in a container PUT/containers/{id}/archiveExtract an archive of files or folders to a directory in a container HEAD/containers/{id}/archiveGet information about files in a container POST/containers/{id}/attachAttach to a container GET/containers/{id}/attach/wsAttach to a container via a websocket GET/containers/{id}/changesGet changes on a container’s filesystem POST/containers/{id}/execCreate an exec instance GET/containers/{id}/exportExport a container GET/containers/{id}/jsonInspect a container POST/containers/{id}/killKill a container GET/containers/{id}/logsGet container logs POST/containers/{id}/pausePause a container POST/containers/{id}/renameRename a container POST/containers/{id}/resizeResize a container TTY POST/containers/{id}/restartRestart a container POST/containers/{id}/startStart a container GET/containers/{id}/statsGet container stats based on resource usage POST/containers/{id}/stopStop a container GET/containers/{id}/topList processes running inside a container POST/containers/{id}/unpauseUnpause a container POST/containers/{id}/updateUpdate a container POST/containers/{id}/waitWait for a container GET/distribution/{name}/jsonGet image information from the registry GET/eventsMonitor events GET/exec/{id}/jsonInspect an exec instance POST/exec/{id}/resizeResize an exec instance POST/exec/{id}/startStart an exec instance POST/images/createCreate an image GET/images/getExport several images GET/images/jsonList Images POST/images/loadImport images POST/images/pruneDelete unused images GET/images/searchSearch images DELETE/images/{name}Remove an image GET/images/{name}/attestationsGet attestation statements for an image GET/images/{name}/getExport an image GET/images/{name}/historyGet the history of an image GET/images/{name}/jsonInspect an image POST/images/{name}/pushPush an image POST/images/{name}/tagTag an image GET/infoGet system information GET/networksList networks POST/networks/createCreate a network POST/networks/pruneDelete unused networks GET/networks/{id}Inspect a network DELETE/networks/{id}Remove a network POST/networks/{id}/connectConnect a container to a network POST/networks/{id}/disconnectDisconnect a container from a network GET/nodesList nodes GET/nodes/{id}Inspect a node DELETE/nodes/{id}Delete a node POST/nodes/{id}/updateUpdate a node GET/pluginsList plugins POST/plugins/createCreate a plugin GET/plugins/privilegesGet plugin privileges POST/plugins/pullInstall a plugin DELETE/plugins/{name}Remove a plugin POST/plugins/{name}/disableDisable a plugin POST/plugins/{name}/enableEnable a plugin GET/plugins/{name}/jsonInspect a plugin POST/plugins/{name}/pushPush a plugin POST/plugins/{name}/setConfigure a plugin POST/plugins/{name}/upgradeUpgrade a plugin GET/secretsList secrets POST/secrets/createCreate a secret GET/secrets/{id}Inspect a secret DELETE/secrets/{id}Delete a secret POST/secrets/{id}/updateUpdate a Secret GET/servicesList services POST/services/createCreate a service GET/services/{id}Inspect a service DELETE/services/{id}Delete a service GET/services/{id}/logsGet service logs POST/services/{id}/updateUpdate a service POST/sessionInitialize interactive session GET/swarmInspect swarm POST/swarm/initInitialize a new swarm POST/swarm/joinJoin an existing swarm POST/swarm/leaveLeave a swarm POST/swarm/unlockUnlock a locked manager GET/swarm/unlockkeyGet the unlock key POST/swarm/updateUpdate a swarm GET/system/dfGet data usage information GET/tasksList tasks GET/tasks/{id}Inspect a task GET/tasks/{id}/logsGet task logs GET/versionGet version GET/volumesList volumes POST/volumes/createCreate a volume POST/volumes/pruneDelete unused volumes GET/volumes/{name}Inspect a volume PUT/volumes/{name}"Update a volume. Valid only for Swarm cluster volumes" DELETE/volumes/{name}Remove a volume

Schemas