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. The new client retains built-in actions and custom extensions, bound to the new version:

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

For custom extensions, the factory’s client is typed with the ApiVersion union. After withVersion(), custom methods remain callable with their original parameters, but their return types are unknown. Check or narrow those values before using them. This avoids assuming the old version’s response shape applies to the new version.

​

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.

The client’s version overrides any X-Phala-Version value in config.headers, regardless of header casing. An action can still explicitly pin its own request to a different version, as the KMS methods below do.

​

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