Network service API reference

The Network API reference documents every Neutron endpoint with curl examples and request bodies.

The Network service uses the OpenStack Networking (Neutron) v2.0 API. The base URL is the Network endpoint listed in your project's service catalog; the examples below use https://network.example.com as a stand-in and synthesized UUIDs for resource IDs. For error handling guidance, see the API error reference.

In the paths below, {network_id}, {subnet_id}, {port_id}, {router_id}, and {floatingip_id} are placeholders. Replace each with the ID of the resource you are acting on. These endpoints manage networks, subnets, ports, routers, and floating IPs.

Request and response conventions#

Authenticate every request with a Keystone token in the X-Auth-Token header. Requests that send a body (POST and PUT) use Content-Type: application/json.

Successful responses use these status codes:

Method	Success status	Body
`GET`	`200 OK`	The requested resource, or a list of resources
`POST`	`201 Created`	The created resource
`PUT`	`200 OK`	The updated resource
`DELETE`	`204 No Content`	Empty

Most responses wrap the resource under a single key that matches the resource singular: network, subnet, port, router, or floatingip. For example, POST /v2.0/networks returns { "network": { ... } }. Collection endpoints wrap the list under the plural key (networks, subnets, and so on). The router interface endpoints are the exception and return an unwrapped flat object, documented in Add interface to router.

Every response includes Content-Type: application/json and an X-Openstack-Request-Id header of the form req-<uuid>. Include that request ID when you report an issue.

Quake AI public networks#

ℹ️ Info

Quake AI public networks

Every project has two public networks:

Network	`router:external`	Use for
`PublicStatic`	`true`	Floating IPs and router external gateways
`PublicEphemeral`	`false`	Direct port attachment with an automatic public IP

PublicEphemeral is reachable from the public internet even though Neutron does not mark it as a router:external network. Attach a port on PublicEphemeral to an instance and its fixed IP is reachable directly from the internet, without a floating IP.

Because PublicEphemeral is not a router:external network, you cannot allocate floating IPs on it or set it as a router's external gateway. Use PublicStatic with a floating IP or a router gateway when you need a stable address that survives instance recreation, or when you need to route private traffic through NAT.

Networks#

List networks#

Method: GET
Endpoint: /v2.0/networks
Success status: 200 OK. The response has the shape { "networks": [ ... ] }.

Show network details#

Method: GET
Endpoint: /v2.0/networks/{network_id}
Success status: 200 OK.

Create a network#

Method: POST
Endpoint: /v2.0/networks
Success status: 201 Created.

Request body:

JSON

{
  "network": {
    "name": "network_name",
    "admin_state_up": true
  }
}

Response body:

JSON

{
  "network": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "network_name",
    "status": "ACTIVE",
    "router:external": false,
    "admin_state_up": true
  }
}

Update a network#

Method: PUT
Endpoint: /v2.0/networks/{network_id}
Success status: 200 OK.

Request body:

JSON

{
  "network": {
    "name": "new_network_name"
  }
}

Delete a network#

Method: DELETE
Endpoint: /v2.0/networks/{network_id}
Success status: 204 No Content.

A network with attached ports cannot be deleted; the request returns 409 Conflict with a NetworkInUse error that lists the ports still in use. Delete or detach those ports first.

Subnets#

List subnets#

Method: GET
Endpoint: /v2.0/subnets
Success status: 200 OK. The response has the shape { "subnets": [ ... ] }.

Show subnet details#

Method: GET
Endpoint: /v2.0/subnets/{subnet_id}
Success status: 200 OK.

Create a subnet#

Method: POST
Endpoint: /v2.0/subnets
Success status: 201 Created.

Request body:

JSON

{
  "subnet": {
    "network_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "ip_version": 4,
    "cidr": "192.168.1.0/24"
  }
}

Response body:

JSON

{
  "subnet": {
    "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "subnet_name",
    "cidr": "192.168.1.0/24",
    "ip_version": 4,
    "gateway_ip": "192.168.1.1",
    "network_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }
}

Update a subnet#

Method: PUT
Endpoint: /v2.0/subnets/{subnet_id}
Success status: 200 OK.

Request body:

JSON

{
  "subnet": {
    "name": "new_subnet_name"
  }
}

Delete a subnet#

Method: DELETE
Endpoint: /v2.0/subnets/{subnet_id}
Success status: 204 No Content.

Ports#

List ports#

Method: GET
Endpoint: /v2.0/ports
Success status: 200 OK. The response has the shape { "ports": [ ... ] }.

Show port details#

Method: GET
Endpoint: /v2.0/ports/{port_id}
Success status: 200 OK.

Create a port#

Method: POST
Endpoint: /v2.0/ports
Success status: 201 Created.

Request body:

JSON

{
  "port": {
    "network_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "admin_state_up": true
  }
}

Response body:

JSON

{
  "port": {
    "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
    "name": "port_name",
    "status": "DOWN",
    "mac_address": "fa:16:3e:1a:2b:3c",
    "fixed_ips": [
      {
        "subnet_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "ip_address": "192.168.1.50"
      }
    ],
    "network_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }
}

Update a port#

Method: PUT
Endpoint: /v2.0/ports/{port_id}
Success status: 200 OK.

Request body:

JSON

{
  "port": {
    "name": "new_port_name"
  }
}

Delete a port#

Method: DELETE
Endpoint: /v2.0/ports/{port_id}
Success status: 204 No Content.

Routers#

List routers#

Method: GET
Endpoint: /v2.0/routers
Success status: 200 OK. The response has the shape { "routers": [ ... ] }.

Show router details#

Method: GET
Endpoint: /v2.0/routers/{router_id}
Success status: 200 OK.

Create a router#

Method: POST
Endpoint: /v2.0/routers
Success status: 201 Created.

Request body:

JSON

{
  "router": {
    "name": "router_name",
    "admin_state_up": true
  }
}

Response body:

JSON

{
  "router": {
    "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
    "name": "router_name",
    "status": "ACTIVE",
    "admin_state_up": true,
    "external_gateway_info": null
  }
}

Update a router#

Method: PUT
Endpoint: /v2.0/routers/{router_id}
Success status: 200 OK.

Request body:

JSON

{
  "router": {
    "name": "new_router_name"
  }
}

Set a router's external gateway#

There is no dedicated set-external-gateway endpoint. Set the external gateway with PUT /v2.0/routers/{router_id}, passing external_gateway_info. Use the PublicStatic network ID as the network_id.

Method: PUT
Endpoint: /v2.0/routers/{router_id}
Success status: 200 OK.

Request body:

JSON

{
  "router": {
    "external_gateway_info": {
      "network_id": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f809102"
    }
  }
}

To remove the gateway, send the same endpoint with "external_gateway_info": null.

Add interface to router#

Method: PUT
Endpoint: /v2.0/routers/{router_id}/add_router_interface
Success status: 200 OK.

Request body:

JSON

{
  "subnet_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

This endpoint returns a flat object, not a body wrapped under a router key:

JSON

{
  "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
  "tenant_id": "f6a7b8c9d0e14f2a3b4c5d6e7f809102",
  "port_id": "e1f2a3b4-c5d6-4e7f-8091-a2b3c4d5e6f7",
  "network_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "subnet_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "subnet_ids": ["b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"]
}

Remove interface from router#

Method: PUT
Endpoint: /v2.0/routers/{router_id}/remove_router_interface
Success status: 200 OK. The response is the same flat object as Add interface to router.

Request body:

JSON

{
  "subnet_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

Floating IPs#

List floating IPs#

Method: GET
Endpoint: /v2.0/floatingips
Success status: 200 OK. The response has the shape { "floatingips": [ ... ] }.

Show floating IP details#

Method: GET
Endpoint: /v2.0/floatingips/{floatingip_id}
Success status: 200 OK.

Create a floating IP#

Allocate a floating IP from the PublicStatic network. Pass its network ID as floating_network_id.

Method: POST
Endpoint: /v2.0/floatingips
Success status: 201 Created.

Request body:

JSON

{
  "floatingip": {
    "floating_network_id": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f809102"
  }
}

Response body:

JSON

{
  "floatingip": {
    "id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8091",
    "floating_ip_address": "203.0.113.10",
    "status": "DOWN",
    "port_id": null,
    "router_id": null
  }
}

Update a floating IP#

Associate a floating IP by setting port_id to a port ID, and disassociate it by setting port_id to null.

Method: PUT
Endpoint: /v2.0/floatingips/{floatingip_id}
Success status: 200 OK.

Request body:

JSON

{
  "floatingip": {
    "port_id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f"
  }
}

Delete a floating IP#

Method: DELETE
Endpoint: /v2.0/floatingips/{floatingip_id}
Success status: 204 No Content.

Network Service API Reference

Network service API reference

Request and response conventions#

Quake AI public networks#

Networks#

List networks#

Show network details#

Create a network#

Update a network#

Delete a network#

Subnets#

List subnets#

Show subnet details#

Create a subnet#

Update a subnet#

Delete a subnet#

Ports#

List ports#

Show port details#

Create a port#

Update a port#

Delete a port#

Routers#

List routers#

Show router details#

Create a router#

Update a router#

Set a router's external gateway#

Add interface to router#

Remove interface from router#

Floating IPs#

List floating IPs#

Show floating IP details#

Create a floating IP#

Update a floating IP#

Delete a floating IP#

See Also