> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apps

> Functions for querying app information, CVMs, and revision history

## getAppList

`GET /apps`

Returns a paginated, filterable list of apps.

**Parameters:**

| Field           | Type       | Required | Description              |
| --------------- | ---------- | -------- | ------------------------ |
| `page`          | `number`   | No       | Page number              |
| `page_size`     | `number`   | No       | Items per page (max 100) |
| `search`        | `string`   | No       | Search by name           |
| `status`        | `string[]` | No       | Filter by status         |
| `listed`        | `boolean`  | No       | Filter by public listing |
| `base_image`    | `string`   | No       | Filter by OS image       |
| `instance_type` | `string`   | No       | Filter by instance type  |
| `kms_slug`      | `string`   | No       | Filter by KMS slug       |
| `kms_type`      | `string`   | No       | Filter by KMS type       |
| `node`          | `string`   | No       | Filter by node           |
| `region`        | `string`   | No       | Filter by region         |

**Returns:** Paginated list of apps (version-aware schema).

**Example:**

```typescript theme={"system"}
const apps = await client.getAppList({
  page: 1,
  page_size: 20,
  status: ["running"],
});
```

***

## getAppInfo

`GET /apps/{app_id}`

Returns detailed information about a specific app.

**Parameters:**

| Field    | Type     | Required | Description    |
| -------- | -------- | -------- | -------------- |
| `app_id` | `string` | Yes      | App identifier |

**Returns:** `AppInfo` — version-aware app details.

***

## getAppCvms

`GET /apps/{app_id}/cvms`

Returns the list of CVMs associated with an app.

**Parameters:**

| Field    | Type     | Required | Description    |
| -------- | -------- | -------- | -------------- |
| `app_id` | `string` | Yes      | App identifier |

**Returns:** Array of CVM objects.

***

## getAppRevisions

`GET /apps/{app_id}/revisions`

Returns the revision history for an app.

**Parameters:**

| Field    | Type     | Required | Description    |
| -------- | -------- | -------- | -------------- |
| `app_id` | `string` | Yes      | App identifier |

**Returns:** Array of app revisions.

***

## getAppRevisionDetail

`GET /apps/{app_id}/revisions/{revision_id}`

Returns details about a specific app revision.

**Parameters:**

| Field         | Type     | Required | Description         |
| ------------- | -------- | -------- | ------------------- |
| `app_id`      | `string` | Yes      | App identifier      |
| `revision_id` | `string` | Yes      | Revision identifier |

**Returns:** `AppRevisionDetail` — revision details including compose file and configuration.

***

## getAppFilterOptions

`GET /apps/filter-options`

Returns the available filter values for app list queries.

**Parameters:** None

**Returns:** `AppFilterOptions` — available values for status, base\_image, instance\_type, kms\_slug, etc.

**Example:**

```typescript theme={"system"}
const filters = await client.getAppFilterOptions();
console.log("Available statuses:", filters.statuses);
console.log("Available regions:", filters.regions);
```

***

## getAppAttestation

`GET /apps/{appId}/attestations`

Returns TEE attestation details for all CVM instances under an app. This includes per-instance certificates, TCB measurements, and KMS metadata, giving you a single view of the app's attestation posture.

**Parameters:**

| Field   | Type     | Required | Description          |
| ------- | -------- | -------- | -------------------- |
| `appId` | `string` | Yes      | App identifier (hex) |

**Returns:** `AppAttestationResponse`

| Field                      | Type      | Description                                                                      |
| -------------------------- | --------- | -------------------------------------------------------------------------------- |
| `app_id`                   | `string`  | App identifier                                                                   |
| `contract_address`         | `string`  | App contract address                                                             |
| `kms_info`                 | `object`  | KMS details (contract address, chain, URL)                                       |
| `instances`                | `array`   | Per-instance attestation (vm\_uuid, tcb\_info, app\_certificates, compose\_file) |
| `kms_guest_agent_info`     | `object?` | KMS guest agent info                                                             |
| `gateway_guest_agent_info` | `object?` | Gateway guest agent info                                                         |
| `qemu_version`             | `string?` | QEMU version                                                                     |

**Example:**

```typescript theme={"system"}
const att = await client.getAppAttestation({ appId: "0x1234abcd" });
att.instances.forEach(inst => {
  console.log(inst.name, inst.status, inst.tcb_info?.app_compose);
});
```

***

## getAppDeviceAllowlist

`GET /apps/{appId}/device-allowlist`

Returns the device allowlist status for all CVMs under an app. For on-chain KMS apps, this queries the blockchain in real-time to check which devices are registered in the app contract. For offchain KMS apps, returns basic info with `is_onchain_kms: false`.

**Parameters:**

| Field   | Type     | Required | Description          |
| ------- | -------- | -------- | -------------------- |
| `appId` | `string` | Yes      | App identifier (hex) |

**Returns:** `DeviceAllowlistResponse`

| Field                  | Type       | Description                                                                          |
| ---------------------- | ---------- | ------------------------------------------------------------------------------------ |
| `is_onchain_kms`       | `boolean`  | Whether the app uses on-chain KMS                                                    |
| `allow_any_device`     | `boolean?` | On-chain `allowAnyDevice` flag                                                       |
| `chain_id`             | `number?`  | Blockchain chain ID                                                                  |
| `app_contract_address` | `string?`  | App contract address                                                                 |
| `devices`              | `array`    | Device entries with `device_id`, `node_name`, `cvm_ids`, `allowed_onchain`, `status` |

**Example:**

```typescript theme={"system"}
const allowlist = await client.getAppDeviceAllowlist({ appId: "0x1234abcd" });
if (allowlist.is_onchain_kms) {
  allowlist.devices.forEach(d => {
    console.log(d.device_id, d.status, d.allowed_onchain);
  });
}
```

***

## checkAppIsAllowed

`POST /apps/{appId}/is-allowed`

Checks whether a deployment is allowed by an on-chain dstack App contract. This queries the blockchain to verify that the compose hash and device are registered. You can use this for pre-flight checks before deploying or updating a CVM.

**Parameters:**

| Field          | Type     | Required | Description                          |
| -------------- | -------- | -------- | ------------------------------------ |
| `appId`        | `string` | Yes      | App contract address                 |
| `compose_hash` | `string` | Yes      | Compose hash to check                |
| `node_id`      | `number` | No       | Node ID (resolves device ID from DB) |
| `device_id`    | `string` | No       | Device ID (hex, direct)              |
| `chain_id`     | `number` | No       | Chain ID for RPC URL resolution      |

**Returns:** `IsAllowedResult`

| Field                  | Type       | Description                           |
| ---------------------- | ---------- | ------------------------------------- |
| `app_contract_address` | `string`   | Contract address                      |
| `compose_hash`         | `string`   | Checked compose hash                  |
| `device_id`            | `string`   | Device ID checked                     |
| `compose_hash_allowed` | `boolean`  | Whether compose hash is registered    |
| `allow_any_device`     | `boolean`  | Whether any device is allowed         |
| `device_id_allowed`    | `boolean?` | Whether specific device is registered |
| `is_allowed`           | `boolean`  | Overall allowance result              |
| `error`                | `string?`  | Error message if check failed         |

**Example:**

```typescript theme={"system"}
const result = await client.checkAppIsAllowed({
  appId: "0x1234abcd",
  compose_hash: "0xaabb...",
  device_id: "0xccdd...",
});
console.log(`Allowed: ${result.is_allowed}`);
```

***

## checkAppCvmsIsAllowed

`POST /apps/{appId}/cvms/is-allowed`

Batch-checks on-chain deployment allowance for all CVMs under an app. For on-chain KMS apps, this queries the blockchain via multicall to check compose hash and device allowance for each CVM in a single operation. For offchain KMS apps, returns `is_onchain: false` with no results.

**Parameters:**

| Field   | Type     | Required | Description          |
| ------- | -------- | -------- | -------------------- |
| `appId` | `string` | Yes      | App identifier (hex) |

**Returns:** `AppCvmsBatchIsAllowedResponse`

| Field             | Type       | Description                                                                                |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------ |
| `is_onchain`      | `boolean`  | Whether the app uses on-chain KMS                                                          |
| `results`         | `array`    | Per-CVM allowance results (each with `cvm_id`, `is_allowed`, `compose_hash_allowed`, etc.) |
| `total`           | `number`   | Total CVMs checked                                                                         |
| `allowed_count`   | `number`   | Number of allowed CVMs                                                                     |
| `denied_count`    | `number`   | Number of denied CVMs                                                                      |
| `error_count`     | `number`   | Number of errored checks                                                                   |
| `skipped_cvm_ids` | `number[]` | CVM IDs that were skipped                                                                  |

**Example:**

```typescript theme={"system"}
const batch = await client.checkAppCvmsIsAllowed({ appId: "0x1234abcd" });
console.log(`${batch.allowed_count}/${batch.total} CVMs allowed`);
batch.results.forEach(r => {
  console.log(`CVM ${r.cvm_id}: allowed=${r.is_allowed}`);
});
```