> This page is for Self-Hosted, version v3.0 (default).
> For other versions, use one of these documentation indexes:
> - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt
> - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt
> - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt
> - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt.

# List AI applications. [Experimental]

GET http://localhost:8080/api/v1/ai-applications

List AI applications.

Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/ai-applications/list-applications

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication

## Request

### Query parameters

- `verbosity` (enum, optional, default: brief) — response verbosity level.
  - Allowed values: `brief`, `full`
- `offset` (integer, optional) — The offset of the first item returned in the collection.
- `limit` (integer, optional, default: 50) — The maximum number of entries to return.
- `sortOrder` (enum, optional, default: asc) — Sort results in descending or ascending order.
  - Allowed values: `asc`, `desc`
- `sortBy` (enum, optional) — Sort results by a parameter.
  - Allowed values: `clusterId`, `name`, `projectId`, `projectName`, `departmentId`, `departmentName`, `source`, `type`, `createdAt`
- `filterBy` (list of string, optional) — Filter results by a parameter. Use the format field-name operator value. Operators are `==` Equals, `!=` Not equals, `<=` Less than or equal, `>=` Greater than or equal, `=@` contains, `!@` Does not contain, `=^` Starts with and `=$` Ends with. Dates are in ISO 8601 timestamp format and available for operators `==`, `!=`, `<=` and `>=`.
- `search` (string, optional) — Filter results by a free text search.

## Response

### 200

ok.

- `applications` (list of AIApplication, required)
- `next` (integer, optional)

## Errors

### 400 Bad Request Error

Bad request.

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 401 Unauthorized Error

Unauthorized

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 403 Forbidden Error

Forbidden

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 503 Service Unavailable Error

unexpected error

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

## Types

### AIApplication

- `id` (string, optional)
- `name` (string, optional) — The name of the application. The name must be unique within the organization and can only contain lowercase alphanumeric characters and hyphens. It must start with a letter.
- `source` (string, optional)
- `type` (string, optional)
- `desiredPhase` (string, optional, nullable) — The desired phase of the application.
- `phase` (string, optional) — The actual status of the release in the cluster.
- `projectId` (string, optional) — The id of the project.
- `projectName` (string, optional) — The name of the project
- `departmentId` (string, optional) — The id of the department.
- `departmentName` (string, optional) — The name of the department
- `resources` (list of AIApplicationResource, optional)
- `allocatedResources` (AIApplicationAllocatedResources, optional)
- `requestedResources` (AIApplicationRequestResources, optional)
- `createdAt` (datetime, optional)
- `createdBy` (string, optional) — The user who created the application.
- `updatedAt` (datetime, optional)
- `updatedBy` (string, optional) — The user who created the application.
- `updateCount` (long, optional) — The sync update counter for this application.
- `actionStatus` (string, optional, nullable) — The status of the recent action preformed on the application.
- `actionMessage` (string, optional, nullable) — The message of the recent action preformed on the application.
- `endpoints` (list of AiApplicationEndpoint, optional) — List of network endpoints through which the workloads associated with the AI application is exposed.
- `resourceConnections` (list of AiApplicationResourceConnection, optional) — Links between the application's workloads and the referenced resources (PersistentVolumeClaims, Secrets, ConfigMaps). Each entry connects one workload to one resource, so a resource shared by several workloads appears once per workload.
- `spec` (AIApplicationSpec, optional, nullable)

### AIApplicationResource

- `id` (string, optional)
- `name` (string, optional)
- `kind` (string, optional)

### AIApplicationAllocatedResources

- `gpu` (double, optional, nullable) — States the number of GPUs allocated for the created workloads.
- `gpuMemory` (string, optional, nullable)
- `cpu` (double, optional, nullable) — States the amount of CPU cores used by the workloads running.
- `cpuMemory` (string, optional, nullable)

### AIApplicationRequestResources

- `gpu` (RequestResourceCores, optional)
- `gpuMemory` (RequestResourceQuantity, optional)
- `cpu` (RequestResourceCores, optional)
- `cpuMemory` (RequestResourceQuantity, optional)

### AiApplicationEndpoint

- `host` (string, optional) — The hostname used to access the endpoint (for example, chat.example.com). This value is typically defined by the exposing Kubernetes resource (such as an Ingress).
- `port` (integer, optional) — The network port exposed by the endpoint. This is the port used when connecting to the workload.
- `path` (string, optional) — The URL path associated with the endpoint (for example, /v1/completions). Combined with host, it forms the full HTTP route to the workload.
- `tlsEnabled` (boolean, optional, nullable) — Indicates whether TLS is enabled for the endpoint. When true, the endpoint expects encrypted connections (typically HTTPS).
- `protocol` (string, optional) — The network protocol used for communication with the endpoint (for example, HTTP or HTTPS).
- `url` (string, optional) — The fully qualified URL through which the workload is accessible. This value represents the complete access address derived from the protocol, host, and path (for example, https://chat.example.com/v1/completions).
- `workloadId` (string, optional) — The id of the workload associated with this endpoint.

### AiApplicationResourceConnection

A reference to an existing Kubernetes resource (PersistentVolumeClaim, Secret, or ConfigMap) used by a workload's pod template.

- `name` (string, required) — The name of the referenced resource.
- `kind` (enum, required) — The Kubernetes resource type of the referenced object.
  - Allowed values: `PersistentVolumeClaim`, `Secret`, `ConfigMap`
- `uid` (string, optional) — The Kubernetes UID of the referenced resource.
- `workloadId` (string, optional) — A unique ID of the workload.

### AIApplicationSpec

- `chartRef` (AIApplicationSpecChartRef, required) — Specifies the origin of the Helm chart. Provide exactly one source: a connected Helm repository (`repo` + `chartName` + `chartVersion`), a direct chart URL (`chartURL`), or the identifier of a previously uploaded chart archive (`chartId`).
- `values` (map from string to any, optional) — Inline Helm values used to override the Helm chart’s default configuration. These values are merged with the Helm chart’s `values.yaml`. This field is mutually exclusive with `valuesBase64`. A complete string value can reference a personal credential using `USERCREDENTIAL:<name>`. Generic secret and Docker registry credentials use that form. NGC credentials require an explicit representation: `USERCREDENTIAL:<name>,generic-secret` or `USERCREDENTIAL:<name>,docker-registry`. Embedded or partial placeholders are not supported. The resolved value is a Kubernetes Secret name, never credential plaintext.
- `valuesBase64` (string, optional) — Base64-encoded Helm values used to override the Helm chart’s default configuration. This field is mutually exclusive with `values`. When the decoded content contains personal credential references, it must be a YAML object. String values support the same exact personal credential placeholder grammar as `values`: `USERCREDENTIAL:<name>` for generic secret and Docker registry credentials, or `USERCREDENTIAL:<name>,generic-secret` and `USERCREDENTIAL:<name>,docker-registry` for NGC credentials. Embedded or partial placeholders are not supported.
- `auth` (AIApplicationAuth, optional) — Authentication configuration required to access a private Helm repository or chart URL. This is used when the chart source requires credentials.

### RequestResourceCores

- `limit` (double, optional, nullable)
- `request` (double, optional, nullable)

### RequestResourceQuantity

- `limit` (string, optional, nullable)
- `request` (string, optional, nullable)

### AIApplicationSpecChartRef

Specifies the origin of the Helm chart. Provide exactly one source: a connected Helm repository (`repo` + `chartName` + `chartVersion`), a direct chart URL (`chartURL`), or the identifier of a previously uploaded chart archive (`chartId`).

- `repo` (string, optional) — The HTTP or HTTPS URL of the Helm repository that hosts the chart. This must match a repository that is accessible. Used together with `name` and `version`.
- `chartName` (string, optional) — The name of the chart within the specified repository. This corresponds to the chart’s directory name.
- `chartVersion` (string, optional) — The specific Semantic Version (SemVer) of the chart to deploy.
- `chartURL` (string, optional) — A direct HTTPS URL to a packaged Helm chart archive (.tgz). When provided, the chart is downloaded directly from this location instead of being resolved through a Helm repository reference.
- `chartId` (string, optional) — Identifier of a Helm chart archive that was previously uploaded via the chart upload endpoint. When provided, the control plane serves the uploaded chart to the cluster for installation instead of resolving a Helm repository reference or a direct chart URL.

### AIApplicationAuth

Authentication configuration required to access a private Helm repository or chart URL. This is used when the chart source requires credentials.

- `userCredential` (boolean, optional, nullable) — Indicates whether the asset is a user credential owned by the caller. When omitted or false, the asset is treated as a shared credential.
- `assetId` (string, optional) — The ID of the asset to use for authentication.

## Examples

**Response**

```json
{
  "applications": [
    {
      "id": "string",
      "name": "string",
      "source": "string",
      "type": "string",
      "desiredPhase": "string",
      "phase": "string",
      "projectId": "1",
      "projectName": "project-a",
      "departmentId": "2",
      "departmentName": "default",
      "resources": [
        {
          "id": "string",
          "name": "string",
          "kind": "string"
        }
      ],
      "allocatedResources": {
        "gpu": 1.5,
        "gpuMemory": "200Mi",
        "cpu": 0.5,
        "cpuMemory": "0B"
      },
      "requestedResources": {
        "gpu": {
          "limit": 1.5,
          "request": 1
        },
        "gpuMemory": {
          "limit": "2G",
          "request": "200M"
        },
        "cpu": {
          "limit": 1.5,
          "request": 1
        },
        "cpuMemory": {
          "limit": "2G",
          "request": "200M"
        }
      },
      "createdAt": "2024-01-15T09:30:00Z",
      "createdBy": "string",
      "updatedAt": "2024-01-15T09:30:00Z",
      "updatedBy": "string",
      "updateCount": 1,
      "actionStatus": "string",
      "actionMessage": "string",
      "endpoints": [
        {
          "host": "string",
          "port": 1,
          "path": "string",
          "tlsEnabled": true,
          "protocol": "string",
          "url": "string",
          "workloadId": "string"
        }
      ],
      "resourceConnections": [
        {
          "name": "my-data-pvc",
          "kind": "PersistentVolumeClaim",
          "uid": "string",
          "workloadId": "string"
        }
      ],
      "spec": {
        "chartRef": {
          "repo": "https://charts.bitnami.com/bitnami",
          "chartName": "redis",
          "chartVersion": "17.3.17",
          "chartURL": "https://helm.ngc.nvidia.com/nvidia/blueprint/charts/nvidia-blueprint-rag-v2.3.0.tgz",
          "chartId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        },
        "values": {},
        "valuesBase64": "string",
        "auth": {
          "userCredential": true,
          "assetId": "string"
        }
      }
    }
  ],
  "next": 1
}
```

**SDK Code**

```python
import requests

url = "http://localhost:8080/api/v1/ai-applications"

querystring = {"verbosity":"full"}

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

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

print(response.json())
```

```javascript
const url = 'http://localhost:8080/api/v1/ai-applications?verbosity=full';
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
package main

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

func main() {

	url := "http://localhost:8080/api/v1/ai-applications?verbosity=full"

	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
require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v1/ai-applications?verbosity=full")

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

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

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

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("http://localhost:8080/api/v1/ai-applications?verbosity=full")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'http://localhost:8080/api/v1/ai-applications?verbosity=full', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("http://localhost:8080/api/v1/ai-applications?verbosity=full");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "http://localhost:8080/api/v1/ai-applications?verbosity=full")! 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()
```