List Virtual Router Interfaces

GET /v2.0/ports

Lists ports to which the user has access.

Use this call to find port IDs of a virtual router with the specified ID. Filter with device_id={router_id}. You may also filter by device_owner=network:router_interface for internal interfaces or device_owner=network:router_gateway for the external gateway interface.

Default policy settings return only those ports that are owned by the project of the user who submits the request, unless the request is submitted by a user with administrative rights.

If the ip-substring-filtering extension is enabled, the Networking API supports IP address substring filtering on the fixed_ips attribute. If you specify an IP address substring (ip_address_substr) in an entry of the fixed_ips attribute, the API lists all ports that have an IP address matching the substring.

info

Source: list-ports

Request

Parameters

Name	In	Type	Description
admin_state_up (Optional)	query	boolean	Filter by administrative state: up (true) or down (false).
binding:host_id (Optional)	query	string	Filter by the ID of the host where the port resides.
description (Optional)	query	string	Filter by the human-readable description of the port.
device_id (Optional)	query	string	Filter by the ID of the device that uses this port (for example, a server instance or a logical router ID).
device_owner (Optional)	query	string	Filter by the entity type that uses this port (for example, `compute:nova`, `network:dhcp`, `network:router_interface`).
fixed_ips (Optional)	query	array	Filter by IP addresses for the port. Each entry can include `ip_address`, `ip_address_substr`, and/or `subnet_id`.
id (Optional)	query	string	Filter by the ID of the port.
ip_allocation (Optional)	query	string	Filter ports using deferred, immediate, or no IP allocation (`none`).
mac_address (Optional)	query	string	Filter by the MAC address of the port.
name (Optional)	query	string	Filter by the human-readable name of the port.
network_id (Optional)	query	string	Filter by the ID of the attached network.
project_id (Optional)	query	string	Filter by the ID of the project that owns the resource.
revision_number (Optional)	query	integer	Filter by the revision number of the resource.
sort_dir (Optional)	query	string	Sort direction, `asc` or `desc`. Multiple `sort_key`/`sort_dir` pairs allowed.
sort_key (Optional)	query	string	Sort by a port attribute. Allowed keys: `admin_state_up`, `device_id`, `device_owner`, `id`, `ip_allocation`, `mac_address`, `name`, `network_id`, `project_id`, `status`, `tenant_id`.
status (Optional)	query	string	Filter by port status: `ACTIVE`, `DOWN`, `BUILD`, `ERROR`.
tenant_id (Optional)	query	string	Filter by the ID of the project that owns the resource.
tags (Optional)	query	string	Return resources that match all specified tags (comma-separated).
tags-any (Optional)	query	string	Return resources that match any of the specified tags (comma-separated).
not-tags (Optional)	query	string	Exclude resources that match all specified tags (comma-separated).
not-tags-any (Optional)	query	string	Exclude resources that match any of the specified tags (comma-separated).
fields (Optional)	query	string	Limit returned fields. Can be specified multiple times, e.g. `fields=id&fields=name`.
mac_learning_enabled (Optional)	query	boolean	Filter by mac learning state: enabled (true) or disabled (false).

Sample Request

Using `curl`

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://api.vietnix.cloud:9696/v2.0/ports?device_id=66fa6a3b-4b3a-485f-819d-c671765eb915

Using HTTP request

GET https://api.vietnix.cloud:9696/v2.0/ports?device_id={router_id}
X-Auth-Token: gAAAAA<...>

Response

Response Parameters

Name	In	Type	Description
ports	body	array	A list of port objects.
admin_state_up	body	boolean	Administrative state: up (true) or down (false).
allowed_address_pairs	body	array	Zero or more allowed address pair objects (`ip_address`, `mac_address`).
binding:host_id	body	string	ID of the host where the port resides.
binding:profile	body	object	Host/driver specific VIF binding information.
binding:vif_details	body	object	Additional information on the port (for example, `port_filter`, `ovs_hybrid_plug`).
binding:vif_type	body	string	Mechanism type used for the port (for example, `ovs`, `bridge`, `vhostuser`). Includes special values: `unbound`, `binding_failed`.
binding:vnic_type	body	string	vNIC type to which the port should be attached (`normal`, `direct`, etc.).
created_at	body	string	ISO 8601 creation timestamp.
data_plane_status	body	string	Status of the underlying data plane of a port.
description	body	string	Human-readable description for the port.
device_id	body	string	ID of the device using the port (for example, server instance or logical router ID).
device_owner	body	string	Entity type that uses the port (for example, `network:router_interface`).
dns_assignment	body	object	Networking internal DNS assignment for the port.
dns_domain	body	string	DNS domain.
dns_name	body	string	DNS name.
extra_dhcp_opts	body	array	Extra DHCP option pairs.
fixed_ips	body	array	One or more fixed IPs (`ip_address`, `subnet_id`).
id	body	string	Port ID.
ip_allocation	body	string	When IPs are allocated: deferred, immediate, or `none`.
mac_address	body	string	Port MAC address.
name	body	string	Port name.
network_id	body	string	Attached network ID.
port_security_enabled	body	boolean	Whether port security is enabled.
project_id	body	string	Project ID.
qos_network_policy_id	body	string	QoS policy ID of the network where the port is plugged.
qos_policy_id	body	string	QoS policy ID associated with the port.
revision_number	body	integer	Revision number.
resource_request (Optional)	body	object	Placement resources and traits requested by the port.
security_groups	body	array	Security group IDs applied to the port.
status	body	string	Port status (`ACTIVE`, `DOWN`, `BUILD`, `ERROR`).
tenant_id	body	string	Project ID.
tags	body	array	List of tags on the resource.
updated_at	body	string	ISO 8601 update timestamp or null.
propagate_uplink_status	body	boolean	Uplink status propagation (`true`/`false`).
mac_learning_enabled (Optional)	body	boolean	Whether MAC Learning is enabled on the port.

Sample Response

{
    "ports": [
        {
            "id": "a60d084b-5bac-489c-b549-7e651b577e36",
            "name": "",
            "network_id": "36a3666a-8ed4-48bf-9528-15f573c4a4f0",
            "tenant_id": "f33507157a634f1cac71e06a70fb558e",
            "mac_address": "fa:16:3e:8a:27:15",
            "admin_state_up": true,
            "status": "ACTIVE",
            "device_id": "66fa6a3b-4b3a-485f-819d-c671765eb915",
            "device_owner": "network:router_interface_distributed",
            "fixed_ips": [
                {
                    "subnet_id": "b367fdf4-d111-4c4c-b8c2-ea5d484ac0fb",
                    "ip_address": "192.168.10.1"
                }
            ],
            "allowed_address_pairs": [],
            "extra_dhcp_opts": [],
            "security_groups": [],
            "description": "",
            "binding:vnic_type": "normal",
            "port_security_enabled": false,
            "qos_policy_id": null,
            "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
            "tags": [],
            "created_at": "2025-09-23T16:01:32Z",
            "updated_at": "2025-09-24T05:07:52Z",
            "revision_number": 18,
            "project_id": "f33507157a634f1cac71e06a70fb558e"
        },
        {
            "id": "f43d2167-fcaf-4ac7-b8ab-8d96ef896f59",
            "name": "",
            "network_id": "36a3666a-8ed4-48bf-9528-15f573c4a4f0",
            "tenant_id": "",
            "mac_address": "fa:16:3e:c9:34:38",
            "admin_state_up": true,
            "status": "ACTIVE",
            "device_id": "66fa6a3b-4b3a-485f-819d-c671765eb915",
            "device_owner": "network:router_centralized_snat",
            "fixed_ips": [
                {
                    "subnet_id": "b367fdf4-d111-4c4c-b8c2-ea5d484ac0fb",
                    "ip_address": "192.168.10.242"
                }
            ],
            "allowed_address_pairs": [],
            "extra_dhcp_opts": [],
            "security_groups": [],
            "description": "",
            "binding:vnic_type": "normal",
            "port_security_enabled": false,
            "qos_policy_id": null,
            "qos_network_policy_id": "dfc42ced-02c8-4b1f-bbe6-14cc014f259d",
            "tags": [],
            "created_at": "2025-09-23T16:01:32Z",
            "updated_at": "2025-09-24T05:07:50Z",
            "revision_number": 12,
            "project_id": ""
        }
    ]
}

Status Codes

Success

Status Code	Description
200 - OK	Request was successful.

Error

Status Code	Description
401 - Unauthorized	User must authenticate before making a request.

Request​

Parameters​

Sample Request​

Using curl​

Using HTTP request​

Response​

Response Parameters​

Sample Response​

Status Codes​

Success​

Error​