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

admin_state_upboolean

Filter by administrative state: up (true) or down (false).

bindingstring

Filter by the ID of the host where the port resides.

descriptionstring

Filter by the human-readable description of the port.

device_idstring

Filter by the ID of the device that uses this port (for example, a server instance or a logical router ID).

device_ownerstring

Filter by the entity type that uses this port (for example, compute:nova, network:dhcp, network:router_interface).

fixed_ipsarray

Filter by IP addresses for the port. Each entry can include ip_address, ip_address_substr, and/or subnet_id.

idstring

Filter by the ID of the port.

ip_allocationstring

Filter ports using deferred, immediate, or no IP allocation (none).

mac_addressstring

Filter by the MAC address of the port.

namestring

Filter by the human-readable name of the port.

network_idstring

Filter by the ID of the attached network.

project_idstring

Filter by the ID of the project that owns the resource.

revision_numberinteger

Filter by the revision number of the resource.

sort_dirstring

Sort direction, asc or desc. Multiple sort_key/sort_dir pairs allowed.

sort_keystring

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.

statusstring

Filter by port status: ACTIVE, DOWN, BUILD, ERROR.

tenant_idstring

Filter by the ID of the project that owns the resource.

tagsstring

Return resources that match all specified tags (comma-separated).

tags-anystring

Return resources that match any of the specified tags (comma-separated).

not-tagsstring

Exclude resources that match all specified tags (comma-separated).

not-tags-anystring

Exclude resources that match any of the specified tags (comma-separated).

fieldsstring

Limit returned fields. Can be specified multiple times, e.g. fields=id&fields=name.

mac_learning_enabledboolean

Filter by mac learning state: enabled (true) or disabled (false).

Sample Request

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

HTTP

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

Response

Response Parameters

portsarrayrequired

A list of port objects.

admin_state_upbooleanrequired

Administrative state: up (true) or down (false).

allowed_address_pairsarrayrequired

Zero or more allowed address pair objects (ip_address, mac_address).

bindingstringrequired

ID of the host where the port resides.

bindingobjectrequired

Host/driver specific VIF binding information.

bindingobjectrequired

Additional information on the port (for example, port_filter, ovs_hybrid_plug).

bindingstringrequired

Mechanism type used for the port (for example, ovs, bridge, vhostuser). Includes special values: unbound, binding_failed.

bindingstringrequired

vNIC type to which the port should be attached (normal, direct, etc.).

created_atstringrequired

ISO 8601 creation timestamp.

data_plane_statusstringrequired

Status of the underlying data plane of a port.

descriptionstringrequired

Human-readable description for the port.

device_idstringrequired

ID of the device using the port (for example, server instance or logical router ID).

device_ownerstringrequired

Entity type that uses the port (for example, network:router_interface).

dns_assignmentobjectrequired

Networking internal DNS assignment for the port.

dns_domainstringrequired

DNS domain.

dns_namestringrequired

DNS name.

extra_dhcp_optsarrayrequired

Extra DHCP option pairs.

fixed_ipsarrayrequired

One or more fixed IPs (ip_address, subnet_id).

idstringrequired

Port ID.

ip_allocationstringrequired

When IPs are allocated: deferred, immediate, or none.

mac_addressstringrequired

Port MAC address.

namestringrequired

Port name.

network_idstringrequired

Attached network ID.

port_security_enabledbooleanrequired

Whether port security is enabled.

project_idstringrequired

Project ID.

qos_network_policy_idstringrequired

QoS policy ID of the network where the port is plugged.

qos_policy_idstringrequired

QoS policy ID associated with the port.

revision_numberintegerrequired

Revision number.

resource_requestobject

Placement resources and traits requested by the port.

security_groupsarrayrequired

Security group IDs applied to the port.

statusstringrequired

Port status (ACTIVE, DOWN, BUILD, ERROR).

tenant_idstringrequired

Project ID.

tagsarrayrequired

List of tags on the resource.

updated_atstringrequired

ISO 8601 update timestamp or null.

propagate_uplink_statusbooleanrequired

Uplink status propagation (true/false).

mac_learning_enabledboolean

Whether MAC Learning is enabled on the port.

Sample Response

Response body

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