Docker-Client
view release on metacpan or search on metacpan
lib/Docker/Client.pm view on Meta::CPAN
use File::ShareDir qw( dist_dir );
use Mojo::File;
use Mojo::URL;
our $VERSION = '0.1.1';
class_type 'Mojo::URL';
coerce 'Mojo::URL', from 'Str', via { Mojo::URL->new(shift) };
has 'endpoint' => (
is => 'ro',
isa => 'Mojo::URL',
default => sub {
return Mojo::URL->new('http+unix://%2Fvar%2Frun%2Fdocker.sock');
},
coerce => 1,
);
has 'version' => (
is => 'ro',
lib/Docker/Client.pm view on Meta::CPAN
has 'api' => (
is => 'ro',
isa => 'OpenAPI::Client',
lazy => 1,
default => sub {
my $self = shift;
## Making sure we use the correct version path
my $base_url =
$self->endpoint()->clone()->path( sprintf '/%s', $self->version() );
## Loading correct version specification from disk.
my $spec =
Mojo::File->new( dist_dir('Docker-Client') )->child('specs')
->child( sprintf '%s.yaml', $self->version() );
## Creating the OpenAPI Client instance using the defined parameters.
my $api =
OpenAPI::Client->new( $spec->to_string(),
base_url => $self->endpoint() );
## If the protocol is local we need to replace the "Host" header on each request
if ( $self->endpoint()->protocol() eq 'http+unix' ) {
$api->ua()->on(
start => sub {
my ( $ua, $tx ) = @_;
$tx->req()->headers()->header( 'Host' => 'localhost' );
}
);
}
return $api;
lib/Docker/Client.pod view on Meta::CPAN
=head1 DESCRIPTION
This module is built on top of L<OpenAPI::Client> and the official OpenAPI specifications from docker.com. It supports multiple versions of Docker API, and in the local context, it doesn't require exposing the Docker API server on a TCP socket as it ...
Under the hood the all requests are handled by a L<Mojo::UserAgent> instance, which is highly configurable.
This module is B<EXPERIMENTAL>, the methods are subject to change. In the future, I might hide all API calls under custom-methods implementations to resemble a high-level API; also, I welcome any suggestions.
=head1 ATTRIBUTES
=head2 endpoint
The Docker REST endpoint. Defaults to 'http+unix://var/run/docker.sock'.
=head2 version
The Docker OpenAPI spec version. Defaults to 'v1.40', lower value supported is 'v1.25'.
=head2 ua
The L<Mojo::UserAgent> object used to perform the requests.
=head1 METHODS
share/specs/v1.25.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.25"
info:
title: "Docker Engine API"
version: "1.25"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.25.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.25.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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`.
- name: "Secret"
x-displayName: "Secrets"
# Swarm things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.25.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
IPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
type: "string"
IPv6Address:
type: "string"
LinkLocalIPs:
type: "array"
items:
type: "string"
share/specs/v1.25.yaml view on Meta::CPAN
- $ref: "#/definitions/Config"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.25.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.25.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.25.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.25.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage statistics.
The `precpu_stats` is the CPU statistic of last read, which is used for calculating the CPU usage percentage. It is not the same as the `cpu_stats` field.
operationId: "ContainerStats"
produces:
- "application/json"
responses:
200:
description: "no error"
schema:
type: "object"
share/specs/v1.25.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.25.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces:
- "text/plain"
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
500:
share/specs/v1.25.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.25.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.25.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.25.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.25.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.25.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.25.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.26.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.26"
info:
title: "Docker Engine API"
version: "1.26"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.26.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.26.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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`.
- name: "Secret"
x-displayName: "Secrets"
# Swarm things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.26.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
IPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
type: "string"
IPv6Address:
type: "string"
LinkLocalIPs:
type: "array"
items:
type: "string"
share/specs/v1.26.yaml view on Meta::CPAN
- $ref: "#/definitions/Config"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.26.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.26.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.26.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.26.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage statistics.
The `precpu_stats` is the CPU statistic of last read, which is used for calculating the CPU usage percentage. It is not the same as the `cpu_stats` field.
operationId: "ContainerStats"
produces:
- "application/json"
responses:
200:
description: "no error"
schema:
type: "object"
share/specs/v1.26.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.26.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces:
- "text/plain"
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
500:
share/specs/v1.26.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.26.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.26.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.26.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.26.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.26.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.26.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.26.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
share/specs/v1.27.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.27"
info:
title: "Docker Engine API"
version: "1.27"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.27.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.27.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.27.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
IPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
type: "string"
IPv6Address:
type: "string"
LinkLocalIPs:
type: "array"
items:
type: "string"
share/specs/v1.27.yaml view on Meta::CPAN
- $ref: "#/definitions/Config"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.27.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.27.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.27.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.27.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
produces:
share/specs/v1.27.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.27.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces:
- "text/plain"
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
500:
share/specs/v1.27.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.27.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.27.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.27.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.27.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.27.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.27.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.27.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
share/specs/v1.28.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.28"
info:
title: "Docker Engine API"
version: "1.28"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.28.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.28.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.28.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
IPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
type: "string"
IPv6Address:
type: "string"
LinkLocalIPs:
type: "array"
items:
type: "string"
share/specs/v1.28.yaml view on Meta::CPAN
- $ref: "#/definitions/Config"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.28.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.28.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.28.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.28.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.28.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.28.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.28.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.28.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.28.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.28.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.28.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.28.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.28.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.28.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
share/specs/v1.29.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.29"
info:
title: "Docker Engine API"
version: "1.29"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.29.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.29.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.29.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
IPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
type: "string"
IPv6Address:
type: "string"
LinkLocalIPs:
type: "array"
items:
type: "string"
share/specs/v1.29.yaml view on Meta::CPAN
- $ref: "#/definitions/Config"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.29.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.29.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.29.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.29.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.29.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.29.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.29.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.29.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.29.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.29.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.29.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.29.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.29.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.29.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.29.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.29.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
share/specs/v1.30.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.30"
info:
title: "Docker Engine API"
version: "1.30"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.30.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.30.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.30.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.30.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
IPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
type: "string"
IPv6Address:
type: "string"
LinkLocalIPs:
type: "array"
items:
type: "string"
share/specs/v1.30.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.30.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.30.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.30.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.30.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.30.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.30.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.30.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.30.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.30.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.30.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.30.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.30.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.30.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.30.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.30.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.30.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.30.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.30.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.31.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.31"
info:
title: "Docker Engine API"
version: "1.31"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.31.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.31.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.31.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
IPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
type: "string"
IPv6Address:
type: "string"
LinkLocalIPs:
type: "array"
items:
type: "string"
share/specs/v1.31.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Secret:
type: "object"
properties:
ID:
share/specs/v1.31.yaml view on Meta::CPAN
type: "string"
format: "dateTime"
Spec:
$ref: "#/definitions/ConfigSpec"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.31.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.31.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.31.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.31.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.31.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.31.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.31.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.31.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.31.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.31.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.31.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.31.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.31.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.31.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.31.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.31.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.31.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.31.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.31.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.31.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.32.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.32"
info:
title: "Docker Engine API"
version: "1.32"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.32.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.32.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.32.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.32.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.32.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.32.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.32.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.32.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.32.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Secret:
type: "object"
properties:
ID:
share/specs/v1.32.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.32.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.32.yaml view on Meta::CPAN
Addr:
description: |
IP address and ports at which this node can be reached.
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.32.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.32.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.32.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.32.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.32.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.32.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.32.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.32.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.32.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.32.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.32.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.32.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.32.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.32.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.32.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.32.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.32.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.32.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.32.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.32.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.33.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.33"
info:
title: "Docker Engine API"
version: "1.33"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.33.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.33.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.33.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.33.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.33.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.33.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.33.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.33.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.33.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Secret:
type: "object"
properties:
ID:
share/specs/v1.33.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.33.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.33.yaml view on Meta::CPAN
Addr:
description: |
IP address and ports at which this node can be reached.
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.33.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.33.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.33.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.33.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.33.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.33.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.33.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.33.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.33.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.33.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.33.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.33.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.33.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.33.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.33.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.33.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.33.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.33.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.33.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.33.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.34.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.34"
info:
title: "Docker Engine API"
version: "1.34"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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"
}
```
share/specs/v1.34.yaml view on Meta::CPAN
1.12.x | [1.24](https://docs.docker.com/engine/api/v1.24/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-24-api-changes)
1.11.x | [1.23](https://docs.docker.com/engine/api/v1.23/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-23-api-changes)
1.10.x | [1.22](https://docs.docker.com/engine/api/v1.22/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-22-api-changes)
1.9.x | [1.21](https://docs.docker.com/engine/api/v1.21/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-21-api-changes)
1.8.x | [1.20](https://docs.docker.com/engine/api/v1.20/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-20-api-changes)
1.7.x | [1.19](https://docs.docker.com/engine/api/v1.19/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-19-api-changes)
1.6.x | [1.18](https://docs.docker.com/engine/api/v1.18/) | [API changes](https://docs.docker.com/engine/api/version-history/#v1-18-api-changes)
# 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.34.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.34.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.34.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.34.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.34.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.34.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.34.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.34.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Secret:
type: "object"
properties:
ID:
share/specs/v1.34.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.34.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.34.yaml view on Meta::CPAN
Addr:
description: |
IP address and ports at which this node can be reached.
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.34.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.34.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.34.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.34.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.34.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.34.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.34.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.34.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.34.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.34.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.34.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.34.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.34.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.34.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.34.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.34.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.34.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.34.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.34.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.34.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.35.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.35"
info:
title: "Docker Engine API"
version: "1.35"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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 (v1.35) is used.
For example, calling `/info` is the same as calling `/v1.35/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 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.35.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.35.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.35.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.35.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.35.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.35.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.35.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.35.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Secret:
type: "object"
properties:
ID:
share/specs/v1.35.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.35.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.35.yaml view on Meta::CPAN
Addr:
description: |
IP address and ports at which this node can be reached.
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.35.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.35.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
share/specs/v1.35.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.35.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.35.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.35.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.35.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.35.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.35.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.35.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.35.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.35.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.35.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.35.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.35.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.35.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.35.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.35.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.35.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.35.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.36.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.36"
info:
title: "Docker Engine API"
version: "1.36"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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 (v1.36) is used.
For example, calling `/info` is the same as calling `/v1.36/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 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.36.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.36.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.36.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.36.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.36.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.36.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.36.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.36.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Secret:
type: "object"
properties:
ID:
share/specs/v1.36.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.36.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.36.yaml view on Meta::CPAN
Addr:
description: |
IP address and ports at which this node can be reached.
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.36.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.36.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
title: "ContainerTopResponse"
description: "OK response to ContainerTop operation"
properties:
Titles:
share/specs/v1.36.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.36.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.36.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.36.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.36.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.36.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.36.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.36.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.36.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.36.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.36.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.36.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.36.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.36.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.36.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.36.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.36.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.36.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.37.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.37"
info:
title: "Docker Engine API"
version: "1.37"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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 (v1.37) is used.
For example, calling `/info` is the same as calling `/v1.37/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 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.37.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.37.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.37.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.37.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.37.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.37.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.37.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.37.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Templating:
description: |
Templating driver, if applicable
Templating controls whether and how to evaluate the config payload as
share/specs/v1.37.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.37.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.37.yaml view on Meta::CPAN
Addr:
description: |
IP address and ports at which this node can be reached.
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.37.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.37.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
title: "ContainerTopResponse"
description: "OK response to ContainerTop operation"
properties:
Titles:
share/specs/v1.37.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.37.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.37.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This endpoint returns a live stream of a container’s resource usage
statistics.
The `precpu_stats` is the CPU statistic of last read, which is used
for calculating the CPU usage percentage. It is not the same as the
`cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.37.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.37.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.37.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.37.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.37.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.37.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.37.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.37.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.37.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.37.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.37.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.37.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.37.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.37.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.37.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.38.yaml view on Meta::CPAN
- "text/plain"
basePath: "/v1.38"
info:
title: "Docker Engine API"
version: "1.38"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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 (v1.38) is used.
For example, calling `/info` is the same as calling `/v1.38/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 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...
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth), you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
# - They should be singular, not plural.
share/specs/v1.38.yaml view on Meta::CPAN
Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/engine/userguide/networking/) for more information.
- name: "Volume"
x-displayName: "Volumes"
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. See the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) 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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. See [the swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.38.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.38.yaml view on Meta::CPAN
type: "object"
description: "The driver specific options used when creating the volume."
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.38.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.38.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.38.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.38.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.38.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: "Name of the secrets driver used to fetch the secret's value from an external secret store"
$ref: "#/definitions/Driver"
Templating:
description: |
Templating driver, if applicable
Templating controls whether and how to evaluate the config payload as
share/specs/v1.38.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.38.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.38.yaml view on Meta::CPAN
Addr:
description: |
IP address and ports at which this node can be reached.
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
the list of linked containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
share/specs/v1.38.yaml view on Meta::CPAN
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
description: "This container's networking configuration."
type: "object"
properties:
EndpointsConfig:
description: "A mapping of network name to endpoint configuration for that network."
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
Hostname: ""
Domainname: ""
User: ""
AttachStdin: false
AttachStdout: true
AttachStderr: true
share/specs/v1.38.yaml view on Meta::CPAN
type: "string"
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: "On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows."
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
title: "ContainerTopResponse"
description: "OK response to ContainerTop operation"
properties:
Titles:
share/specs/v1.38.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
share/specs/v1.38.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.38.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This 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 calculate the CPU usage percentage. It is not an exact copy
of the `cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
operationId: "ContainerStats"
share/specs/v1.38.yaml view on Meta::CPAN
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
See [the documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.38.yaml view on Meta::CPAN
BuildTime: "2016-06-14T07:09:13.444803460+00:00"
Experimental: true
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.38.yaml view on Meta::CPAN
required: true
tags: ["Image"]
/images/get:
get:
summary: "Export several images"
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there wo...
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.38.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see [the export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.38.yaml view on Meta::CPAN
required: true
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
share/specs/v1.38.yaml view on Meta::CPAN
Tty: false
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: "Resize 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."
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
- name: "id"
share/specs/v1.38.yaml view on Meta::CPAN
format: "int64"
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see [the network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than inspecting a single network. For example,
the list of containers attached to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
share/specs/v1.38.yaml view on Meta::CPAN
required: true
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.38.yaml view on Meta::CPAN
description: "A base64-encoded auth configuration for pulling from private registries. [See the authentication section for details.](#section/Authentication)"
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.38.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.38.yaml view on Meta::CPAN
description: "ID of the task"
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
**Note**: This endpoint works only for services with the `json-file` or `journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
share/specs/v1.38.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.38.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: "The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values."
- name: "version"
in: "query"
description: "The version number of the secret object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
get:
summary: "List configs"
share/specs/v1.38.yaml view on Meta::CPAN
parameters:
- name: "id"
in: "path"
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values."
- name: "version"
in: "query"
description: "The version number of the config object being updated. This is required to avoid conflicting writes."
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
get:
summary: "Get image information from the registry"
share/specs/v1.38.yaml view on Meta::CPAN
description: "Image name or id"
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
The Docker daemon will respond with a `101 UPGRADED` response follow with the raw stream:
share/specs/v1.39.yaml view on Meta::CPAN
info:
title: "Docker Engine API"
version: "1.39"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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 (v1.39) is used.
For example, calling `/info` is the same as calling `/v1.39/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 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](https://tools.ietf.org/html/rfc4648#section-5)
(JSON) string with the following structure:
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth),
you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
share/specs/v1.39.yaml view on Meta::CPAN
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. Refer to the
[command-line reference](https://docs.docker.com/engine/reference/commandline/exec/)
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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. Refer to the
[swarm mode documentation](https://docs.docker.com/engine/swarm/)
for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode
must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must
be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must
be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm
mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.39.yaml view on Meta::CPAN
NetworkingConfig:
description: |
NetworkingConfig represents the container's networking configuration for
each of its interfaces.
It is used for the networking configs specified in the `docker create`
and `docker network connect` commands.
type: "object"
properties:
EndpointsConfig:
description: |
A mapping of network name to endpoint configuration for that network.
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
# putting an example here, instead of using the example values from
# /definitions/EndpointSettings, because containers/create currently
# does not support attaching to multiple networks, so the example request
# would be confusing if it showed that multiple networks can be contained
# in the EndpointsConfig.
# TODO remove once we support multiple networks on container create (see https://github.com/moby/moby/blob/07e6b843594e061f82baa5fa23c2ff7d536c2a05/daemon/create.go#L323)
share/specs/v1.39.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.39.yaml view on Meta::CPAN
description: |
The driver specific options used when creating the volume.
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.39.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.39.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.39.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.39.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.39.yaml view on Meta::CPAN
node attribute | matches | example
---------------------|--------------------------------|-----------------------------------------------
`node.id` | Node ID | `node.id==2ivku8v2gvtg4`
`node.hostname` | Node hostname | `node.hostname!=node-2`
`node.role` | Node role (`manager`/`worker`) | `node.role==manager`
`node.labels` | User-defined node labels | `node.labels.security==high`
`engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04`
`engine.labels` apply to Docker Engine labels like operating system,
drivers, etc. Swarm administrators add `node.labels` for operational
purposes by using the [`node update endpoint`](#operation/NodeUpdate).
type: "array"
items:
type: "string"
example:
- "node.hostname!=node3.corp.example.com"
- "node.role!=manager"
- "node.labels.type==production"
Preferences:
description: |
share/specs/v1.39.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-5))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: |
Name of the secrets driver used to fetch the secret's value from an
external secret store.
$ref: "#/definitions/Driver"
Templating:
description: |
Templating driver, if applicable
share/specs/v1.39.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.39.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.39.yaml view on Meta::CPAN
type: "object"
additionalProperties:
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see the
[inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container
than inspecting a single container. For example, the list of linked
containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
share/specs/v1.39.yaml view on Meta::CPAN
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: |
On Unix systems, this is done by running the `ps` command. This endpoint
is not supported on Windows.
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
title: "ContainerTopResponse"
description: "OK response to ContainerTop operation"
properties:
share/specs/v1.39.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or
`journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
share/specs/v1.39.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.39.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This 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 calculate the CPU usage percentage. It is not an exact copy
of the `cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
share/specs/v1.39.yaml view on Meta::CPAN
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint
to do anything.
See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/)
for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`,
and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.39.yaml view on Meta::CPAN
schema:
$ref: "#/definitions/SystemVersion"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.39.yaml view on Meta::CPAN
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are
returned; if it is an image ID, similarly only that image (and its parents)
are returned and there would be no names referenced in the 'repositories'
file for this image ID.
For details on the format, see the [export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.39.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see the [export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.39.yaml view on Meta::CPAN
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: |
Starts a previously set up exec instance. If detach is true, this endpoint
returns immediately after starting the command. Otherwise, it sets up an
interactive session with the command.
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
share/specs/v1.39.yaml view on Meta::CPAN
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: |
Resize 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.
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.39.yaml view on Meta::CPAN
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see the
[network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than
inspecting a single network. For example, the list of containers attached
to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
share/specs/v1.39.yaml view on Meta::CPAN
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be
enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.39.yaml view on Meta::CPAN
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service. See also
[`/containers/{id}/logs`](#operation/ContainerLogs).
**Note**: This endpoint works only for services with the `json-file` or
`journald` logging drivers.
operationId: "ServiceLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
share/specs/v1.39.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show service context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.39.yaml view on Meta::CPAN
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
See also [`/containers/{id}/logs`](#operation/ContainerLogs).
**Note**: This endpoint works only for services with the `json-file` or
`journald` logging drivers.
operationId: "TaskLogs"
produces:
- "application/vnd.docker.raw-stream"
- "application/json"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
share/specs/v1.39.yaml view on Meta::CPAN
- name: "details"
in: "query"
description: "Show task context and extra details provided to logs."
type: "boolean"
default: false
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
This will return a `101` HTTP response with a `Connection: upgrade` header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, [see the documentation for the attach endpoint](#o...
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
share/specs/v1.39.yaml view on Meta::CPAN
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: |
The spec of the secret to update. Currently, only the Labels field
can be updated. All other fields must remain unchanged from the
[SecretInspect endpoint](#operation/SecretInspect) response values.
- name: "version"
in: "query"
description: |
The version number of the secret object being updated. This is
required to avoid conflicting writes.
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
share/specs/v1.39.yaml view on Meta::CPAN
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: |
The spec of the config to update. Currently, only the Labels field
can be updated. All other fields must remain unchanged from the
[ConfigInspect endpoint](#operation/ConfigInspect) response values.
- name: "version"
in: "query"
description: |
The version number of the config object being updated. This is
required to avoid conflicting writes.
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
share/specs/v1.39.yaml view on Meta::CPAN
type: "string"
required: true
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to
call back to the client for advanced capabilities.
> **Note**: This endpoint is *experimental* and only available if the daemon is started with experimental
> features enabled. The specifications for this endpoint may still change in a future version of the API.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows
the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
share/specs/v1.40.yaml view on Meta::CPAN
info:
title: "Docker Engine API"
version: "1.40"
x-logo:
url: "https://docs.docker.com/images/logo-docker-main.png"
description: |
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 (v1.40) is used.
For example, calling `/info` is the same as calling `/v1.40/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 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](https://tools.ietf.org/html/rfc4648#section-5)
(JSON) string with the following structure:
```
{
"username": "string",
"password": "string",
"email": "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](#operation/SystemAuth),
you can just pass this instead of credentials:
```
{
"identitytoken": "9cbaf023786cd7..."
}
```
# The tags on paths define the menu sections in the ReDoc documentation, so
# the usage of tags must make sense for that:
share/specs/v1.40.yaml view on Meta::CPAN
description: |
Create and manage persistent storage that can be attached to containers.
- name: "Exec"
x-displayName: "Exec"
description: |
Run new commands inside running containers. Refer to the
[command-line reference](https://docs.docker.com/engine/reference/commandline/exec/)
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 things
- name: "Swarm"
x-displayName: "Swarm"
description: |
Engines can be clustered together in a swarm. Refer to the
[swarm mode documentation](https://docs.docker.com/engine/swarm/)
for more information.
- name: "Node"
x-displayName: "Nodes"
description: |
Nodes are instances of the Engine participating in a swarm. Swarm mode
must be enabled for these endpoints to work.
- name: "Service"
x-displayName: "Services"
description: |
Services are the definitions of tasks to run on a swarm. Swarm mode must
be enabled for these endpoints to work.
- name: "Task"
x-displayName: "Tasks"
description: |
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.
- name: "Secret"
x-displayName: "Secrets"
description: |
Secrets are sensitive data that can be used by services. Swarm mode must
be enabled for these endpoints to work.
- name: "Config"
x-displayName: "Configs"
description: |
Configs are application configurations that can be used by services. Swarm
mode must be enabled for these endpoints to work.
# System things
- name: "Plugin"
x-displayName: "Plugins"
- name: "System"
x-displayName: "System"
definitions:
Port:
type: "object"
description: "An open port on a container"
share/specs/v1.40.yaml view on Meta::CPAN
NetworkingConfig:
description: |
NetworkingConfig represents the container's networking configuration for
each of its interfaces.
It is used for the networking configs specified in the `docker create`
and `docker network connect` commands.
type: "object"
properties:
EndpointsConfig:
description: |
A mapping of network name to endpoint configuration for that network.
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
example:
# putting an example here, instead of using the example values from
# /definitions/EndpointSettings, because containers/create currently
# does not support attaching to multiple networks, so the example request
# would be confusing if it showed that multiple networks can be contained
# in the EndpointsConfig.
# TODO remove once we support multiple networks on container create (see https://github.com/moby/moby/blob/07e6b843594e061f82baa5fa23c2ff7d536c2a05/daemon/create.go#L323)
share/specs/v1.40.yaml view on Meta::CPAN
description: ""
type: "array"
items:
$ref: "#/definitions/Address"
x-nullable: true
# TODO properties below are part of DefaultNetworkSettings, which is
# marked as deprecated since Docker 1.9 and to be removed in Docker v17.12
EndpointID:
description: |
EndpointID uniquely represents a service endpoint in a Sandbox.
<p><br /></p>
> **Deprecated**: This field is only propagated when attached to the
> default "bridge" network. Use the information from the "bridge"
> network inside the `Networks` map instead, which contains the same
> information. This field was deprecated in Docker 1.9 and is scheduled
> to be removed in Docker 17.12.0
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
share/specs/v1.40.yaml view on Meta::CPAN
description: |
The driver specific options used when creating the volume.
additionalProperties:
type: "string"
UsageData:
type: "object"
x-nullable: true
required: [Size, RefCount]
description: |
Usage details about the volume. This information is used by the
`GET /system/df` endpoint, and omitted in other endpoints.
properties:
Size:
type: "integer"
default: -1
description: |
Amount of disk space used by the volume (in bytes). This information
is only available for volumes created with the `"local"` volume
driver. For volumes created with other volume drivers, this field
is set to `-1` ("not available")
x-nullable: false
share/specs/v1.40.yaml view on Meta::CPAN
description: "Response to an API call that returns just an Id"
type: "object"
required: ["Id"]
properties:
Id:
description: "The id of the newly created object."
type: "string"
x-nullable: false
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
Links:
type: "array"
items:
type: "string"
example:
share/specs/v1.40.yaml view on Meta::CPAN
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
share/specs/v1.40.yaml view on Meta::CPAN
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: |
EndpointIPAMConfig represents an endpoint's IPAM configuration.
type: "object"
x-nullable: true
properties:
IPv4Address:
type: "string"
example: "172.20.30.33"
IPv6Address:
type: "string"
example: "2001:db8:abcd::3033"
LinkLocalIPs:
share/specs/v1.40.yaml view on Meta::CPAN
type: "string"
example:
"max-file": "10"
"max-size": "100m"
# The Swarm information for `GET /info`. It is the same as `GET /swarm`, but
# without `JoinTokens`.
ClusterInfo:
description: |
ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
x-nullable: true
type: "object"
properties:
ID:
description: "The ID of the swarm."
type: "string"
example: "abajmipo7b4xz5ip2nrla6b11"
Version:
$ref: "#/definitions/ObjectVersion"
CreatedAt:
share/specs/v1.40.yaml view on Meta::CPAN
`node.id` | Node ID | `node.id==2ivku8v2gvtg4`
`node.hostname` | Node hostname | `node.hostname!=node-2`
`node.role` | Node role (`manager`/`worker`) | `node.role==manager`
`node.platform.os` | Node operating system | `node.platform.os==windows`
`node.platform.arch` | Node architecture | `node.platform.arch==x86_64`
`node.labels` | User-defined node labels | `node.labels.security==high`
`engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04`
`engine.labels` apply to Docker Engine labels like operating system,
drivers, etc. Swarm administrators add `node.labels` for operational
purposes by using the [`node update endpoint`](#operation/NodeUpdate).
type: "array"
items:
type: "string"
example:
- "node.hostname!=node3.corp.example.com"
- "node.role!=manager"
- "node.labels.type==production"
- "node.platform.os==linux"
- "node.platform.arch==x86_64"
share/specs/v1.40.yaml view on Meta::CPAN
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Data:
description: |
Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-5))
data to store as secret.
This field is only used to _create_ a secret, and is not returned by
other endpoints.
type: "string"
example: ""
Driver:
description: |
Name of the secrets driver used to fetch the secret's value from an
external secret store.
$ref: "#/definitions/Driver"
Templating:
description: |
Templating driver, if applicable
share/specs/v1.40.yaml view on Meta::CPAN
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
<p><br /></p>
> **Note**: When part of a Swarm, nodes can both have _daemon_ labels,
> set through the daemon configuration, and _node_ labels, set from a
> manager node in the Swarm. Node labels are not included in this
> field. Node labels can be retrieved using the `/nodes/(id)` endpoint
> on a manager node in the Swarm.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
share/specs/v1.40.yaml view on Meta::CPAN
> returns the Swarm version instead of the daemon version, for example
> `swarm/1.2.8`.
type: "string"
example: "17.06.0-ce"
ClusterStore:
description: |
URL of the distributed storage backend.
The storage backend is used for multihost networking (to store
network and endpoint information) and by the node discovery mechanism.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
example: "consul://consul.corp.example.com:8600/some/path"
ClusterAdvertise:
description: |
The network endpoint that the Engine advertises for the purpose of
node discovery. ClusterAdvertise is a `host:port` combination on which
the daemon is reachable by other hosts.
<p><br /></p>
> **Note**: This field is only propagated when using standalone Swarm
> mode, and overlay networking using an external k/v store. Overlay
> networks with Swarm mode enabled use the built-in raft store, and
> this field will be empty.
type: "string"
share/specs/v1.40.yaml view on Meta::CPAN
type: "object"
additionalProperties:
type: "string"
paths:
/containers/json:
get:
summary: "List containers"
description: |
Returns a list of containers. For details on the format, see the
[inspect endpoint](#operation/ContainerInspect).
Note that it uses a different, smaller representation of a container
than inspecting a single container. For example, the list of linked
containers is not propagated .
operationId: "ContainerList"
produces:
- "application/json"
parameters:
- name: "all"
in: "query"
share/specs/v1.40.yaml view on Meta::CPAN
- name: "size"
in: "query"
type: "boolean"
default: false
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/{id}/top:
get:
summary: "List processes running inside a container"
description: |
On Unix systems, this is done by running the `ps` command. This endpoint
is not supported on Windows.
operationId: "ContainerTop"
responses:
200:
description: "no error"
schema:
type: "object"
title: "ContainerTopResponse"
description: "OK response to ContainerTop operation"
properties:
share/specs/v1.40.yaml view on Meta::CPAN
description: "The arguments to pass to `ps`. For example, `aux`"
type: "string"
default: "-ef"
tags: ["Container"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or
`journald` logging driver.
operationId: "ContainerLogs"
responses:
200:
description: |
logs returned as a stream in response body.
For the stream format, [see the documentation for the attach endpoint](#operation/ContainerAttach).
Note that unlike the attach endpoint, the logs endpoint does not
upgrade the connection and does not set Content-Type.
schema:
type: "string"
format: "binary"
404:
description: "no such container"
schema:
$ref: "#/definitions/ErrorResponse"
examples:
application/json:
share/specs/v1.40.yaml view on Meta::CPAN
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
tags: ["Container"]
/containers/{id}/stats:
get:
summary: "Get container stats based on resource usage"
description: |
This 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 calculate the CPU usage percentage. It is not an exact copy
of the `cpu_stats` field.
If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is
nil then for compatibility with older daemons the length of the
corresponding `cpu_usage.percpu_usage` array should be used.
share/specs/v1.40.yaml view on Meta::CPAN
type: "string"
tags: ["Container"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach 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 been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint
to do anything.
See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/)
for more details.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`,
and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
[STREAM]
```
share/specs/v1.40.yaml view on Meta::CPAN
schema:
$ref: "#/definitions/SystemVersion"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["System"]
/_ping:
get:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPing"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
headers:
API-Version:
share/specs/v1.40.yaml view on Meta::CPAN
headers:
Cache-Control:
type: "string"
default: "no-cache, no-store, must-revalidate"
Pragma:
type: "string"
default: "no-cache"
tags: ["System"]
head:
summary: "Ping"
description: "This is a dummy endpoint you can use to test if the server is accessible."
operationId: "SystemPingHead"
produces: ["text/plain"]
responses:
200:
description: "no error"
schema:
type: "string"
example: "(empty)"
headers:
API-Version:
share/specs/v1.40.yaml view on Meta::CPAN
description: |
Get 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. `ubuntu:latest`), then only that image (and its parents) are
returned; if it is an image ID, similarly only that image (and its parents)
are returned and there would be no names referenced in the 'repositories'
file for this image ID.
For details on the format, see the [export image endpoint](#operation/ImageGet).
operationId: "ImageGetAll"
produces:
- "application/x-tar"
responses:
200:
description: "no error"
schema:
type: "string"
format: "binary"
500:
share/specs/v1.40.yaml view on Meta::CPAN
type: "array"
items:
type: "string"
tags: ["Image"]
/images/load:
post:
summary: "Import images"
description: |
Load a set of images and tags into a repository.
For details on the format, see the [export image endpoint](#operation/ImageGet).
operationId: "ImageLoad"
consumes:
- "application/x-tar"
produces:
- "application/json"
responses:
200:
description: "no error"
500:
description: "server error"
share/specs/v1.40.yaml view on Meta::CPAN
- name: "id"
in: "path"
description: "ID or name of container"
type: "string"
required: true
tags: ["Exec"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: |
Starts a previously set up exec instance. If detach is true, this endpoint
returns immediately after starting the command. Otherwise, it sets up an
interactive session with the command.
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.docker.raw-stream"
responses:
200:
description: "No error"
share/specs/v1.40.yaml view on Meta::CPAN
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/resize:
post:
summary: "Resize an exec instance"
description: |
Resize 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.
operationId: "ExecResize"
responses:
201:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.40.yaml view on Meta::CPAN
500:
description: "Server error"
schema:
$ref: "#/definitions/ErrorResponse"
tags: ["Volume"]
/networks:
get:
summary: "List networks"
description: |
Returns a list of networks. For details on the format, see the
[network inspect endpoint](#operation/NetworkInspect).
Note that it uses a different, smaller representation of a network than
inspecting a single network. For example, the list of containers attached
to the network is not propagated in API versions 1.28 and up.
operationId: "NetworkList"
produces:
- "application/json"
responses:
200:
description: "No error"
share/specs/v1.40.yaml view on Meta::CPAN
type: "string"
tags:
- "Plugin"
/plugins/pull:
post:
summary: "Install a plugin"
operationId: "PluginPull"
description: |
Pulls and installs a plugin. After the plugin is installed, it can be
enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).
produces:
- "application/json"
responses:
204:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/definitions/ErrorResponse"
parameters:
share/specs/v1.40.yaml view on Meta::CPAN
type: "string"
tags: ["Service"]
/services/{id}/logs:
get:
summary: "Get service logs"
description: |
Get `stdout` and `stderr` logs from a service. See also
[`/containers/{id}/logs`](#operation/ContainerLogs).
**Note**: This endpoint works only for services with the `local`,
`json-file` or `journald` logging drivers.
operationId: "ServiceLogs"
responses:
200:
description: "logs returned as a stream in response body"
schema:
type: "string"
format: "binary"
404:
description: "no such service"
share/specs/v1.40.yaml view on Meta::CPAN
required: true
type: "string"
tags: ["Task"]
/tasks/{id}/logs:
get:
summary: "Get task logs"
description: |
Get `stdout` and `stderr` logs from a task.
See also [`/containers/{id}/logs`](#operation/ContainerLogs).
**Note**: This endpoint works only for services with the `local`,
`json-file` or `journald` logging drivers.
operationId: "TaskLogs"
responses:
200:
description: "logs returned as a stream in response body"
schema:
type: "string"
format: "binary"
404:
description: "no such task"
share/specs/v1.40.yaml view on Meta::CPAN
description: "The ID or name of the secret"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/SecretSpec"
description: |
The spec of the secret to update. Currently, only the Labels field
can be updated. All other fields must remain unchanged from the
[SecretInspect endpoint](#operation/SecretInspect) response values.
- name: "version"
in: "query"
description: |
The version number of the secret object being updated. This is
required to avoid conflicting writes.
type: "integer"
format: "int64"
required: true
tags: ["Secret"]
/configs:
share/specs/v1.40.yaml view on Meta::CPAN
description: "The ID or name of the config"
type: "string"
required: true
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ConfigSpec"
description: |
The spec of the config to update. Currently, only the Labels field
can be updated. All other fields must remain unchanged from the
[ConfigInspect endpoint](#operation/ConfigInspect) response values.
- name: "version"
in: "query"
description: |
The version number of the config object being updated. This is
required to avoid conflicting writes.
type: "integer"
format: "int64"
required: true
tags: ["Config"]
/distribution/{name}/json:
share/specs/v1.40.yaml view on Meta::CPAN
tags: ["Distribution"]
/session:
post:
summary: "Initialize interactive session"
description: |
Start a new interactive session with a server. Session allows server to
call back to the client for advanced capabilities.
### Hijacking
This endpoint hijacks the HTTP connection to HTTP2 transport that allows
the client to expose gPRC services on that connection.
For example, the client sends this request to upgrade the connection:
```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```
t/01_load.t view on Meta::CPAN
use warnings;
use Test::More;
require_ok('Docker::Client');
# Defaults
{
my $client = Docker::Client->new();
isa_ok( $client, 'Docker::Client' );
can_ok( $client, qw( endpoint version ua ) );
isa_ok( $client->endpoint(), 'Mojo::URL' );
isa_ok( $client->ua(), 'Mojo::UserAgent' );
is( $client->version(), 'v1.40', 'Correct default API version' );
};
## Endpoint from string
{
my $client = Docker::Client->new(
{
endpoint => 'http://domain.tld'
}
);
isa_ok( $client->endpoint(), 'Mojo::URL' );
is( $client->endpoint()->to_string(),
'http://domain.tld', 'Correct custom URL' );
};
done_testing();
( run in 0.917 second using v1.01-cache-2.11-cpan-2b1a40005be )