Docker Engine API
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…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
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 asX-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..."
}Endpoints 108
Container
- GETList containers
/containers/json?all=false&limit=0&size=false&filters=stringReturns a list of containers. For details on the format, see the inspect endpoint. Note that it uses a different, smaller representation of a container than… - POSTCreate a container
/containers/create?name=string&platform= - GETInspect a container
/containers/:id/json?size=falseReturn low-level information about a container. - GETList processes running inside a container
/containers/:id/top?ps_args=-efOn Unix systems, this is done by running the ps command. This endpoint is not supported on Windows. - GETGet container logs
/containers/:id/logs?follow=false&stdout=false&stderr=false&since=0&until=0×tamps=false&tail=allGet stdout and stderr logs from a container. Note: This endpoint works only for containers with the json-file or journald logging driver. - GETGet changes on a container’s filesystem
/containers/:id/changesReturns which files in a container's filesystem have been added, deleted, or modified. The Kind of modification can be one of: 0: Modified ("C") 1: Added… - GETExport a container
/containers/:id/exportExport the contents of a container as a tarball. - GETGet container stats based on resource usage
/containers/:id/stats?stream=true&one-shot=falseThis endpoint returns a live stream of a container’s resource usage statistics. The precpu_stats is the CPU statistic of the *previous* read, and is used to… - POSTResize a container TTY
/containers/:id/resize?h=0&w=0Resize the TTY for a container. - POSTStart a container
/containers/:id/start?detachKeys=string - POSTStop a container
/containers/:id/stop?signal=string&t=0 - POSTRestart a container
/containers/:id/restart?signal=string&t=0 - POSTKill a container
/containers/:id/kill?signal=SIGKILLSend a POSIX signal to a container, defaulting to killing to the container. - POSTUpdate a container
/containers/:id/updateChange various configuration options of a container without having to recreate it. - POSTRename a container
/containers/:id/rename?name=string - POSTPause a container
/containers/:id/pauseUse the freezer cgroup to suspend all processes in a container. Traditionally, when suspending a process the SIGSTOP signal is used, which is observable by… - POSTUnpause a container
/containers/:id/unpauseResume a container which has been paused. - POSTAttach to a container
/containers/:id/attach?detachKeys=string&logs=false&stream=false&stdin=false&stdout=false&stderr=falseAttach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have… - GETAttach to a container via a websocket
/containers/:id/attach/ws?detachKeys=string&logs=false&stream=false&stdin=false&stdout=false&stderr=false - POSTWait for a container
/containers/:id/wait?condition=not-runningBlock until a container stops, then returns the exit code. - DELETERemove a container
/containers/:id?v=false&force=false&link=false - GETGet an archive of a filesystem resource in a container
/containers/:id/archive?path=stringGet a tar archive of a resource in the filesystem of container id. - PUTExtract an archive of files or folders to a directory in a container
/containers/:id/archive?path=string&noOverwriteDirNonDir=string©UIDGID=stringUpload a tar archive to be extracted to a path in the filesystem of container id. path parameter is asserted to be a directory. If it exists as a file, 400… - HEADGet information about files in a container
/containers/:id/archive?path=stringA response header X-Docker-Container-Path-Stat is returned, containing a base64 - encoded JSON object with some filesystem header information about the path. - POSTDelete stopped containers
/containers/prune?filters=string
Image
- GETList Images
/images/json?all=false&filters=string&shared-size=false&digests=false&manifests=false&identity=falseReturns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image. - POSTBuild an image
/build?dockerfile=Dockerfile&t=string&extrahosts=string&remote=string&q=false&nocache=false&cachefrom=string&pull=string&rm=true&forcerm=false&memory=0&memswap=0&cpushares=0&cpusetcpus=string&cpuperiod=0&cpuquota=0&buildargs=string&shmsize=0&squash=true&labels=string&networkmode=string&platform=&target=&outputs=&version=1Build an image from a tar archive with a Dockerfile in it. The Dockerfile specifies how the image is built from the tar archive. It is typically in the… - POSTDelete builder cache
/build/prune?reserved-space=0&max-used-space=0&min-free-space=0&all=true&filters=string - POSTCreate an image
/images/create?fromImage=string&fromSrc=string&repo=string&tag=string&message=string&changes=string&platform=Pull or import an image. - GETInspect an image
/images/:name/json?manifests=false&platform=stringReturn low-level information about an image. - GETGet attestation statements for an image
/images/:name/attestations?platform=string&type=string&statement=falseReturn the in-toto attestation statements attached to the image for the given platform. The daemon locates the attestation manifest(s) that reference the… - GETGet the history of an image
/images/:name/history?platform=stringReturn parent layers of an image. - POSTPush an image
/images/:name/push?tag=string&platform=stringPush an image to a registry. If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For… - POSTTag an image
/images/:name/tag?repo=string&tag=stringCreate a tag that refers to a source image. This creates an additional reference (tag) to the source image. The tag can include a different repository name… - DELETERemove an image
/images/:name?force=false&noprune=false&platforms=stringRemove an image, along with any untagged parent images that were referenced by that image. Images can't be removed if they have descendant images, are being… - GETSearch images
/images/search?term=string&limit=0&filters=stringSearch for an image on Docker Hub. - POSTDelete unused images
/images/prune?filters=string - POSTCreate a new image from a container
/commit?container=string&repo=string&tag=string&comment=string&author=string&pause=true&changes=string - GETExport an image
/images/:name/get?platform=stringGet a tarball containing all images and metadata for a repository. If name is a specific name and tag (e.g. ubuntu:latest), then only that image (and its… - GETExport several images
/images/get?names=string&platform=stringGet a tarball containing all images and metadata for several image repositories. For each value of the names parameter: if it is a specific name and tag (e.g.… - POSTImport images
/images/load?quiet=false&platform=stringLoad a set of images and tags into a repository. For details on the format, see the export image endpoint.
Network
- GETList networks
/networks?filters=stringReturns a list of networks. For details on the format, see the network inspect endpoint. Note that it uses a different, smaller representation of a network… - GETInspect a network
/networks/:id?verbose=false&scope=string - DELETERemove a network
/networks/:id - POSTCreate a network
/networks/create - POSTConnect a container to a network
/networks/:id/connectThe network must be either a local-scoped network or a swarm-scoped network with the attachable option set. A network cannot be re-attached to a running… - POSTDisconnect a container from a network
/networks/:id/disconnect - POSTDelete unused networks
/networks/prune?filters=string
Volume
- GETList volumes
/volumes?filters=string - POSTCreate a volume
/volumes/create - GETInspect a volume
/volumes/:name - PUT"Update a volume. Valid only for Swarm cluster volumes"
/volumes/:name?version=0 - DELETERemove a volume
/volumes/:name?force=falseInstruct the driver to remove the volume. - POSTDelete unused volumes
/volumes/prune?filters=string
Exec
- POSTCreate an exec instance
/containers/:id/execRun a command inside a running container. - POSTStart an exec instance
/exec/:id/startStarts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an… - POSTResize an exec instance
/exec/:id/resize?h=0&w=0Resize the TTY session used by an exec instance. This endpoint only works if tty was specified as part of creating and starting the exec instance. - GETInspect an exec instance
/exec/:id/jsonReturn low-level information about an exec instance.
Swarm
- GETInspect swarm
/swarm - POSTInitialize a new swarm
/swarm/init - POSTJoin an existing swarm
/swarm/join - POSTLeave a swarm
/swarm/leave?force=false - POSTUpdate a swarm
/swarm/update?version=0&rotateWorkerToken=false&rotateManagerToken=false&rotateManagerUnlockKey=false - GETGet the unlock key
/swarm/unlockkey - POSTUnlock a locked manager
/swarm/unlock
Node
- GETList nodes
/nodes?filters=string - GETInspect a node
/nodes/:id - DELETEDelete a node
/nodes/:id?force=false - POSTUpdate a node
/nodes/:id/update?version=0
Service
- GETList services
/services?filters=string&status=true - POSTCreate a service
/services/create - GETInspect a service
/services/:id?insertDefaults=false - DELETEDelete a service
/services/:id - POSTUpdate a service
/services/:id/update?version=0®istryAuthFrom=spec&rollback=string - GETGet service logs
/services/:id/logs?details=false&follow=false&stdout=false&stderr=false&since=0×tamps=false&tail=allGet stdout and stderr logs from a service. See also /containers/{id}/logs. Note: This endpoint works only for services with the local, json-file or journald…
Task
- GETList tasks
/tasks?filters=string - GETInspect a task
/tasks/:id - GETGet task logs
/tasks/:id/logs?details=false&follow=false&stdout=false&stderr=false&since=0×tamps=false&tail=allGet stdout and stderr logs from a task. See also /containers/{id}/logs. Note: This endpoint works only for services with the local, json-file or journald…
Secret
- GETList secrets
/secrets?filters=string - POSTCreate a secret
/secrets/create - GETInspect a secret
/secrets/:id - DELETEDelete a secret
/secrets/:id - POSTUpdate a Secret
/secrets/:id/update?version=0
Config
- GETList configs
/configs?filters=string - POSTCreate a config
/configs/create - GETInspect a config
/configs/:id - DELETEDelete a config
/configs/:id - POSTUpdate a Config
/configs/:id/update?version=0
Plugin
- GETList plugins
/plugins?filters=stringReturns information about installed plugins. - GETGet plugin privileges
/plugins/privileges?remote=string - POSTInstall a plugin
/plugins/pull?remote=string&name=stringPulls and installs a plugin. After the plugin is installed, it can be enabled using the POST /plugins/{name}/enable endpoint. - GETInspect a plugin
/plugins/:name/json - DELETERemove a plugin
/plugins/:name?force=false - POSTEnable a plugin
/plugins/:name/enable?timeout=0 - POSTDisable a plugin
/plugins/:name/disable?force=true - POSTUpgrade a plugin
/plugins/:name/upgrade?remote=string - POSTCreate a plugin
/plugins/create?name=string - POSTPush a plugin
/plugins/:name/pushPush a plugin to the registry. - POSTConfigure a plugin
/plugins/:name/set
System
- POSTCheck auth configuration
/authValidate credentials for a registry and, if available, get an identity token for accessing the registry without password. - GETGet system information
/info - GETGet version
/versionReturns the version of Docker that is running and various information about the system that Docker is running on. - GETPing
/_pingThis is a dummy endpoint you can use to test if the server is accessible. - HEADPing
/_pingThis is a dummy endpoint you can use to test if the server is accessible. - GETMonitor events
/events?since=string&until=string&filters=stringStream real-time events from the server. Various objects within Docker report events when something happens to them. Containers report these events: attach,… - GETGet data usage information
/system/df?type=container&verbose=false
Distribution
- GETGet image information from the registry
/distribution/:name/jsonReturn image digest and platform information by contacting the registry.
Session
- POSTInitialize interactive session
/sessionStart a new interactive session with a server. Session allows server to call back to the client for advanced capabilities. > Deprecated: This endpoint is…
API details
- Authentication
- None declared in the description
- Operations
- 108 operations on 98 pathsPOST 51GET 44DELETE 9PUT 2HEAD 2
- Main resources
- Container 25Image 16Plugin 11Network 7Swarm 7System 7Service 6Volume 6Config 5Secret 5
- Response formats
application/jsontext/plain- Description format
- Swagger 2.0, API version
1.57 - Links
- OpenAPI document
- Listed from
- Docker Engine (Moby)'s published OpenAPI description (moby/moby) (Apache-2.0)
How to test the Docker Engine API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Docker Engine API collection, without the publisher's secrets.
- Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
- Send a requestPick an endpoint, for example “List containers” (GET /containers/json?all=false&limit=0&size=false&filters=string), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Docker Engine API?
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… It is listed under Developer tools and has 108 endpoints.
Who publishes the Docker Engine API?
It is listed from Docker's public API description (an OpenAPI document), not published by Docker on Swastik Codes. Anyone who controls docker.com can claim the profile by adding a DNS TXT record.
How do I authenticate with the Docker Engine API?
Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.
How many endpoints does the Docker Engine API have?
108 operations on 98 paths (51 POST, 44 GET, 9 DELETE, 2 PUT, 2 HEAD). The largest groups are Container, Image, Plugin, Network.
Is forking the Docker Engine API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.