Ports API reference
See https://docs.openstack.org/api-ref/network/.
These endpoints list existing ports, show details of a specific port, create a port, update a port, and delete a port in the Network service.
In these endpoints, {port_id} is the ID of the port, "network_id" is the ID of the network to which the port is attached, "subnet_id" is the ID of the subnet from which the IP address is allocated, "ip_address" is the IP address assigned to the port (optional), "security_group_id" is the ID of a security group associated with the port, and "device_id" is the ID of the device (such as a server or router) to which the port is attached.
List ports#
GET /v2.0/portsReturns 200 OK. The response wraps the list under a ports key.
Show port details#
GET /v2.0/ports/{port_id}Returns 200 OK. The response wraps the port under a port key.
Create a port#
POST /v2.0/portsRequest body
{
"port": {
"network_id": "NETWORK_ID",
"name": "PORT_NAME",
"admin_state_up": true,
"fixed_ips": [{"subnet_id": "SUBNET_ID", "ip_address": "10.47.0.50"}],
"security_groups": ["SECURITY_GROUP_ID"],
"device_id": "DEVICE_ID"
}
}Returns 201 Created. The response wraps the new port under a port key. A new port reports "status": "DOWN" until it is bound to a device, then "ACTIVE".
{
"port": {
"id": "PORT_ID",
"name": "PORT_NAME",
"network_id": "NETWORK_ID",
"tenant_id": "PROJECT_ID",
"mac_address": "fa:16:3e:5d:7c:a1",
"admin_state_up": true,
"status": "DOWN",
"device_id": "",
"device_owner": "",
"fixed_ips": [{"subnet_id": "SUBNET_ID", "ip_address": "10.47.0.50"}],
"security_groups": ["SECURITY_GROUP_ID"],
"allowed_address_pairs": [],
"extra_dhcp_opts": [],
"binding:vnic_type": "normal",
"port_security_enabled": true,
"qos_policy_id": null,
"qos_network_policy_id": null,
"tags": [],
"description": "",
"created_at": "2026-06-04T12:00:00Z",
"updated_at": "2026-06-04T12:00:00Z",
"revision_number": 1,
"project_id": "PROJECT_ID"
}
}If you omit security_groups, the service assigns the project's default security group.
Update a port#
PUT /v2.0/ports/{port_id}Request body
{
"port": {
"name": "NEW_PORT_NAME",
"fixed_ips": [{"subnet_id": "SUBNET_ID", "ip_address": "10.47.0.51"}],
"security_groups": ["NEW_SECURITY_GROUP_ID"]
}
}Returns 200 OK. The response wraps the updated port under a port key and uses the same envelope as the create response, with revision_number incremented.
Delete a port#
DELETE /v2.0/ports/{port_id}Returns 204 No Content with an empty body. Deleting a port that does not exist returns 404 Not Found.
Error responses#
The Network service returns these responses for invalid requests:
401 Unauthorized: the token is missing, invalid, or expired.404 Not Found: the referenced port, network, or security group does not exist (PortNotFound,NetworkNotFound,SecurityGroupNotFound).409 Conflict: the requested fixed IP is already allocated in the subnet (IpAddressAlreadyAllocated).