Create Network Port

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

POST /v2.0/ports

Body Structure

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

Parameters

Name	In	Type	Description
port	body	object	A port object (container for all below attributes).
admin_state_up (Optional)	body	boolean	Administrative state of the port: up (true) or down (false). Default: true.
allowed_address_pairs (Optional)	body	array	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_id (Optional)	body	string	ID of the host where the port should reside.
binding:profile (Optional)	body	object	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_type (Optional)	body	string	Desired vNIC type. One of: normal, macvtap, direct, baremetal, direct-physical, virtio-forwarder, smart-nic, remote-managed. Default: normal.
device_id (Optional)	body	string	ID of the device (e.g. server instance or router) that will use this port.
device_owner (Optional)	body	string	Entity type using the port (e.g. compute:nova, network:dhcp, network:router_interface).
dns_domain (Optional)	body	string	Valid DNS domain to associate.
dns_name (Optional)	body	string	Valid DNS name (hostname) to associate.
extra_dhcp_opts (Optional)	body	array	Zero or more DHCP option objects (opt_name, opt_value).
fixed_ips (Optional)	body	array	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.
hints (Optional)	body	object	Admin-only. Mechanism-driver keyed dict (e.g. {"openvswitch": {"other_config": {"tx-steering": "hash"}}}). Max length 4095 chars serialized.
mac_address (Optional)	body	string	Port MAC address. Auto-generated if omitted.
name (Optional)	body	string	Human-readable name of the port.
network_id	body	string	ID of the network to attach the port to. (Required)
numa_affinity_policy (Optional)	body	string	NUMA affinity policy: none, required, preferred, or legacy.
port_security_enabled (Optional)	body	boolean	Enable (true) or disable (false) security group & anti-spoofing enforcement. Defaults to network setting.
project_id (Optional)	body	string	Project ID that will own the port (admin / advsvc only if different from own).
qos_policy_id (Optional)	body	string	QoS policy ID to apply.
security_groups (Optional)	body	array	List of security group IDs. If omitted defaults to the network's configured default security groups (or none).
tenant_id (Optional)	body	string	Deprecated alias of project_id.
propagate_uplink_status (Optional)	body	boolean	Whether uplink status is propagated (true/false).
description (Optional)	body	string	Human-readable description. Default: empty string.
mac_learning_enabled (Optional)	body	boolean	Enable MAC learning on the port.
port_trusted_vif (Optional)	body	boolean	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.

Name	In	Type	Description
port	body	object	Port object.
admin_state_up	body	boolean	Administrative state (true or false).
allowed_address_pairs	body	array	Allowed address pairs (see request).
binding:host_id	body	string	ID of host where the port resides.
binding:profile	body	object	Backend-specific VIF info (empty {} if none).
binding:vif_details	body	object	Additional details (e.g. port_filter, ovs_hybrid_plug).
binding:vif_type	body	string	Mechanism driver type (ovs, bridge, macvtap, etc.) or unbound / binding_failed.
binding:vnic_type	body	string	vNIC type requested / in effect.
created_at	body	string	Creation timestamp (ISO 8601).
data_plane_status	body	string	Underlying data plane status (deployment-specific).
device_id	body	string	ID of the attached device (empty if none yet).
device_owner	body	string	Owner entity type.
dns_assignment	body	object	Internal DNS assignment (hostname, ip_address, fqdn).
dns_domain	body	string	DNS domain.
dns_name	body	string	DNS name.
extra_dhcp_opts	body	array	Extra DHCP options applied.
fixed_ips	body	array	Assigned IP addresses (list of {subnet_id, ip_address}).
hints	body	object	OVS Userspace Tx packet steering hints if provided.
id	body	string	Port ID.
ip_allocation	body	string	Allocation mode (immediate, deferred, or none).
mac_address	body	string	MAC address (may be overridden by binding for direct-physical).
name	body	string	Port name.
network_id	body	string	Network ID.
numa_affinity_policy (Optional)	body	string	NUMA affinity policy.
port_security_enabled	body	boolean	Whether port security is enabled.
project_id	body	string	Owning project ID.
qos_network_policy_id	body	string	QoS policy of the network (if any).
qos_policy_id	body	string	QoS policy applied directly to the port (if any).
revision_number	body	integer	Revision number.
resource_request (Optional)	body	object	Placement resource groups / traits requested.
security_groups	body	array	Security group IDs on the port.
status	body	string	Port status: ACTIVE, DOWN, BUILD, or ERROR.
tenant_id	body	string	Project ID (legacy field).
updated_at	body	string	Last update timestamp (ISO 8601) or null.
propagate_uplink_status	body	boolean	Uplink status propagation flag.
description	body	string	Description.
mac_learning_enabled (Optional)	body	boolean	Whether MAC learning is enabled.
port_trusted_vif	body	boolean	Trusted VIF status.
tags	body	array	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

{
    "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