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:

import { createClient } from "@phala/cloud";

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

Set version when you need an older response shape:

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:

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.

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:

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
• Schema Reference
• KMS