> This page is for NVIDIA Infra Controller.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/infra-controller/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/infra-controller/_mcp/server.

# Retrieve Tenant-visible Interfaces

GET https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/interface

Retrieve current, non-deleted REST Interfaces visible to the caller's Tenant. Results include all Interfaces on the caller's Instances, plus Interfaces on other Tenants' Instances when they explicitly select a VPC owned by the caller or a VPC Prefix under one.

`vpcId` filters by the directly selected VPC or the parent of an explicitly selected VPC Prefix. `crossTenant: true` returns only Interfaces whose Instance and selected VPC or VPC Prefix have different owning Tenants; `false` returns only matching ownership. `instanceTenantId` filters by the Tenant that owns the consuming Instance, and `vpcTenantId` filters by the Tenant that owns the selected VPC or VPC Prefix. Filters compose and may produce an empty result. A valid but inaccessible `vpcId`, `instanceTenantId`, or `vpcTenantId` returns an empty list rather than disclosing resource existence.

The caller must have an organization membership and an authorization role with `TENANT_ADMIN` suffix. No cross-Tenant creation capability is required to list visible Interfaces. A cross-Tenant result includes non-null `instanceTenantId` and `vpcTenantId`; both are null when the owners match. The response uses the complete Interface representation, including addresses and routing data. Visibility does not grant authority over another Tenant's Instance, VPC, VPC Prefix, or security policy.

Results are ordered by `created` ascending by default, with Interface `id` ascending as a stable tie-breaker. `orderBy` supports `status`, `created`, and `updated` in ascending or descending order; Interface `id` ascending remains the tie-breaker. An empty result is returned as `[]`.

Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/interface/get-all-interfaces

## Authentication

- `Authorization` header (bearer token, required) — ``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<org-name> # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ```

## Request

### Path parameters

- `org` (string, required) — Name of the Tenant organization

### Query parameters

- `vpcId` (string, optional) — Filter by the selected VPC or the parent VPC of an explicitly selected VPC Prefix
- `crossTenant` (boolean, optional) — Filter by whether the Instance and selected VPC or VPC Prefix have different owning Tenants
- `instanceTenantId` (string, optional) — Filter by the Tenant that owns the consuming Instance, within the caller's visibility boundary
- `vpcTenantId` (string, optional) — Filter by the Tenant that owns the selected VPC or VPC Prefix, within the caller's visibility boundary
- `status` (enum, optional) — Filter Interfaces by status
  - Allowed values: `Pending`, `Provisioning`, `Ready`, `Deleting`, `Error`
- `includeRelation` (enum, optional) — Related entity to expand; repeat the parameter to request multiple relations.
  - Allowed values: `Instance`, `Subnet`, `VpcPrefix`
- `pageNumber` (integer, optional) — Page number for pagination query
- `pageSize` (integer, optional, default: 20) — Page size for pagination query
- `orderBy` (enum, optional, default: CREATED_ASC) — Ordering for pagination query; defaults to `CREATED_ASC`
  - Allowed values: `STATUS_ASC`, `STATUS_DESC`, `CREATED_ASC`, `CREATED_DESC`, `UPDATED_ASC`, `UPDATED_DESC`

## Response

### 200

Interfaces visible to the current Tenant

- `list of Interface`

## Errors

### 400 Bad Request Error

Error response when request data cannot be validated

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 403 Forbidden Error

Error response when user is not authorized to call an endpoint or retrieve/modify objects

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 500 Internal Server Error

Response when the API handler encounters an unexpected error

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

## Types

### Interface

Associates an Instance with a Subnet or VPC-backed network

- `instanceTenantId` (string, required, nullable) — ID of the Tenant that owns the associated Instance when it differs from the selected VPC or VPC Prefix owner; null when the owners match
- `vpcTenantId` (string, required, nullable) — ID of the Tenant that owns the selected VPC or VPC Prefix when it differs from the Instance owner; null when the owners match
- `id` (string, optional) — Unique UUID v4 identifier for the Interface
- `instanceId` (string, optional) — ID of the associated Instance
- `subnetId` (string, optional, nullable) — ID of the associated Subnet
- `vpcPrefixId` (string, optional, nullable) — ID of the VPC Prefix explicitly selected by the caller
- `vpcId` (string, optional) — ID of the VPC from which the Controller selects a prefix
- `ipFamilies` (list of enum, optional) — Address families requested for Controller prefix selection
  - Allowed values: `IPv4`, `IPv6`
- `isPhysical` (boolean, optional) — Indicates whether the network is bound on a physical Interface
- `device` (string, optional, nullable) — Name of the device to use
- `deviceInstance` (integer, optional, nullable) — Index of the device, used to identify which interface card to attache the Partition to
- `virtualFunctionId` (integer, optional, nullable) — Must be specified if isPhysical is false
- `macAddress` (string, optional, nullable) — MAC address of the Interface
- `ipAddresses` (list of string, optional) — A list of IPv4 or IPv6 addresses
- `ipPrefixes` (list of string, optional) — Reported IPv4 or IPv6 prefixes in CIDR notation, ordered IPv4 before IPv6. This list is independent of `ipAddresses`; SLAAC can report an IPv6 prefix without a fixed host address. Match prefixes and addresses by address family, not list position. Empty when no prefixes are available.
- `requestedIpAddress` (string, optional, nullable) — Explicitly requested IP address for the interface. This is only used with an explicit `vpcPrefixId` and is not valid with `subnetId` or VPC-selected interfaces. The least-significant host bit must be 1.
- `inlineRoutingProfile` (InterfaceInlineRoutingProfile, optional, nullable) — Inline interface-local routing profile options. Only valid for VPC-backed interfaces.
- `status` (enum, optional) — Status of the Interface
  - Allowed values: `Pending`, `Provisioning`, `Ready`, `Deleting`, `Error`
- `created` (datetime, optional) — Date/time when the Interface was created
- `updated` (datetime, optional) — Date/time when the Interface was last updated

### NiCoApiErrorData

Additional data about the error

### InterfaceInlineRoutingProfile

Interface-local routing profile options that narrow the owning VPC's routing profile.

- `allowedAnycastPrefixes` (list of string, optional, default: []) — CIDR prefixes this interface is allowed to announce as anycast routes.

## Examples

**Response**

```json
[
  {
    "instanceTenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    "vpcTenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    "id": "07cd865e-5512-4fe9-8063-8f4c8f442b1a",
    "instanceId": "37804b21-0a00-4668-81cb-af9e1b07ad3e",
    "vpcPrefixId": null,
    "vpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isPhysical": true,
    "device": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
    "deviceInstance": 1,
    "virtualFunctionId": null,
    "macAddress": "02:00:00:00:00:01",
    "ipAddresses": [
      "192.0.2.10"
    ],
    "ipPrefixes": [
      "192.0.2.0/24"
    ],
    "status": "Ready",
    "created": "2019-08-24T14:15:22Z",
    "updated": "2019-08-24T14:15:22Z"
  },
  {
    "instanceTenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
    "vpcTenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    "id": "fa84f327-cad4-458b-94b7-c320cdf48d4d",
    "instanceId": "bba44e11-facc-4d7f-a2b5-ffdca3935b8b",
    "vpcPrefixId": "915443b6-d164-48d4-89dd-041968e1f9d7",
    "vpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "isPhysical": false,
    "device": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
    "deviceInstance": 0,
    "virtualFunctionId": 1,
    "status": "Provisioning",
    "created": "2019-08-24T14:16:22Z",
    "updated": "2019-08-24T14:17:22Z"
  }
]
```

**SDK Code**

```python direct-and-prefix
import requests

url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript direct-and-prefix
const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go direct-and-prefix
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby direct-and-prefix
require 'uri'
require 'net/http'

url = URI("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java direct-and-prefix
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php direct-and-prefix
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp direct-and-prefix
using RestSharp;

var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift direct-and-prefix
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/interface")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```