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.
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"
}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 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/versionContainers
Networks
Volumes
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
Nodes
Services
Tasks
Secrets
Configs
Operations
/_ping Ping
HEAD/_ping Ping
POST/auth Check auth configuration
POST/build Build an image
POST/build/prune Delete builder cache
POST/commit Create a new image from a container
GET/configs List configs
POST/configs/create Create a config
GET/configs/{id} Inspect a config
DELETE/configs/{id} Delete a config
POST/configs/{id}/update Update a Config
POST/containers/create Create a container
GET/containers/json List containers
POST/containers/prune Delete stopped containers
DELETE/containers/{id} Remove a container
GET/containers/{id}/archive Get an archive of a filesystem resource in a container
PUT/containers/{id}/archive Extract an archive of files or folders to a directory in a container
HEAD/containers/{id}/archive Get information about files in a container
POST/containers/{id}/attach Attach to a container
GET/containers/{id}/attach/ws Attach to a container via a websocket
GET/containers/{id}/changes Get changes on a container’s filesystem
POST/containers/{id}/exec Create an exec instance
GET/containers/{id}/export Export a container
GET/containers/{id}/json Inspect a container
POST/containers/{id}/kill Kill a container
GET/containers/{id}/logs Get container logs
POST/containers/{id}/pause Pause a container
POST/containers/{id}/rename Rename a container
POST/containers/{id}/resize Resize a container TTY
POST/containers/{id}/restart Restart a container
POST/containers/{id}/start Start a container
GET/containers/{id}/stats Get container stats based on resource usage
POST/containers/{id}/stop Stop a container
GET/containers/{id}/top List processes running inside a container
POST/containers/{id}/unpause Unpause a container
POST/containers/{id}/update Update a container
POST/containers/{id}/wait Wait for a container
GET/distribution/{name}/json Get image information from the registry
GET/events Monitor events
GET/exec/{id}/json Inspect an exec instance
POST/exec/{id}/resize Resize an exec instance
POST/exec/{id}/start Start an exec instance
POST/images/create Create an image
GET/images/get Export several images
GET/images/json List Images
POST/images/load Import images
POST/images/prune Delete unused images
GET/images/search Search images
DELETE/images/{name} Remove an image
GET/images/{name}/attestations Get attestation statements for an image
GET/images/{name}/get Export an image
GET/images/{name}/history Get the history of an image
GET/images/{name}/json Inspect an image
POST/images/{name}/push Push an image
POST/images/{name}/tag Tag an image
GET/info Get system information
GET/networks List networks
POST/networks/create Create a network
POST/networks/prune Delete unused networks
GET/networks/{id} Inspect a network
DELETE/networks/{id} Remove a network
POST/networks/{id}/connect Connect a container to a network
POST/networks/{id}/disconnect Disconnect a container from a network
GET/nodes List nodes
GET/nodes/{id} Inspect a node
DELETE/nodes/{id} Delete a node
POST/nodes/{id}/update Update a node
GET/plugins List plugins
POST/plugins/create Create a plugin
GET/plugins/privileges Get plugin privileges
POST/plugins/pull Install a plugin
DELETE/plugins/{name} Remove a plugin
POST/plugins/{name}/disable Disable a plugin
POST/plugins/{name}/enable Enable a plugin
GET/plugins/{name}/json Inspect a plugin
POST/plugins/{name}/push Push a plugin
POST/plugins/{name}/set Configure a plugin
POST/plugins/{name}/upgrade Upgrade a plugin
GET/secrets List secrets
POST/secrets/create Create a secret
GET/secrets/{id} Inspect a secret
DELETE/secrets/{id} Delete a secret
POST/secrets/{id}/update Update a Secret
GET/services List services
POST/services/create Create a service
GET/services/{id} Inspect a service
DELETE/services/{id} Delete a service
GET/services/{id}/logs Get service logs
POST/services/{id}/update Update a service
POST/session Initialize interactive session
GET/swarm Inspect swarm
POST/swarm/init Initialize a new swarm
POST/swarm/join Join an existing swarm
POST/swarm/leave Leave a swarm
POST/swarm/unlock Unlock a locked manager
GET/swarm/unlockkey Get the unlock key
POST/swarm/update Update a swarm
GET/system/df Get data usage information
GET/tasks List tasks
GET/tasks/{id} Inspect a task
GET/tasks/{id}/logs Get task logs
GET/version Get version
GET/volumes List volumes
POST/volumes/create Create a volume
POST/volumes/prune Delete 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 volumeSchemas
AddressAttestationStatementAuthConfigAuthResponseBuildCacheBuildCacheDiskUsageBuildIdentityBuildInfoChangeTypeClusterInfoClusterVolumeClusterVolumeSpecCommitConfigConfigReferenceConfigSpecContainerBlkioStatEntryContainerBlkioStatsContainerCPUStatsContainerCPUUsageContainerConfigContainerCreateResponseContainerInspectResponseContainerMemoryStatsContainerNetworkStatsContainerPidsStatsContainerStateContainerStatsResponseContainerStatusContainerStorageStatsContainerSummaryContainerThrottlingDataContainerTopResponseContainerUpdateResponseContainerWaitExitErrorContainerWaitResponseContainerdInfoContainersDiskUsageCreateImageInfoDeviceInfoDeviceMappingDeviceRequestDistributionInspectDriverDriverDataEndpointIPAMConfigEndpointPortConfigEndpointResourceEndpointSettingsEndpointSpecEngineDescriptionErrorDetailErrorResponseEventActorEventMessageFilesystemChangeFirewallInfoGenericResourcesHealthHealthConfigHealthcheckResultHostConfigIDResponseIPAMIPAMConfigIPAMStatusIdentityImageConfigImageDeleteResponseItemImageHistoryResponseItemImageIDImageInspectImageManifestSummaryImageSummaryImagesDiskUsageIndexInfoJoinTokensKnownSignerIdentityLimitLocalNodeStateManagerStatusMountMountPointMountTypeNRIInfoNetworkNetworkAttachmentNetworkAttachmentConfigNetworkConnectRequestNetworkCreateResponseNetworkDisconnectRequestNetworkInspectNetworkSettingsNetworkStatusNetworkSummaryNetworkTaskInfoNetworkingConfigNodeNodeDescriptionNodeSpecNodeStateNodeStatusOCIDescriptorOCIPlatformObjectVersionPeerInfoPeerNodePlatformPluginPluginDevicePluginEnvPluginMountPluginPrivilegePluginsInfoPortBindingPortMapPortStatusPortSummaryProcessConfigProgressDetailPullIdentityPushImageInfoReachabilityRegistryServiceConfigResourceObjectResourcesRestartPolicyRootFSStorageRootFSStorageSnapshotRuntimeSecretSecretSpecServiceServiceCreateResponseServiceInfoServiceSpecServiceUpdateResponseSignatureIdentitySignatureTimestampSignatureTimestampTypeSignatureTypeSignerIdentityStorageSubnetStatusSwarmSwarmInfoSwarmSpecSystemInfoSystemVersionTLSInfoTaskTaskSpecTaskStateTaskStatusThrottleDeviceTopologyVolumeVolumeCreateRequestVolumeListResponseVolumesDiskUsage