Skip to main content
POST
/
api
/
networks
curl -X POST 'https://your-dockhand.com/api/networks?env=1' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=your-session-cookie' \
  -d '{
    "name": "app-network",
    "driver": "bridge"
  }'

{
  "error": "Network name is required"
}

​
Overview

Creates a new Docker network with the specified configuration. This endpoint supports all network drivers including bridge, overlay, macvlan, and custom drivers.

​
Authentication

This endpoint requires authentication via cookies. The user must have the networks:create permission for the specified environment.

​
Query Parameters

​
env
integer
required
The environment ID where the network will be created. Required parameter.

​
Request Body

​
name
string
required
Network name. Must be unique within the environment.
​
driver
string
default:"bridge"
Network driver to use. Options: bridge, host, overlay, macvlan, ipvlan, or custom driver name.
​
internal
boolean
default:false
Whether to restrict external access to the network. Internal networks have no connectivity to external networks.
​
attachable
boolean
default:false
Enable manual container attachment. Useful for swarm overlay networks that need standalone container access.
​
ingress
boolean
default:false
Create as swarm ingress network. Only one ingress network can exist per swarm.
​
enableIPv6
boolean
default:false
Enable IPv6 networking.
​
options
object
Network driver options as key-value pairs.
​
labels
object
User-defined labels as key-value pairs for organizing and identifying networks.
​
ipam
object
IP Address Management (IPAM) configuration.

​
Response

​
success
boolean
Whether the network was created successfully
​
id
string
The ID of the newly created network

​
Error Responses

{
  "error": "Network name is required"
}

curl -X POST 'https://your-dockhand.com/api/networks?env=1' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=your-session-cookie' \
  -d '{
    "name": "app-network",
    "driver": "bridge"
  }'

{
  "success": true,
  "id": "c7b9a6e5f8d3a1b2c3d4e5f6"
}

​
Examples

​
Bridge Network

Create a standard bridge network for container communication: 
{
  "name": "app-network",
  "driver": "bridge",
  "ipam": {
    "config": [{
      "subnet": "172.18.0.0/16",
      "gateway": "172.18.0.1"
    }]
  }
}

​
Overlay Network (Swarm)

Create an encrypted overlay network for swarm services: 
{
  "name": "swarm-overlay",
  "driver": "overlay",
  "attachable": true,
  "ipam": {
    "config": [{
      "subnet": "10.0.9.0/24",
      "gateway": "10.0.9.1"
    }]
  },
  "options": {
    "encrypted": "true"
  }
}

​
Macvlan Network

Create a macvlan network for containers that need physical network presence: 
{
  "name": "macvlan-net",
  "driver": "macvlan",
  "ipam": {
    "config": [{
      "subnet": "192.168.1.0/24",
      "gateway": "192.168.1.1",
      "ipRange": "192.168.1.200/28"
    }]
  },
  "options": {
    "parent": "eth0",
    "macvlan_mode": "bridge"
  }
}

​
Internal Network

Create an internal network with no external connectivity: 
{
  "name": "backend-internal",
  "driver": "bridge",
  "internal": true,
  "ipam": {
    "config": [{
      "subnet": "172.19.0.0/16",
      "gateway": "172.19.0.1"
    }]
  }
}

​
Notes

  • Network names must be unique within the environment
  • The name field is required; all other fields are optional
  • Default driver is bridge if not specified
  • IPAM configuration is optional; Docker will auto-assign if not provided
  • Network creation is audited with the user, action, and network details
  • Built-in networks (bridge, host, none) cannot be created as they already exist
  • For overlay networks, Docker must be running in swarm mode

Build docs developers (and LLMs) love

Get started for freeTalk to us