Docker Swarm API
Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/docker-swarm-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Docker Engine Config Swarm 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"
servers:
- url: /v1.54
tags:
- 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.
'
paths:
/swarm:
get:
summary: Inspect swarm
operationId: SwarmInspect
responses:
200:
description: no error
content:
application/json:
schema:
$ref: '#/components/schemas/Swarm'
text/plain:
schema:
$ref: '#/components/schemas/Swarm'
404:
description: no such swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
503:
description: node is not part of a swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Swarm
/swarm/init:
post:
summary: Initialize a new swarm
operationId: SwarmInit
responses:
200:
description: no error
content:
application/json:
schema:
description: The node ID
type: string
example: 7v2t30z9blmxuhnyo6s4cpenp
text/plain:
schema:
description: The node ID
type: string
example: 7v2t30z9blmxuhnyo6s4cpenp
400:
description: bad parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
503:
description: node is already part of a swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Swarm
requestBody:
content:
application/json:
schema:
type: object
title: SwarmInitRequest
properties:
ListenAddr:
description: 'Listen address used for inter-manager communication, as well
as determining the networking interface used for the VXLAN
Tunnel Endpoint (VTEP). This can either be an address/port
combination in the form `192.168.1.1:4567`, or an interface
followed by a port number, like `eth0:4567`. If the port number
is omitted, the default swarm listening port is used.
'
type: string
AdvertiseAddr:
description: 'Externally reachable address advertised to other nodes. This
can either be an address/port combination in the form
`192.168.1.1:4567`, or an interface followed by a port number,
like `eth0:4567`. If the port number is omitted, the port
number from the listen address is used. If `AdvertiseAddr` is
not specified, it will be automatically detected when possible.
'
type: string
DataPathAddr:
description: 'Address or interface to use for data path traffic (format:
`<ip|interface>`), for example, `192.168.1.1`, or an interface,
like `eth0`. If `DataPathAddr` is unspecified, the same address
as `AdvertiseAddr` is used.
The `DataPathAddr` specifies the address that global scope
network drivers will publish towards other nodes in order to
reach the containers running on this node. Using this parameter
it is possible to separate the container data traffic from the
management traffic of the cluster.
'
type: string
DataPathPort:
description: 'DataPathPort specifies the data path port number for data traffic.
Acceptable port range is 1024 to 49151.
if no port is set or is set to 0, default port 4789 will be used.
'
type: integer
format: uint32
DefaultAddrPool:
description: 'Default Address Pool specifies default subnet pools for global
scope networks.
'
type: array
items:
type: string
example:
- 10.10.0.0/16
- 20.20.0.0/16
ForceNewCluster:
description: Force creation of a new swarm.
type: boolean
SubnetSize:
description: 'SubnetSize specifies the subnet size of the networks created
from the default subnet pool.
'
type: integer
format: uint32
Spec:
$ref: '#/components/schemas/SwarmSpec'
example:
ListenAddr: 0.0.0.0:2377
AdvertiseAddr: 192.168.1.1:2377
DataPathPort: 4789
DefaultAddrPool:
- 10.10.0.0/8
- 20.20.0.0/8
SubnetSize: 24
ForceNewCluster: false
Spec:
Orchestration: {}
Raft: {}
Dispatcher: {}
CAConfig: {}
EncryptionConfig:
AutoLockManagers: false
text/plain:
schema:
type: object
title: SwarmInitRequest
properties:
ListenAddr:
description: 'Listen address used for inter-manager communication, as well
as determining the networking interface used for the VXLAN
Tunnel Endpoint (VTEP). This can either be an address/port
combination in the form `192.168.1.1:4567`, or an interface
followed by a port number, like `eth0:4567`. If the port number
is omitted, the default swarm listening port is used.
'
type: string
AdvertiseAddr:
description: 'Externally reachable address advertised to other nodes. This
can either be an address/port combination in the form
`192.168.1.1:4567`, or an interface followed by a port number,
like `eth0:4567`. If the port number is omitted, the port
number from the listen address is used. If `AdvertiseAddr` is
not specified, it will be automatically detected when possible.
'
type: string
DataPathAddr:
description: 'Address or interface to use for data path traffic (format:
`<ip|interface>`), for example, `192.168.1.1`, or an interface,
like `eth0`. If `DataPathAddr` is unspecified, the same address
as `AdvertiseAddr` is used.
The `DataPathAddr` specifies the address that global scope
network drivers will publish towards other nodes in order to
reach the containers running on this node. Using this parameter
it is possible to separate the container data traffic from the
management traffic of the cluster.
'
type: string
DataPathPort:
description: 'DataPathPort specifies the data path port number for data traffic.
Acceptable port range is 1024 to 49151.
if no port is set or is set to 0, default port 4789 will be used.
'
type: integer
format: uint32
DefaultAddrPool:
description: 'Default Address Pool specifies default subnet pools for global
scope networks.
'
type: array
items:
type: string
example:
- 10.10.0.0/16
- 20.20.0.0/16
ForceNewCluster:
description: Force creation of a new swarm.
type: boolean
SubnetSize:
description: 'SubnetSize specifies the subnet size of the networks created
from the default subnet pool.
'
type: integer
format: uint32
Spec:
$ref: '#/components/schemas/SwarmSpec'
example:
ListenAddr: 0.0.0.0:2377
AdvertiseAddr: 192.168.1.1:2377
DataPathPort: 4789
DefaultAddrPool:
- 10.10.0.0/8
- 20.20.0.0/8
SubnetSize: 24
ForceNewCluster: false
Spec:
Orchestration: {}
Raft: {}
Dispatcher: {}
CAConfig: {}
EncryptionConfig:
AutoLockManagers: false
required: true
/swarm/join:
post:
summary: Join an existing swarm
operationId: SwarmJoin
responses:
200:
description: no error
400:
description: bad parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
503:
description: node is already part of a swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Swarm
requestBody:
content:
application/json:
schema:
type: object
title: SwarmJoinRequest
properties:
ListenAddr:
description: 'Listen address used for inter-manager communication if the node
gets promoted to manager, as well as determining the networking
interface used for the VXLAN Tunnel Endpoint (VTEP).
'
type: string
AdvertiseAddr:
description: 'Externally reachable address advertised to other nodes. This
can either be an address/port combination in the form
`192.168.1.1:4567`, or an interface followed by a port number,
like `eth0:4567`. If the port number is omitted, the port
number from the listen address is used. If `AdvertiseAddr` is
not specified, it will be automatically detected when possible.
'
type: string
DataPathAddr:
description: 'Address or interface to use for data path traffic (format:
`<ip|interface>`), for example, `192.168.1.1`, or an interface,
like `eth0`. If `DataPathAddr` is unspecified, the same address
as `AdvertiseAddr` is used.
The `DataPathAddr` specifies the address that global scope
network drivers will publish towards other nodes in order to
reach the containers running on this node. Using this parameter
it is possible to separate the container data traffic from the
management traffic of the cluster.
'
type: string
RemoteAddrs:
description: 'Addresses of manager nodes already participating in the swarm.
'
type: array
items:
type: string
JoinToken:
description: Secret token for joining this swarm.
type: string
example:
ListenAddr: 0.0.0.0:2377
AdvertiseAddr: 192.168.1.1:2377
DataPathAddr: 192.168.1.1
RemoteAddrs:
- node1:2377
JoinToken: SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2
text/plain:
schema:
type: object
title: SwarmJoinRequest
properties:
ListenAddr:
description: 'Listen address used for inter-manager communication if the node
gets promoted to manager, as well as determining the networking
interface used for the VXLAN Tunnel Endpoint (VTEP).
'
type: string
AdvertiseAddr:
description: 'Externally reachable address advertised to other nodes. This
can either be an address/port combination in the form
`192.168.1.1:4567`, or an interface followed by a port number,
like `eth0:4567`. If the port number is omitted, the port
number from the listen address is used. If `AdvertiseAddr` is
not specified, it will be automatically detected when possible.
'
type: string
DataPathAddr:
description: 'Address or interface to use for data path traffic (format:
`<ip|interface>`), for example, `192.168.1.1`, or an interface,
like `eth0`. If `DataPathAddr` is unspecified, the same address
as `AdvertiseAddr` is used.
The `DataPathAddr` specifies the address that global scope
network drivers will publish towards other nodes in order to
reach the containers running on this node. Using this parameter
it is possible to separate the container data traffic from the
management traffic of the cluster.
'
type: string
RemoteAddrs:
description: 'Addresses of manager nodes already participating in the swarm.
'
type: array
items:
type: string
JoinToken:
description: Secret token for joining this swarm.
type: string
example:
ListenAddr: 0.0.0.0:2377
AdvertiseAddr: 192.168.1.1:2377
DataPathAddr: 192.168.1.1
RemoteAddrs:
- node1:2377
JoinToken: SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2
required: true
/swarm/leave:
post:
summary: Leave a swarm
operationId: SwarmLeave
responses:
200:
description: no error
500:
description: server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
503:
description: node is not part of a swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
- name: force
description: 'Force leave swarm, even if this is the last manager or that it will
break the cluster.
'
in: query
schema:
type: boolean
default: false
tags:
- Swarm
/swarm/update:
post:
summary: Update a swarm
operationId: SwarmUpdate
responses:
200:
description: no error
400:
description: bad parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
500:
description: server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
503:
description: node is not part of a swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
- name: version
in: query
description: 'The version number of the swarm object being updated. This is
required to avoid conflicting writes.
'
required: true
schema:
type: integer
format: int64
- name: rotateWorkerToken
in: query
description: Rotate the worker join token.
schema:
type: boolean
default: false
- name: rotateManagerToken
in: query
description: Rotate the manager join token.
schema:
type: boolean
default: false
- name: rotateManagerUnlockKey
in: query
description: Rotate the manager unlock key.
schema:
type: boolean
default: false
tags:
- Swarm
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SwarmSpec'
text/plain:
schema:
$ref: '#/components/schemas/SwarmSpec'
required: true
/swarm/unlockkey:
get:
summary: Get the unlock key
operationId: SwarmUnlockkey
responses:
200:
description: no error
content:
application/json:
schema:
type: object
title: UnlockKeyResponse
properties:
UnlockKey:
description: The swarm's unlock key.
type: string
example:
UnlockKey: SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8
text/plain:
schema:
type: object
title: UnlockKeyResponse
properties:
UnlockKey:
description: The swarm's unlock key.
type: string
example:
UnlockKey: SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8
500:
description: server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
503:
description: node is not part of a swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
text/plain:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Swarm
/swarm/unlock:
post:
summary: Unlock a locked manager
operationId: SwarmUnlock
responses:
200:
description: no error
500:
description: server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
503:
description: node is not part of a swarm
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Swarm
requestBody:
content:
application/json:
schema:
type: object
title: SwarmUnlockRequest
properties:
UnlockKey:
description: The swarm's unlock key.
type: string
example:
UnlockKey: SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8
required: true
components:
schemas:
ErrorResponse:
description: Represents an error.
type: object
required:
- message
properties:
message:
description: The error message.
type: string
example:
message: Something went wrong.
TLSInfo:
description: 'Information about the issuer of leaf TLS certificates and the trusted root
CA certificate.
'
type: object
properties:
TrustRoot:
description: 'The root CA certificate(s) that are used to validate leaf TLS
certificates.
'
type: string
CertIssuerSubject:
description: The base64-url-safe-encoded raw subject bytes of the issuer.
type: string
CertIssuerPublicKey:
description: 'The base64-url-safe-encoded raw public key bytes of the issuer.
'
type: string
example:
TrustRoot: '-----BEGIN CERTIFICATE-----
MIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw
EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0
MzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf
3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
Af8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO
PQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz
pxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H
-----END CERTIFICATE-----
'
CertIssuerSubject: MBMxETAPBgNVBAMTCHN3YXJtLWNh
CertIssuerPublicKey: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A==
ClusterInfo:
description: 'ClusterInfo represents information about the swarm as is returned by the
"/info" endpoint. Join-tokens are not included.
'
type:
- object
- 'null'
properties:
ID:
description: The ID of the swarm.
type: string
example: abajmipo7b4xz5ip2nrla6b11
Version:
$ref: '#/components/schemas/ObjectVersion'
CreatedAt:
description: 'Date and time at which the swarm was initialised in
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds.
'
type: string
format: dateTime
example: '2016-08-18T10:44:24.496525531Z'
UpdatedAt:
description: 'Date and time at which the swarm was last updated in
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds.
'
type: string
format: dateTime
example: '2017-08-09T07:09:37.632105588Z'
Spec:
$ref: '#/components/schemas/SwarmSpec'
TLSInfo:
$ref: '#/components/schemas/TLSInfo'
RootRotationInProgress:
description: 'Whether there is currently a root CA rotation in progress for the swarm
'
type: boolean
example: false
DataPathPort:
description: 'DataPathPort specifies the data path port number for data traffic.
Acceptable port range is 1024 to 49151.
If no port is set or is set to 0, the default port (4789) is used.
'
type: integer
format: uint32
default: 4789
example: 4789
DefaultAddrPool:
description: 'Default Address Pool specifies default subnet pools for global scope
networks.
'
type: array
items:
type: string
format: CIDR
example:
- 10.10.0.0/16
- 20.20.0.0/16
SubnetSize:
description: 'SubnetSize specifies the subnet size of the networks created from the
default subnet pool.
'
type: integer
format: uint32
maximum: 29
default: 24
example: 24
JoinTokens:
description: 'JoinTokens contains the tokens workers and managers need to join the swarm.
'
type: object
properties:
Worker:
description: 'The token workers can use to join the swarm.
'
type: string
example: SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx
Manager:
description: 'The token managers can use to join the swarm.
'
type: string
example: SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2
ObjectVersion:
description: 'The version number of the object such as node, service, etc. This is needed
to avoid conflicting writes. The client must send the version number along
with the modified specification when updating these objects.
This approach ensures safe concurrency and determinism in that the change
on the object may not be applied if the version number has changed from the
last read. In other words, if two update requests specify the same base
version, only one of the requests can succeed. As a result, two separate
update requests that happen at the same time will not unintentionally
overwrite each other.
'
type: object
properties:
Index:
type: integer
format: uint64
example: 373531
SwarmSpec:
description: User modifiable swarm configuration.
type: object
properties:
Name:
description: Name of the swarm.
type: string
example: default
Labels:
description: User-defined key/value metadata.
type: object
additionalProperties:
type: string
example:
com.example.corp.type: production
com.example.corp.department: engineering
Orchestration:
description: Orchestration configuration.
type:
- object
- 'null'
properties:
TaskHistoryRetentionLimit:
description: 'The number of historic tasks to keep per instance or node. If
negative, never remove completed or failed tasks.
'
type: integer
format: int64
example: 10
Raft:
description: Raft configuration.
type: object
properties:
SnapshotInterval:
description: The number of log entries between snapshots.
type: integer
format: uint64
example: 10000
KeepOldSnapshots:
description: 'The number of snapshots to keep beyond the current snapshot.
'
type: integer
format: uint64
LogEntriesForSlowFollowers:
description: 'The number of log entries to keep around to sync up slow followers
after a snapshot is created.
'
type: integer
format: uint64
example: 500
ElectionTick:
description: 'The number of ticks that a follower will wait for a message from
the leader before becoming a candidate and starting an election.
`ElectionTick` must be greater than `HeartbeatTick`.
A tick current
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-swarm-api-openapi.yml