# Join an existing swarm


[API catalog](/reference/api/) · [Docker Engine overview](/reference/api/engine/version/v1.57/) · [Product manual](https://docs.docker.com/engine/) · [OpenAPI specification](/reference/api/engine/version/v1.57.yaml)

API version: 1.57





`POST /swarm/join`



## Connection and access

[API connection and authentication guidance](/reference/api/engine/version/v1.57/#connection)


Server: `/v1.57`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
null
```

## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request POST \
  --unix-socket "${DOCKER_SOCKET:-/var/run/docker.sock}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathAddr": "192.168.1.1",
  "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
  "ListenAddr": "0.0.0.0:2377",
  "RemoteAddrs": [
    "node1:2377"
  ]
}' \
  'http://localhost/v1.57/swarm/join'
```



## Parameters

## Request and responses

### Request  application/json




Schema:

```json
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathAddr": "192.168.1.1",
    "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
    "ListenAddr": "0.0.0.0:2377",
    "RemoteAddrs": [
      "node1:2377"
    ]
  },
  "properties": {
    "AdvertiseAddr": {
      "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
      "type": "string"
    },
    "DataPathAddr": {
      "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
      "type": "string"
    },
    "JoinToken": {
      "description": "Secret token for joining this swarm.",
      "type": "string"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
      "type": "string"
    },
    "RemoteAddrs": {
      "description": "Addresses of manager nodes already participating in the swarm.\n",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "ListenAddr",
    "RemoteAddrs",
    "JoinToken"
  ],
  "title": "SwarmJoinRequest",
  "type": "object"
}
```









Schema example:
```json
{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathAddr": "192.168.1.1",
  "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
  "ListenAddr": "0.0.0.0:2377",
  "RemoteAddrs": [
    "node1:2377"
  ]
}
```


### Request  text/plain




Schema:

```json
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathAddr": "192.168.1.1",
    "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
    "ListenAddr": "0.0.0.0:2377",
    "RemoteAddrs": [
      "node1:2377"
    ]
  },
  "properties": {
    "AdvertiseAddr": {
      "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
      "type": "string"
    },
    "DataPathAddr": {
      "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
      "type": "string"
    },
    "JoinToken": {
      "description": "Secret token for joining this swarm.",
      "type": "string"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
      "type": "string"
    },
    "RemoteAddrs": {
      "description": "Addresses of manager nodes already participating in the swarm.\n",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "ListenAddr",
    "RemoteAddrs",
    "JoinToken"
  ],
  "title": "SwarmJoinRequest",
  "type": "object"
}
```









Schema example:
```json
{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathAddr": "192.168.1.1",
  "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
  "ListenAddr": "0.0.0.0:2377",
  "RemoteAddrs": [
    "node1:2377"
  ]
}
```


### Response 200 application/json

no error











### Response 200 text/plain

no error











### Response 400 application/json

bad parameter


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 500 application/json

server error


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 503 application/json

node is already part of a swarm


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


## Complete operation contract

```json
{
  "operationId": "SwarmJoin",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathAddr": "192.168.1.1",
            "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
            "ListenAddr": "0.0.0.0:2377",
            "RemoteAddrs": [
              "node1:2377"
            ]
          },
          "properties": {
            "AdvertiseAddr": {
              "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
              "type": "string"
            },
            "DataPathAddr": {
              "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
              "type": "string"
            },
            "JoinToken": {
              "description": "Secret token for joining this swarm.",
              "type": "string"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
              "type": "string"
            },
            "RemoteAddrs": {
              "description": "Addresses of manager nodes already participating in the swarm.\n",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "ListenAddr",
            "RemoteAddrs",
            "JoinToken"
          ],
          "title": "SwarmJoinRequest",
          "type": "object"
        }
      },
      "text/plain": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathAddr": "192.168.1.1",
            "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
            "ListenAddr": "0.0.0.0:2377",
            "RemoteAddrs": [
              "node1:2377"
            ]
          },
          "properties": {
            "AdvertiseAddr": {
              "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
              "type": "string"
            },
            "DataPathAddr": {
              "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
              "type": "string"
            },
            "JoinToken": {
              "description": "Secret token for joining this swarm.",
              "type": "string"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
              "type": "string"
            },
            "RemoteAddrs": {
              "description": "Addresses of manager nodes already participating in the swarm.\n",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "ListenAddr",
            "RemoteAddrs",
            "JoinToken"
          ],
          "title": "SwarmJoinRequest",
          "type": "object"
        }
      }
    },
    "required": true,
    "x-codegen-request-body-name": "body"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {},
        "text/plain": {}
      },
      "description": "no error"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "bad parameter"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    },
    "503": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "node is already part of a swarm"
    }
  },
  "summary": "Join an existing swarm",
  "tags": [
    "Swarm"
  ]
}
```

## Referenced schemas

- [#/components/schemas/ErrorResponse](/reference/api/engine/version/v1.57/schemas/ErrorResponse/)




