> ## 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.

# API Versioning

> Supported Phala Cloud API versions, the current default, and version-specific TypeScript response types.

`@phala/cloud` v0.4.0 uses API version `2026-06-23` by default. The SDK sends the selected version in the `X-Phala-Version` header and returns matching TypeScript types.

## Supported versions

| Version      | Status      | Response behavior                                                            |
| ------------ | ----------- | ---------------------------------------------------------------------------- |
| `2026-06-23` | **Default** | Uses the latest CVM and app schemas and enables the contract-centric KMS API |
| `2026-05-22` | Supported   | Uses hashed CVM IDs and the current CVM and app schemas                      |
| `2026-01-21` | Supported   | Uses the earlier workspace-aware CVM and app schemas                         |
| `2025-10-28` | Legacy      | Uses the legacy flat response schemas                                        |

## Select a version

Omit `version` to use `2026-06-23`:

```typescript theme={"system"}
import { createClient } from "@phala/cloud";

const client = createClient({ apiKey: "phak_your_api_key" });
```

Set `version` when you need an older response shape:

```typescript theme={"system"}
const client = createClient({
  apiKey: "phak_your_api_key",
  version: "2026-05-22",
});
```

Use `.withVersion()` to create another client with the same authentication and a different API version:

```typescript theme={"system"}
const currentClient = createClient({ apiKey: "phak_your_api_key" });
const legacyClient = currentClient.withVersion("2025-10-28");
```

## Version-aware return types

The client version controls the return type for versioned actions such as `getCvmList`, `getCvmInfo`, `getAppList`, and lifecycle operations.

```typescript theme={"system"}
const currentClient = createClient({
  apiKey: "phak_your_api_key",
  version: "2026-06-23",
});
const currentCvm = await currentClient.getCvmInfo({ id: "my-cvm" });
// CvmInfoDetailV20260522

const olderClient = currentClient.withVersion("2026-01-21");
const olderCvm = await olderClient.getCvmInfo({ id: "my-cvm" });
// CvmInfoDetailV20260121
```

Versions `2026-05-22` and `2026-06-23` share the same CVM and app response types. Version `2026-06-23` changes the KMS resource model from individual KMS nodes to KMS contracts.

## Contract-centric KMS methods

The following methods always request API version `2026-06-23`, even when the client uses an older version:

* `listKmsContracts()`
* `getKmsContract({ slug })`
* `listKmsContractNodes({ slug })`

The deprecated `getKmsList()` and `getKmsInfo()` methods remain pinned to `2026-05-22` so existing code continues to receive the legacy node-centric response shape.

## Standalone actions

Version-aware typing also works with a base client and standalone actions:

```typescript theme={"system"}
import { createBaseClient, getCvmInfo } from "@phala/cloud";

const client = createBaseClient({
  apiKey: "phak_your_api_key",
  version: "2026-06-23",
});
const cvm = await getCvmInfo(client, { id: "my-cvm" });
```

## Related

* [SDK Overview](/phala-cloud/references/cloud-js-sdk/overview)
* [Schema Reference](/phala-cloud/references/cloud-js-sdk/schema-reference)
* [KMS](/phala-cloud/references/cloud-js-sdk/kms)