Create Network Port

POST/v2.0/ports

Create a network port on a specified network.

Default policy settings allow you to create ports only on networks that belong to your project (unless you have administrative privileges).

Request

Body Structure

Top-level JSON object must contain a single port object with the attributes below.

Parameters

portobjectrequired

A port object (container for all below attributes).

admin_state_upboolean

Administrative state of the port: up (true) or down (false). Default: true.

allowed_address_pairsarray

Zero or more objects each with ip_address (required) and optional mac_address. ip_address may be a single IP or CIDR. If mac_address omitted it defaults to the port MAC. Enables a server to send packets with those source addresses.

binding:host_idstring

ID of the host where the port should reside.

binding:profileobject

Opaque dict for backend-specific VIF information. Use device_mac_address when binding a direct-physical port to override MAC. Empty object {} by default.

binding:vnic_typestring

Desired vNIC type. One of: normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic, remote-managed. Default: normal.

device_idstring

ID of the device (e.g. server instance or router) that will use this port.

device_ownerstring

Entity type using the port (e.g. compute:nova, network:dhcp, network:router_interface).

dns_domainstring

Valid DNS domain to associate.

dns_namestring

Valid DNS name (hostname) to associate.

extra_dhcp_optsarray

Zero or more DHCP option objects (opt_name, opt_value).

fixed_ipsarray

Assign specific IPs. Each entry may include subnet_id and/or ip_address. Logic: supply both to request a precise address; only subnet_id to auto-allocate from that subnet; only ip_address to allocate if valid on any subnet of the network.

hintsobject

Admin-only. Mechanism-driver keyed dict (e.g. {"openvswitch": {"other_config": {"tx-steering": "hash"}}}). Max length 4095 chars serialized.

mac_addressstring

Port MAC address. Auto-generated if omitted.

namestring

Human-readable name of the port.

network_idstringrequired

ID of the network to attach the port to. (Required)

numa_affinity_policystring

NUMA affinity policy: none, required, preferred, or legacy.

port_security_enabledboolean

Enable (true) or disable (false) security group & anti-spoofing enforcement. Defaults to network setting.

project_idstring

Project ID that will own the port (admin / advsvc only if different from own).

qos_policy_idstring

QoS policy ID to apply.

security_groupsarray

List of security group IDs. If omitted defaults to the network's configured default security groups (or none).

tenant_idstring

Deprecated alias of project_id.

propagate_uplink_statusboolean

Whether uplink status is propagated (true/false).

descriptionstring

Human-readable description. Default: empty string.

mac_learning_enabledboolean

Enable MAC learning on the port.

port_trusted_vifboolean

Trusted VIF status (true/false). Reflected inside binding:profile.

Example Request

curl -ks -H 'Content-Type: application/json' \
     -H 'X-Auth-Token: gAAAAA<...>' \
     -d '{
    "port": {
        "name": "private-port",
        "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
        "fixed_ips": [
            {
                "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                "ip_address": "192.168.1.12"
            }
        ]
    }
}' \
https://<node_IP_addr>:9696/v2.0/ports

Response

Response Parameters

If successful the API returns a single port object containing the created resource.

portobjectrequired

Port object.

admin_state_upbooleanrequired

Administrative state (true or false).

allowed_address_pairsarrayrequired

Allowed address pairs (see request).

binding:host_idstringrequired

ID of host where the port resides.

binding:profileobjectrequired

Backend-specific VIF info (empty {} if none).

binding:vif_detailsobjectrequired

Additional details (e.g. port_filter, ovs_hybrid_plug).

binding:vif_typestringrequired

Mechanism driver type (ovs, bridge, macvtap, etc.) or unbound / binding_failed.

binding:vnic_typestringrequired

vNIC type requested / in effect.

created_atstringrequired

Creation timestamp (ISO 8601).

data_plane_statusstringrequired

Underlying data plane status (deployment-specific).

device_idstringrequired

ID of the attached device (empty if none yet).

device_ownerstringrequired

Owner entity type.

dns_assignmentobjectrequired

Internal DNS assignment (hostname, ip_address, fqdn).

dns_domainstringrequired

DNS domain.

dns_namestringrequired

DNS name.

extra_dhcp_optsarrayrequired

Extra DHCP options applied.

fixed_ipsarrayrequired

Assigned IP addresses (list of {subnet_id, ip_address}).

hintsobjectrequired

OVS Userspace Tx packet steering hints if provided.

idstringrequired

Port ID.

ip_allocationstringrequired

Allocation mode (immediate, deferred, or none).

mac_addressstringrequired

MAC address (may be overridden by binding for direct-physical).

namestringrequired

Port name.

network_idstringrequired

Network ID.

numa_affinity_policystring

NUMA affinity policy.

port_security_enabledbooleanrequired

Whether port security is enabled.

project_idstringrequired

Owning project ID.

qos_network_policy_idstringrequired

QoS policy of the network (if any).

qos_policy_idstringrequired

QoS policy applied directly to the port (if any).

revision_numberintegerrequired

Revision number.

resource_requestobject

Placement resource groups / traits requested.

security_groupsarrayrequired

Security group IDs on the port.

statusstringrequired

Port status: ACTIVE, DOWN, BUILD, or ERROR.

tenant_idstringrequired

Project ID (legacy field).

updated_atstringrequired

Last update timestamp (ISO 8601) or null.

propagate_uplink_statusbooleanrequired

Uplink status propagation flag.

descriptionstringrequired

Description.

mac_learning_enabledboolean

Whether MAC learning is enabled.

port_trusted_vifbooleanrequired

Trusted VIF status.

tagsarrayrequired

Tag list.

Status Codes

Success

Code	Reason
201 - Created	Resource was created and is ready to use.

Error

Code	Reason
400 - Bad Request	Some content in the request was invalid.
401 - Unauthorized	User must authenticate before making a request.
403 - Forbidden	Policy does not allow current user to do this operation.
404 - Not Found	The requested resource (e.g. network) could not be found.

Example Response

Response body

{
    "port": {
        "id": "2d74fa0c-3e43-4fd9-a234-cbb4996cc684",
        "name": "private-port",
        "network_id": "f858b8d1-e66b-4a48-bc2e-3f16483b1b58",
        "tenant_id": "f33507157a634f1cac71e06a70fb558e",
        "mac_address": "fa:16:3e:7f:ae:b2",
        "admin_state_up": true,
        "status": "DOWN",
        "device_id": "",
        "device_owner": "",
        "fixed_ips": [
            {
                "subnet_id": "adffaac8-2261-43f7-9e4f-6044230f65f1",
                "ip_address": "192.168.1.12"
            }
        ],
        "project_id": "f33507157a634f1cac71e06a70fb558e",
        "port_security_enabled": true,
        "qos_policy_id": null,
        "security_groups": [
            "e1c1aa83-7302-4493-9cf4-43c2407e8074"
        ],
        "binding:vnic_type": "normal",
        "allowed_address_pairs": [],
        "extra_dhcp_opts": [],
        "description": "",
        "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
        "tags": [],
        "created_at": "2025-10-08T08:05:12Z",
        "updated_at": "2025-10-08T08:05:12Z",
        "revision_number": 1
    }
}

See Also

• Listing Network Ports