swagger: '2.0'
info:
title: Docker Engine Config Container API
version: '1.54'
x-logo:
url: https://docs.docker.com/assets/images/logo-docker-main.png
description: "The Engine API is an HTTP API served by Docker Engine. It is the API the\nDocker client uses to communicate with the Engine, so everything the Docker\nclient can do can be done with the API.\n\nMost of the client's commands map directly to API endpoints (e.g. `docker ps`\nis `GET /containers/json`). The notable exception is running containers,\nwhich consists of several API calls.\n\n# Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof the API call. The body of the response will be JSON in the following\nformat:\n\n```\n{\n \"message\": \"page not found\"\n}\n```\n\n# Versioning\n\nThe API is usually changed in each release, so API calls are versioned to\nensure that clients don't break. To lock to a specific version of the API,\nyou prefix the URL with its version, for example, call `/v1.30/info` to use\nthe v1.30 version of the `/info` endpoint. If the API version specified in\nthe URL is not supported by the daemon, a HTTP `400 Bad Request` error message\nis returned.\n\nIf you omit the version-prefix, the current version of the API (v1.50) is used.\nFor example, calling `/info` is the same as calling `/v1.52/info`. Using the\nAPI without a version-prefix is deprecated and will be removed in a future release.\n\nEngine releases in the near future should support this version of the API,\nso your client will continue to work even if it is talking to a newer Engine.\n\nThe API uses an open schema model, which means the server may add extra properties\nto responses. Likewise, the server will ignore any extra query parameters and\nrequest body properties. When you write clients, you need to ignore additional\nproperties in responses to ensure they do not break when talking to newer\ndaemons.\n\n\n# Authentication\n\nAuthentication for registries is handled client side. The client has to send\nauthentication details to various endpoints that need to communicate with\nregistries, such as `POST /images/(name)/push`. These are sent as\n`X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5)\n(JSON) string with the following structure:\n\n```\n{\n \"username\": \"string\",\n \"password\": \"string\",\n \"serveraddress\": \"string\"\n}\n```\n\nThe `serveraddress` is a domain/IP without a protocol. Throughout this\nstructure, double quotes are required.\n\nIf you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth),\nyou can just pass this instead of credentials:\n\n```\n{\n \"identitytoken\": \"9cbaf023786cd7...\"\n}\n```\n"
basePath: /v1.54
schemes:
- http
- https
consumes:
- application/json
- text/plain
produces:
- application/json
- text/plain
tags:
- name: Container
x-displayName: Containers
description: 'Create and manage containers.
'
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.
'
type: boolean
default: false
- name: limit
in: query
description: 'Return this number of most recently created containers, including
non-running ones.
'
type: integer
- name: size
in: query
description: 'Return the size of container as fields `SizeRw` and `SizeRootFs`.
'
type: boolean
default: false
- name: filters
in: query
description: 'Filters to process on the container list, encoded as JSON (a
`map[string][]string`). For example, `{"status": ["paused"]}` will
only return paused containers.
Available filters:
- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)
- `before`=(`<container id>` or `<container name>`)
- `expose`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`)
- `exited=<int>` containers with exit code of `<int>`
- `health`=(`starting`|`healthy`|`unhealthy`|`none`)
- `id=<ID>` a container''s ID
- `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only)
- `is-task=`(`true`|`false`)
- `label=key` or `label="key=value"` of a container label
- `name=<name>` a container''s name
- `network`=(`<network id>` or `<network name>`)
- `publish`=(`<port>[/<proto>]`|`<startport-endport>/[<proto>]`)
- `since`=(`<container id>` or `<container name>`)
- `status=`(`created`|`restarting`|`running`|`removing`|`paused`|`exited`|`dead`)
- `volume`=(`<volume name>` or `<mount point destination>`)
'
type: string
responses:
200:
description: no error
schema:
type: array
items:
$ref: '#/definitions/ContainerSummary'
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- Container
/containers/create:
post:
summary: Create a container
operationId: ContainerCreate
consumes:
- application/json
- application/octet-stream
produces:
- application/json
parameters:
- name: name
in: query
description: 'Assign the specified name to the container. Must match
`/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
'
type: string
pattern: ^/?[a-zA-Z0-9][a-zA-Z0-9_.-]+$
- name: platform
in: query
description: "Platform in the format `os[/arch[/variant]]` used for image lookup.\n\nWhen specified, the daemon checks if the requested image is present\nin the local image cache with the given OS and Architecture, and\notherwise returns a `404` status.\n\nIf the option is not set, the host's native OS and Architecture are\nused to look up the image in the image cache. However, if no platform\nis passed and the given image does exist in the local image cache,\nbut its OS or architecture does not match, the container is created\nwith the available image, and a warning is added to the `Warnings`\nfield in the response, for example;\n\n WARNING: The requested image's platform (linux/arm64/v8) does not\n match the detected host platform (linux/amd64) and no\n specific platform was requested\n"
type: string
default: ''
- name: body
in: body
description: Container to create
schema:
allOf:
- $ref: '#/definitions/ContainerConfig'
- type: object
properties:
HostConfig:
$ref: '#/definitions/HostConfig'
NetworkingConfig:
$ref: '#/definitions/NetworkingConfig'
example:
Hostname: ''
Domainname: ''
User: ''
AttachStdin: false
AttachStdout: true
AttachStderr: true
Tty: false
OpenStdin: false
StdinOnce: false
Env:
- FOO=bar
- BAZ=quux
Cmd:
- date
Entrypoint: ''
Image: ubuntu
Labels:
com.example.vendor: Acme
com.example.license: GPL
com.example.version: '1.0'
Volumes:
/volumes/data: {}
WorkingDir: ''
NetworkDisabled: false
ExposedPorts:
22/tcp: {}
StopSignal: SIGTERM
StopTimeout: 10
HostConfig:
Binds:
- /tmp:/tmp
Links:
- redis3:redis
Memory: 0
MemorySwap: 0
MemoryReservation: 0
NanoCpus: 500000
CpuPercent: 80
CpuShares: 512
CpuPeriod: 100000
CpuRealtimePeriod: 1000000
CpuRealtimeRuntime: 10000
CpuQuota: 50000
CpusetCpus: 0,1
CpusetMems: 0,1
MaximumIOps: 0
MaximumIOBps: 0
BlkioWeight: 300
BlkioWeightDevice:
- {}
BlkioDeviceReadBps:
- {}
BlkioDeviceReadIOps:
- {}
BlkioDeviceWriteBps:
- {}
BlkioDeviceWriteIOps:
- {}
DeviceRequests:
- Driver: nvidia
Count: -1
DeviceIDs":
- '0'
- '1'
- GPU-fef8089b-4820-abfc-e83e-94318197576e
Capabilities:
- - gpu
- nvidia
- compute
Options:
property1: string
property2: string
MemorySwappiness: 60
OomKillDisable: false
OomScoreAdj: 500
PidMode: ''
PidsLimit: 0
PortBindings:
22/tcp:
- HostPort: '11022'
PublishAllPorts: false
Privileged: false
ReadonlyRootfs: false
Dns:
- 8.8.8.8
DnsOptions:
- ''
DnsSearch:
- ''
VolumesFrom:
- parent
- other:ro
CapAdd:
- NET_ADMIN
CapDrop:
- MKNOD
GroupAdd:
- newgroup
RestartPolicy:
Name: ''
MaximumRetryCount: 0
AutoRemove: true
NetworkMode: bridge
Devices: []
Ulimits:
- {}
LogConfig:
Type: json-file
Config: {}
SecurityOpt: []
StorageOpt: {}
CgroupParent: ''
VolumeDriver: ''
ShmSize: 67108864
NetworkingConfig:
EndpointsConfig:
isolated_nw:
IPAMConfig:
IPv4Address: 172.20.30.33
IPv6Address: 2001:db8:abcd::3033
LinkLocalIPs:
- 169.254.34.68
- fe80::3468
Links:
- container_1
- container_2
Aliases:
- server_x
- server_y
database_nw: {}
required: true
responses:
201:
description: Container created successfully
schema:
$ref: '#/definitions/ContainerCreateResponse'
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
404:
description: no such image
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such image: c2ada9df5af8'
409:
description: conflict
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- Container
/containers/{id}/json:
get:
summary: Inspect a container
description: Return low-level information about a container.
operationId: ContainerInspect
produces:
- application/json
responses:
200:
description: no error
schema:
$ref: '#/definitions/ContainerInspectResponse'
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
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:
$ref: '#/definitions/ContainerTopResponse'
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: ps_args
in: query
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.
'
produces:
- application/vnd.docker.raw-stream
- application/vnd.docker.multiplexed-stream
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:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: follow
in: query
description: Keep connection after returning logs.
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`
type: boolean
default: false
- name: since
in: query
description: Only return logs since this time, as a UNIX timestamp
type: integer
default: 0
- name: until
in: query
description: Only return logs before this time, as a UNIX timestamp
type: integer
default: 0
- name: timestamps
in: query
description: Add timestamps to every log line
type: boolean
default: false
- name: tail
in: query
description: 'Only return this number of log lines from the end of the logs.
Specify as an integer or `all` to output all log lines.
'
type: string
default: all
tags:
- Container
/containers/{id}/changes:
get:
summary: Get changes on a container’s filesystem
description: 'Returns which files in a container''s filesystem have been added, deleted,
or modified. The `Kind` of modification can be one of:
- `0`: Modified ("C")
- `1`: Added ("A")
- `2`: Deleted ("D")
'
operationId: ContainerChanges
produces:
- application/json
responses:
200:
description: The list of changes
schema:
type: array
items:
$ref: '#/definitions/FilesystemChange'
examples:
application/json:
- Path: /dev
Kind: 0
- Path: /dev/kmsg
Kind: 1
- Path: /test
Kind: 1
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
tags:
- Container
/containers/{id}/export:
get:
summary: Export a container
description: Export the contents of a container as a tarball.
operationId: ContainerExport
produces:
- application/octet-stream
responses:
200:
description: no error
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- 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.
On a cgroup v2 host, the following fields are not set
* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt`
Also, `memory_stats.stats` fields are incompatible with cgroup v1.
To calculate the values shown by the `stats` command of the docker cli tool
the following formulas can be used:
* used_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system_cpu_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`
'
operationId: ContainerStats
produces:
- application/json
responses:
200:
description: no error
schema:
$ref: '#/definitions/ContainerStatsResponse'
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: stream
in: query
description: 'Stream the output. If false, the stats will be output once and then
it will disconnect.
'
type: boolean
default: true
- name: one-shot
in: query
description: 'Only get a single stat instead of waiting for 2 cycles. Must be used
with `stream=false`.
'
type: boolean
default: false
tags:
- Container
/containers/{id}/resize:
post:
summary: Resize a container TTY
description: Resize the TTY for a container.
operationId: ContainerResize
consumes:
- application/octet-stream
produces:
- text/plain
responses:
200:
description: no error
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: cannot resize container
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: h
in: query
required: true
description: Height of the TTY session in characters
type: integer
- name: w
in: query
required: true
description: Width of the TTY session in characters
type: integer
tags:
- Container
/containers/{id}/start:
post:
summary: Start a container
operationId: ContainerStart
responses:
204:
description: no error
304:
description: container already started
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: detachKeys
in: query
description: 'Override the key sequence for detaching a container. Format is a
single character `[a-Z]` or `ctrl-<value>` where `<value>` is one
of: `a-z`, `@`, `^`, `[`, `,` or `_`.
'
type: string
tags:
- Container
/containers/{id}/stop:
post:
summary: Stop a container
operationId: ContainerStop
responses:
204:
description: no error
304:
description: container already stopped
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: signal
in: query
description: 'Signal to send to the container as an integer or string (e.g. `SIGINT`).
'
type: string
- name: t
in: query
description: Number of seconds to wait before killing the container
type: integer
tags:
- Container
/containers/{id}/restart:
post:
summary: Restart a container
operationId: ContainerRestart
responses:
204:
description: no error
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: signal
in: query
description: 'Signal to send to the container as an integer or string (e.g. `SIGINT`).
'
type: string
- name: t
in: query
description: Number of seconds to wait before killing the container
type: integer
tags:
- Container
/containers/{id}/kill:
post:
summary: Kill a container
description: 'Send a POSIX signal to a container, defaulting to killing to the
container.
'
operationId: ContainerKill
responses:
204:
description: no error
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
409:
description: container is not running
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: Container d37cde0fe4ad63c3a7252023b2f9800282894247d145cb5933ddf6e52cc03a28 is not running
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: signal
in: query
description: 'Signal to send to the container as an integer or string (e.g. `SIGINT`).
'
type: string
default: SIGKILL
tags:
- Container
/containers/{id}/update:
post:
summary: Update a container
description: 'Change various configuration options of a container without having to
recreate it.
'
operationId: ContainerUpdate
consumes:
- application/json
produces:
- application/json
responses:
200:
description: The container has been updated.
schema:
$ref: '#/definitions/ContainerUpdateResponse'
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: update
in: body
required: true
schema:
allOf:
- $ref: '#/definitions/Resources'
- type: object
properties:
RestartPolicy:
$ref: '#/definitions/RestartPolicy'
example:
BlkioWeight: 300
CpuShares: 512
CpuPeriod: 100000
CpuQuota: 50000
CpuRealtimePeriod: 1000000
CpuRealtimeRuntime: 10000
CpusetCpus: 0,1
CpusetMems: '0'
Memory: 314572800
MemorySwap: 514288000
MemoryReservation: 209715200
RestartPolicy:
MaximumRetryCount: 4
Name: on-failure
tags:
- Container
/containers/{id}/rename:
post:
summary: Rename a container
operationId: ContainerRename
responses:
204:
description: no error
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
409:
description: name already in use
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
- name: name
in: query
required: true
description: New name for the container
type: string
tags:
- Container
/containers/{id}/pause:
post:
summary: Pause a container
description: 'Use the freezer cgroup to suspend all processes in a container.
Traditionally, when suspending a process the `SIGSTOP` signal is used,
which is observable by the process being suspended. With the freezer
cgroup the process is unaware, and unable to capture, that it is being
suspended, and subsequently resumed.
'
operationId: ContainerPause
responses:
204:
description: no error
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID or name of the container
type: string
tags:
- Container
/containers/{id}/unpause:
post:
summary: Unpause a container
description: Resume a container which has been paused.
operationId: ContainerUnpause
responses:
204:
description: no error
404:
description: no such container
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such container: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
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]
```
After the headers and two new lines, the TCP connection can now be used
for raw, bidirectional communication between the client and server.
To hint potential proxies about connection hijacking, the Docker client
can also optional
# --- truncated at 32 KB (135 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-container-api-openapi.yml