Docker System API
The System API from Docker — 6 operation(s) for system.
OpenAPI Specification
swagger: '2.0'
info:
title: Docker Engine Config System 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: System
x-displayName: System
paths:
/auth:
post:
summary: Check auth configuration
description: 'Validate credentials for a registry and, if available, get an identity
token for accessing the registry without password.
'
operationId: SystemAuth
consumes:
- application/json
produces:
- application/json
responses:
200:
description: An identity token was generated successfully.
schema:
$ref: '#/definitions/AuthResponse'
204:
description: No error
401:
description: Auth error
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: authConfig
in: body
description: Authentication to check
schema:
$ref: '#/definitions/AuthConfig'
tags:
- System
/info:
get:
summary: Get system information
operationId: SystemInfo
produces:
- application/json
responses:
200:
description: No error
schema:
$ref: '#/definitions/SystemInfo'
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- System
/version:
get:
summary: Get version
description: Returns the version of Docker that is running and various information about the system that Docker is running on.
operationId: SystemVersion
produces:
- application/json
responses:
200:
description: no error
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:
type: string
description: Max API Version the server supports
Builder-Version:
type: string
description: 'Default version of docker image builder
The default on Linux is version "2" (BuildKit), but the daemon
can be configured to recommend version "1" (classic Builder).
Windows does not yet support BuildKit for native Windows images,
and uses "1" (classic builder) as a default.
This value is a recommendation as advertised by the daemon, and
it is up to the client to choose which builder to use.
'
default: '2'
Docker-Experimental:
type: boolean
description: If the server is running with experimental mode enabled
Swarm:
type: string
enum:
- inactive
- pending
- error
- locked
- active/worker
- active/manager
description: 'Contains information about Swarm status of the daemon,
and if the daemon is acting as a manager or worker node.
'
default: inactive
Cache-Control:
type: string
default: no-cache, no-store, must-revalidate
Pragma:
type: string
default: no-cache
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
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:
type: string
description: Max API Version the server supports
Builder-Version:
type: string
description: Default version of docker image builder
Docker-Experimental:
type: boolean
description: If the server is running with experimental mode enabled
Swarm:
type: string
enum:
- inactive
- pending
- error
- locked
- active/worker
- active/manager
description: 'Contains information about Swarm status of the daemon,
and if the daemon is acting as a manager or worker node.
'
default: inactive
Cache-Control:
type: string
default: no-cache, no-store, must-revalidate
Pragma:
type: string
default: no-cache
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- System
/events:
get:
summary: Monitor events
description: 'Stream real-time events from the server.
Various objects within Docker report events when something happens to them.
Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`
Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`
Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`
Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`
The Docker daemon reports these events: `reload`
Services report these events: `create`, `update`, and `remove`
Nodes report these events: `create`, `update`, and `remove`
Secrets report these events: `create`, `update`, and `remove`
Configs report these events: `create`, `update`, and `remove`
The Builder reports `prune` events
'
operationId: SystemEvents
produces:
- application/jsonl
- application/x-ndjson
- application/json-seq
responses:
200:
description: no error
schema:
$ref: '#/definitions/EventMessage'
400:
description: bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: since
in: query
description: Show events created since this timestamp then stream new events.
type: string
- name: until
in: query
description: Show events created until this timestamp then stop streaming.
type: string
- name: filters
in: query
description: 'A JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:
- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`=<string> plugin name or ID
- `scope`=<string> local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name
'
type: string
tags:
- System
/system/df:
get:
summary: Get data usage information
operationId: SystemDataUsage
responses:
200:
description: no error
schema:
type: object
title: SystemDataUsageResponse
properties:
ImageUsage:
$ref: '#/definitions/ImagesDiskUsage'
ContainerUsage:
$ref: '#/definitions/ContainersDiskUsage'
VolumeUsage:
$ref: '#/definitions/VolumesDiskUsage'
BuildCacheUsage:
$ref: '#/definitions/BuildCacheDiskUsage'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: type
in: query
description: 'Object types, for which to compute and return data.
'
type: array
collectionFormat: multi
items:
type: string
enum:
- container
- image
- volume
- build-cache
- name: verbose
in: query
description: 'Show detailed information on space usage.
'
type: boolean
default: false
tags:
- System
definitions:
PeerNode:
description: Represents a peer-node in the swarm
type: object
properties:
NodeID:
description: Unique identifier of for this node in the swarm.
type: string
Addr:
description: 'IP address and ports at which this node can be reached.
'
type: string
IndexInfo:
description: IndexInfo contains information about a registry.
type: object
x-nullable: true
properties:
Name:
description: 'Name of the registry, such as "docker.io".
'
type: string
example: docker.io
Mirrors:
description: 'List of mirrors, expressed as URIs.
'
type: array
items:
type: string
example:
- https://hub-mirror.corp.example.com:5000/
- https://registry-2.docker.io/
- https://registry-3.docker.io/
Secure:
description: 'Indicates if the registry is part of the list of insecure
registries.
If `false`, the registry is insecure. Insecure registries accept
un-encrypted (HTTP) and/or untrusted (HTTPS with certificates from
unknown CAs) communication.
> **Warning**: Insecure registries can be useful when running a local
> registry. However, because its use creates security vulnerabilities
> it should ONLY be enabled for testing purposes. For increased
> security, users should add their CA to their system''s list of
> trusted CAs instead of enabling this option.
'
type: boolean
example: true
Official:
description: 'Indicates whether this is an official registry (i.e., Docker Hub / docker.io)
'
type: boolean
example: true
SystemInfo:
type: object
properties:
ID:
description: 'Unique identifier of the daemon.
<p><br /></p>
> **Note**: The format of the ID itself is not part of the API, and
> should not be considered stable.
'
type: string
example: 7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS
Containers:
description: Total number of containers on the host.
type: integer
example: 14
ContainersRunning:
description: 'Number of containers with status `"running"`.
'
type: integer
example: 3
ContainersPaused:
description: 'Number of containers with status `"paused"`.
'
type: integer
example: 1
ContainersStopped:
description: 'Number of containers with status `"stopped"`.
'
type: integer
example: 10
Images:
description: 'Total number of images on the host.
Both _tagged_ and _untagged_ (dangling) images are counted.
'
type: integer
example: 508
Driver:
description: Name of the storage driver in use.
type: string
example: overlay2
DriverStatus:
description: 'Information specific to the storage driver, provided as
"label" / "value" pairs.
This information is provided by the storage driver, and formatted
in a way consistent with the output of `docker info` on the command
line.
<p><br /></p>
> **Note**: The information returned in this field, including the
> formatting of values and labels, should not be considered stable,
> and may change without notice.
'
type: array
items:
type: array
items:
type: string
example:
- - Backing Filesystem
- extfs
- - Supports d_type
- 'true'
- - Native Overlay Diff
- 'true'
DockerRootDir:
description: 'Root directory of persistent Docker state.
Defaults to `/var/lib/docker` on Linux, and `C:\ProgramData\docker`
on Windows.
'
type: string
example: /var/lib/docker
Plugins:
$ref: '#/definitions/PluginsInfo'
MemoryLimit:
description: Indicates if the host has memory limit support enabled.
type: boolean
example: true
SwapLimit:
description: Indicates if the host has memory swap limit support enabled.
type: boolean
example: true
CpuCfsPeriod:
description: 'Indicates if CPU CFS(Completely Fair Scheduler) period is supported by
the host.
'
type: boolean
example: true
CpuCfsQuota:
description: 'Indicates if CPU CFS(Completely Fair Scheduler) quota is supported by
the host.
'
type: boolean
example: true
CPUShares:
description: 'Indicates if CPU Shares limiting is supported by the host.
'
type: boolean
example: true
CPUSet:
description: 'Indicates if CPUsets (cpuset.cpus, cpuset.mems) are supported by the host.
See [cpuset(7)](https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt)
'
type: boolean
example: true
PidsLimit:
description: Indicates if the host kernel has PID limit support enabled.
type: boolean
example: true
OomKillDisable:
description: Indicates if OOM killer disable is supported on the host.
type: boolean
IPv4Forwarding:
description: Indicates IPv4 forwarding is enabled.
type: boolean
example: true
Debug:
description: 'Indicates if the daemon is running in debug-mode / with debug-level
logging enabled.
'
type: boolean
example: true
NFd:
description: 'The total number of file Descriptors in use by the daemon process.
This information is only returned if debug-mode is enabled.
'
type: integer
example: 64
NGoroutines:
description: 'The number of goroutines that currently exist.
This information is only returned if debug-mode is enabled.
'
type: integer
example: 174
SystemTime:
description: 'Current system-time in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt)
format with nano-seconds.
'
type: string
example: '2017-08-08T20:28:29.06202363Z'
LoggingDriver:
description: 'The logging driver to use as a default for new containers.
'
type: string
CgroupDriver:
description: 'The driver to use for managing cgroups.
'
type: string
enum:
- cgroupfs
- systemd
- none
default: cgroupfs
example: cgroupfs
CgroupVersion:
description: 'The version of the cgroup.
'
type: string
enum:
- '1'
- '2'
default: '1'
example: '1'
NEventsListener:
description: Number of event listeners subscribed.
type: integer
example: 30
KernelVersion:
description: 'Kernel version of the host.
On Linux, this information obtained from `uname`. On Windows this
information is queried from the <kbd>HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\</kbd>
registry value, for example _"10.0 14393 (14393.1198.amd64fre.rs1_release_sec.170427-1353)"_.
'
type: string
example: 6.8.0-31-generic
OperatingSystem:
description: 'Name of the host''s operating system, for example: "Ubuntu 24.04 LTS"
or "Windows Server 2016 Datacenter"
'
type: string
example: Ubuntu 24.04 LTS
OSVersion:
description: 'Version of the host''s operating system
<p><br /></p>
> **Note**: The information returned in this field, including its
> very existence, and the formatting of values, should not be considered
> stable, and may change without notice.
'
type: string
example: '24.04'
OSType:
description: 'Generic type of the operating system of the host, as returned by the
Go runtime (`GOOS`).
Currently returned values are "linux" and "windows". A full list of
possible values can be found in the [Go documentation](https://go.dev/doc/install/source#environment).
'
type: string
example: linux
Architecture:
description: 'Hardware architecture of the host, as returned by the operating system.
This is equivalent to the output of `uname -m` on Linux.
Unlike `Arch` (from `/version`), this reports the machine''s native
architecture, which can differ from the Go runtime architecture when
running a binary compiled for a different architecture (for example,
a 32-bit binary running on 64-bit hardware).
'
type: string
example: x86_64
NCPU:
description: 'The number of logical CPUs usable by the daemon.
The number of available CPUs is checked by querying the operating
system when the daemon starts. Changes to operating system CPU
allocation after the daemon is started are not reflected.
'
type: integer
example: 4
MemTotal:
description: 'Total amount of physical memory available on the host, in bytes.
'
type: integer
format: int64
example: 2095882240
IndexServerAddress:
description: 'Address / URL of the index server that is used for image search,
and as a default for user authentication for Docker Hub and Docker Cloud.
'
default: https://index.docker.io/v1/
type: string
example: https://index.docker.io/v1/
RegistryConfig:
$ref: '#/definitions/RegistryServiceConfig'
GenericResources:
$ref: '#/definitions/GenericResources'
HttpProxy:
description: 'HTTP-proxy configured for the daemon. This value is obtained from the
[`HTTP_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable.
Credentials ([user info component](https://tools.ietf.org/html/rfc3986#section-3.2.1)) in the proxy URL
are masked in the API response.
Containers do not automatically inherit this configuration.
'
type: string
example: http://xxxxx:xxxxx@proxy.corp.example.com:8080
HttpsProxy:
description: 'HTTPS-proxy configured for the daemon. This value is obtained from the
[`HTTPS_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable.
Credentials ([user info component](https://tools.ietf.org/html/rfc3986#section-3.2.1)) in the proxy URL
are masked in the API response.
Containers do not automatically inherit this configuration.
'
type: string
example: https://xxxxx:xxxxx@proxy.corp.example.com:4443
NoProxy:
description: 'Comma-separated list of domain extensions for which no proxy should be
used. This value is obtained from the [`NO_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html)
environment variable.
Containers do not automatically inherit this configuration.
'
type: string
example: '*.local, 169.254/16'
Name:
description: Hostname of the host.
type: string
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
ServerVersion:
description: 'Version string of the daemon.
'
type: string
example: 27.0.1
Runtimes:
description: 'List of [OCI compliant](https://github.com/opencontainers/runtime-spec)
runtimes configured on the daemon. Keys hold the "name" used to
reference the runtime.
The Docker daemon relies on an OCI compliant runtime (invoked via the
`containerd` daemon) as its interface to the Linux kernel namespaces,
cgroups, and SELinux.
The default runtime is `runc`, and automatically configured. Additional
runtimes can be configured by the user and will be listed here.
'
type: object
additionalProperties:
$ref: '#/definitions/Runtime'
default:
runc:
path: runc
example:
runc:
path: runc
runc-master:
path: /go/bin/runc
custom:
path: /usr/local/bin/my-oci-runtime
runtimeArgs:
- --debug
- --systemd-cgroup=false
DefaultRuntime:
description: 'Name of the default OCI runtime that is used when starting containers.
The default can be overridden per-container at create time.
'
type: string
default: runc
example: runc
Swarm:
$ref: '#/definitions/SwarmInfo'
LiveRestoreEnabled:
description: 'Indicates if live restore is enabled.
If enabled, containers are kept running when the daemon is shutdown
or upon daemon start if running containers are detected.
'
type: boolean
default: false
example: false
Isolation:
description: 'Represents the isolation technology to use as a default for containers.
The supported values are platform-specific.
If no isolation value is specified on daemon start, on Windows client,
the default is `hyperv`, and on Windows server, the default is `process`.
This option is currently not used on other platforms.
'
default: default
type: string
enum:
- default
- hyperv
- process
- ''
InitBinary:
description: 'Name and, optional, path of the `docker-init` binary.
If the path is omitted, the daemon searches the host''s `$PATH` for the
binary and uses the first result.
'
type: string
example: docker-init
ContainerdCommit:
$ref: '#/definitions/Commit'
RuncCommit:
$ref: '#/definitions/Commit'
InitCommit:
$ref: '#/definitions/Commit'
SecurityOptions:
description: 'List of security features that are enabled on the daemon, such as
apparmor, seccomp, SELinux, user-namespaces (userns), rootless and
no-new-privileges.
Additional configuration options for each security feature may
be present, and are included as a comma-separated list of key/value
pairs.
'
type: array
items:
type: string
example:
- name=apparmor
- name=seccomp,profile=default
- name=selinux
- name=userns
- name=rootless
ProductLicense:
description: 'Reports a summary of the product license on the daemon.
If a commercial license has been applied to the daemon, information
such as number of nodes, and expiration are included.
'
type: string
example: Community Engine
DefaultAddressPools:
description: 'List of custom default address pools for local networks, which can be
specified in the daemon.json file or dockerd option.
Example: a Base "10.10.0.0/16" with Size 24 will define the set of 256
10.10.[0-255].0/24 address pools.
'
type: array
items:
type: object
properties:
Base:
description: The network address in CIDR format
type: string
example: 10.10.0.0/16
Size:
description: The network pool size
type: integer
example: '24'
FirewallBackend:
$ref: '#/definitions/FirewallInfo'
DiscoveredDevices:
description: 'List of devices discovered by device drivers.
Each device includes information about its source driver, kind, name,
and additional driver-specific attributes.
'
type: array
items:
$ref: '#/definitions/DeviceInfo'
NRI:
$ref: '#/definitions/NRIInfo'
Warnings:
description: 'List of warnings / informational messages about missing features, or
issues related to the daemon configuration.
These messages can be printed by the client as information to the user.
'
type: array
items:
type: string
example:
- 'WARNING: No memory limit support'
CDISpecDirs:
description: 'List of directories where (Container Device Interface) CDI
specifications are located.
These specifications define vendor-specific modifications to an OCI
runtime specification for a container being created.
An empty list indicates that CDI device injection is disabled.
Note that since using CDI device injection requires the daemon to have
experimental enabled. For non-experimental daemons an empty list will
always be returned.
'
type: array
items:
type: string
example:
- /etc/cdi
- /var/run/cdi
Containerd:
$ref: '#/definitions/ContainerdInfo'
VolumesDiskUsage:
type: object
x-go-name: DiskUsage
x-go-package: github.com/moby/moby/api/types/volume
description: 'represents system data usage for volume resources.
'
properties:
ActiveCount:
description: 'Count of active volumes.
'
type: integer
format: int64
example: 1
TotalCount:
description: 'Count of all volumes.
'
type: integer
format: int64
example: 4
Reclaimable:
description: 'Disk space that can be reclaimed by removing inactive volumes.
'
type: integer
format: int64
example: 12345678
TotalSize:
description: 'Disk space in use by volumes.
'
type: integer
format: int64
example: 98765432
Items:
description: 'List of volumes.
'
type: array
x-omitempty: true
items:
x-go-type:
type: Volume
FirewallInfo:
description: 'Information about the daemon''s firewalling configuration.
This field is currently only used on Linux, and omitted on other platforms.
'
type: object
x-nullable: true
properties:
Driver:
description: 'The name of the firewall backend driver.
'
type: string
example: nftables
Info:
description: 'Information about the fire
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-system-api-openapi.yml