# Network Topologies

The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are "closer" to each other, minimizing communication overhead and optimizing workload performance.

## Get network topologies.

> Retrieve a list of network topologies with details.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Network Topologies","description":"The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are \"closer\" to each other, minimizing communication overhead and optimizing workload performance."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologiesFilterBy":{"name":"filterBy","in":"query","required":false,"description":"Filter results by a parameter. Use the format field-name operator value. Supported operators:  == Equals  != Not equals  <= Less than or equal  >= Greater than or equal  =@ Contains !@ Does not contain  =^ Starts with  =$ Ends with Date values must be in ISO 8601 timestamp format. Only the following operators support dates: ==, !=, <=, >=.","schema":{"type":"array","items":{"type":"string","pattern":"^(name|clusterId|source|phase)(==|!=|<=|>=|=@|!@|=\\^|=\\$).+$"}},"explode":false}},"schemas":{"NetworkTopology":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"},{"type":"object","required":["id","tenantId","createdAt","status"],"properties":{"id":{"$ref":"#/components/schemas/NetworkTopologyId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the network topology was created"},"createdBy":{"type":"string","description":"Identifier of the user who created the network topology"},"phase":{"type":"string","description":"Phase of the network topology in the cluster. Enum: Creating, Ready"},"source":{"$ref":"#/components/schemas/NetworkTopologiesSource"},"nodePools":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true,"description":"List of node-pools associated with this network topology"}}}]},"NetworkTopologyCreateRequest":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyUpdateFields"},{"type":"object","required":["name","clusterId"],"properties":{"name":{"$ref":"#/components/schemas/NetworkTopologyName"},"clusterId":{"$ref":"#/components/schemas/ClusterId"}}}]},"NetworkTopologyUpdateFields":{"type":"object","required":["levels"],"properties":{"levels":{"$ref":"#/components/schemas/NetworkTopologyLevels"}}},"NetworkTopologyLevels":{"type":"array","items":{"type":"string","pattern":"^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\\/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$","minLength":1,"maxLength":63},"description":"Ordered array of network topology levels"},"NetworkTopologyName":{"type":"string","description":"Name of the network topology","maxLength":63,"minLength":1,"pattern":"^[a-z]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"NetworkTopologyId":{"type":"string","format":"uuid","description":"The unique identifier for the network topology"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"NetworkTopologiesSource":{"type":"string","description":"Identifier of the the source of the topology. Useful for tracking where the topology data originated (i.e. Run:ai, Cluster).","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies":{"get":{"summary":"Get network topologies.","description":"Retrieve a list of network topologies with details.","operationId":"get_network_topologies","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologiesFilterBy"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"networkTopologies":{"type":"array","items":{"$ref":"#/components/schemas/NetworkTopology"}}}}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Create network topologies

> Creates a network topology object based on the provided specification.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Network Topologies","description":"The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are \"closer\" to each other, minimizing communication overhead and optimizing workload performance."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"NetworkTopologyCreateRequest":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyUpdateFields"},{"type":"object","required":["name","clusterId"],"properties":{"name":{"$ref":"#/components/schemas/NetworkTopologyName"},"clusterId":{"$ref":"#/components/schemas/ClusterId"}}}]},"NetworkTopologyUpdateFields":{"type":"object","required":["levels"],"properties":{"levels":{"$ref":"#/components/schemas/NetworkTopologyLevels"}}},"NetworkTopologyLevels":{"type":"array","items":{"type":"string","pattern":"^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\\/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$","minLength":1,"maxLength":63},"description":"Ordered array of network topology levels"},"NetworkTopologyName":{"type":"string","description":"Name of the network topology","maxLength":63,"minLength":1,"pattern":"^[a-z]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"NetworkTopology":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"},{"type":"object","required":["id","tenantId","createdAt","status"],"properties":{"id":{"$ref":"#/components/schemas/NetworkTopologyId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the network topology was created"},"createdBy":{"type":"string","description":"Identifier of the user who created the network topology"},"phase":{"type":"string","description":"Phase of the network topology in the cluster. Enum: Creating, Ready"},"source":{"$ref":"#/components/schemas/NetworkTopologiesSource"},"nodePools":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true,"description":"List of node-pools associated with this network topology"}}}]},"NetworkTopologyId":{"type":"string","format":"uuid","description":"The unique identifier for the network topology"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"NetworkTopologiesSource":{"type":"string","description":"Identifier of the the source of the topology. Useful for tracking where the topology data originated (i.e. Run:ai, Cluster).","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies":{"post":{"summary":"Create network topologies","description":"Creates a network topology object based on the provided specification.","operationId":"create_network_topology","tags":["Network Topologies"],"requestBody":{"description":"The network topology to create.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkTopology"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Count the amount of network topologies in a tenant.

> Retrieve the count of network topologies in a tenant group by selected attributes

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Network Topologies","description":"The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are \"closer\" to each other, minimizing communication overhead and optimizing workload performance."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologiesFilterBy":{"name":"filterBy","in":"query","required":false,"description":"Filter results by a parameter. Use the format field-name operator value. Supported operators:  == Equals  != Not equals  <= Less than or equal  >= Greater than or equal  =@ Contains !@ Does not contain  =^ Starts with  =$ Ends with Date values must be in ISO 8601 timestamp format. Only the following operators support dates: ==, !=, <=, >=.","schema":{"type":"array","items":{"type":"string","pattern":"^(name|clusterId|source|phase)(==|!=|<=|>=|=@|!@|=\\^|=\\$).+$"}},"explode":false}},"schemas":{"CountResponse":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","format":"int64"}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies/count":{"get":{"summary":"Count the amount of network topologies in a tenant.","description":"Retrieve the count of network topologies in a tenant group by selected attributes","operationId":"get_network_topologies_count","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologiesFilterBy"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountResponse"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Get network topology by id.

> Retrieve network topology details by Universally Unique Identifier (UUID).

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Network Topologies","description":"The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are \"closer\" to each other, minimizing communication overhead and optimizing workload performance."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologyId":{"name":"networkTopologyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier for the network topology"}},"schemas":{"NetworkTopology":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"},{"type":"object","required":["id","tenantId","createdAt","status"],"properties":{"id":{"$ref":"#/components/schemas/NetworkTopologyId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the network topology was created"},"createdBy":{"type":"string","description":"Identifier of the user who created the network topology"},"phase":{"type":"string","description":"Phase of the network topology in the cluster. Enum: Creating, Ready"},"source":{"$ref":"#/components/schemas/NetworkTopologiesSource"},"nodePools":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true,"description":"List of node-pools associated with this network topology"}}}]},"NetworkTopologyCreateRequest":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyUpdateFields"},{"type":"object","required":["name","clusterId"],"properties":{"name":{"$ref":"#/components/schemas/NetworkTopologyName"},"clusterId":{"$ref":"#/components/schemas/ClusterId"}}}]},"NetworkTopologyUpdateFields":{"type":"object","required":["levels"],"properties":{"levels":{"$ref":"#/components/schemas/NetworkTopologyLevels"}}},"NetworkTopologyLevels":{"type":"array","items":{"type":"string","pattern":"^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\\/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$","minLength":1,"maxLength":63},"description":"Ordered array of network topology levels"},"NetworkTopologyName":{"type":"string","description":"Name of the network topology","maxLength":63,"minLength":1,"pattern":"^[a-z]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"NetworkTopologyId":{"type":"string","format":"uuid","description":"The unique identifier for the network topology"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"NetworkTopologiesSource":{"type":"string","description":"Identifier of the the source of the topology. Useful for tracking where the topology data originated (i.e. Run:ai, Cluster).","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies/{networkTopologyId}":{"get":{"summary":"Get network topology by id.","description":"Retrieve network topology details by Universally Unique Identifier (UUID).","operationId":"get_network_topology_by_id","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologyId"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkTopology"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Delete network topology by ID.

> Delete an existing network topology by its ID.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.24"},"tags":[{"name":"Network Topologies","description":"The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are \"closer\" to each other, minimizing communication overhead and optimizing workload performance."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologyId":{"name":"networkTopologyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier for the network topology"}},"responses":{"204NoContent":{"description":"No Content."},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/network-topologies/{networkTopologyId}":{"delete":{"summary":"Delete network topology by ID.","description":"Delete an existing network topology by its ID.","operationId":"delete_network_topology","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologyId"}],"responses":{"204":{"$ref":"#/components/responses/204NoContent"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```