Skip to main content

​
getAppList

GET /apps Returns a paginated, filterable list of apps. Parameters:
FieldTypeRequiredDescription
pagenumberNoPage number
page_sizenumberNoItems per page (max 100)
searchstringNoSearch by name
statusstring[]NoFilter by status
listedbooleanNoFilter by public listing
base_imagestringNoFilter by OS image
instance_typestringNoFilter by instance type
kms_slugstringNoFilter by KMS slug
kms_typestringNoFilter by KMS type
nodestringNoFilter by node
regionstringNoFilter by region
Returns: Paginated list of apps (version-aware schema). Example: 
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:
FieldTypeRequiredDescription
app_idstringYesApp identifier
Returns: AppInfo — version-aware app details.

​
getAppCvms

GET /apps/{app_id}/cvms Returns the list of CVMs associated with an app. Parameters:
FieldTypeRequiredDescription
app_idstringYesApp identifier
Returns: Array of CVM objects.

​
getAppRevisions

GET /apps/{app_id}/revisions Returns the revision history for an app. Parameters:
FieldTypeRequiredDescription
app_idstringYesApp identifier
Returns: Array of app revisions.

​
getAppRevisionDetail

GET /apps/{app_id}/revisions/{revision_id} Returns details about a specific app revision. Parameters:
FieldTypeRequiredDescription
app_idstringYesApp identifier
revision_idstringYesRevision 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: 
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:
FieldTypeRequiredDescription
appIdstringYesApp identifier (hex)
Returns: AppAttestationResponse
FieldTypeDescription
app_idstringApp identifier
contract_addressstringApp contract address
kms_infoobjectKMS details (contract address, chain, URL)
instancesarrayPer-instance attestation (vm_uuid, tcb_info, app_certificates, compose_file)
kms_guest_agent_infoobject?KMS guest agent info
gateway_guest_agent_infoobject?Gateway guest agent info
qemu_versionstring?QEMU version
Example: 
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:
FieldTypeRequiredDescription
appIdstringYesApp identifier (hex)
Returns: DeviceAllowlistResponse
FieldTypeDescription
is_onchain_kmsbooleanWhether the app uses on-chain KMS
allow_any_deviceboolean?On-chain allowAnyDevice flag
chain_idnumber?Blockchain chain ID
app_contract_addressstring?App contract address
devicesarrayDevice entries with device_id, node_name, cvm_ids, allowed_onchain, status
Example: 
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:
FieldTypeRequiredDescription
appIdstringYesApp contract address
compose_hashstringYesCompose hash to check
node_idnumberNoNode ID (resolves device ID from DB)
device_idstringNoDevice ID (hex, direct)
chain_idnumberNoChain ID for RPC URL resolution
Returns: IsAllowedResult
FieldTypeDescription
app_contract_addressstringContract address
compose_hashstringChecked compose hash
device_idstringDevice ID checked
compose_hash_allowedbooleanWhether compose hash is registered
allow_any_devicebooleanWhether any device is allowed
device_id_allowedboolean?Whether specific device is registered
is_allowedbooleanOverall allowance result
errorstring?Error message if check failed
Example: 
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:
FieldTypeRequiredDescription
appIdstringYesApp identifier (hex)
Returns: AppCvmsBatchIsAllowedResponse
FieldTypeDescription
is_onchainbooleanWhether the app uses on-chain KMS
resultsarrayPer-CVM allowance results (each with cvm_id, is_allowed, compose_hash_allowed, etc.)
totalnumberTotal CVMs checked
allowed_countnumberNumber of allowed CVMs
denied_countnumberNumber of denied CVMs
error_countnumberNumber of errored checks
skipped_cvm_idsnumber[]CVM IDs that were skipped
Example: 
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}`);
});