API Reference

Node & Blocklet Management

This section provides detailed documentation for queries used to fetch information about the Blocklet Server itself and manage the lifecycle, configuration, and status of blocklets. These queries allow you to monitor server health, retrieve blocklet metadata, check runtime status, and access security settings.
For actions that modify state, such as installing or starting blocklets, please refer to the Node & Blocklet Management Mutations section.
Node Information#Queries for retrieving status and environmental details of the Blocklet Server.
getNodeInfo#Retrieves detailed information and status about the connected Blocklet Server.
Parameters
This method does not take any parameters.
Returns
Returns a Promise that resolves to a ResponseGetNodeInfo object containing the server's state.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getNodeInfo();
  console.log('Node Info:', response.info);
} catch (error) {
  console.error('Error fetching node info:', error);
}Example Response
{
  "code": "ok",
  "info": {
    "did": "z1...",
    "pk": "...",
    "version": "1.7.0",
    "name": "My Blocklet Server",
    "description": "My personal server for running blocklets.",
    "status": 0,
    "initialized": true
  }
}getNodeEnv#Retrieves environment details of the Blocklet Server, such as IP addresses, OS, location, and installed blocklet engines.
Parameters
This method does not take any parameters.
Returns
Returns a Promise that resolves to a ResponseGetNodeEnv object.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getNodeEnv();
  console.log('Node Environment:', response.info);
} catch (error) {
  console.error('Error fetching node environment:', error);
}Example Response
{
  "code": "ok",
  "info": {
    "ip": {
      "externalV4": "123.45.67.89"
    },
    "os": "linux",
    "location": "Unknown",
    "docker": true,
    "blockletEngines": [
      {
        "name": "node",
        "version": "18.17.0",
        "available": true
      }
    ]
  }
}checkNodeVersion#Checks for available updates for the Blocklet Server and returns the latest version if an update is available.
Parameters
This method does not take any parameters.
Returns
Returns a Promise that resolves to a ResponseCheckNodeVersion object.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.checkNodeVersion();
  if (response.version) {
    console.log('New version available:', response.version);
  } else {
    console.log('Server is up to date.');
  }
} catch (error) {
  console.error('Error checking server version:', error);
}Example Response
{
  "code": "ok",
  "version": "1.7.1"
}getNodeRuntimeHistory#Retrieves the runtime history (CPU and memory usage) for the Blocklet Server over a specified number of hours.
Parameters
Name
Type
Description
input.hours
number
The number of past hours to retrieve history for.
Returns
Returns a Promise that resolves to a ResponseNodeRuntimeHistory object.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getNodeRuntimeHistory({ input: { hours: 24 } });
  console.log('Node runtime history for the last 24 hours:', response.history);
} catch (error) {
  console.error('Error fetching node runtime history:', error);
}Example Response
{
  "code": "ok",
  "history": [
    {
      "date": 1672531200000,
      "cpu": 5.2,
      "mem": 2048
    }
  ]
}resetNodeStatus#Resets the status of the Blocklet Server. This is typically used to clear an error state after resolving an issue.
Parameters
This method does not take any parameters.
Returns
Returns a Promise that resolves to a ResponseGetNodeInfo object with the updated server state.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.resetNodeStatus();
  console.log('Node status reset successfully:', response.info.status);
} catch (error) {
  console.error('Error resetting node status:', error);
}getDelegationState#Checks if the node has a delegation state, which is relevant for certain DID-related operations.
Parameters
This method does not take any parameters.
Returns
Returns a Promise that resolves to a ResponseDelegationState object.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getDelegationState();
  console.log('Is delegated:', response.state.delegated);
} catch (error) {
  console.error('Error fetching delegation state:', error);
}Example Response
{
  "code": "ok",
  "state": {
    "delegated": false
  }
}Blocklet Information & Lifecycle#Queries for retrieving metadata, status, and history of installed blocklets.
getBlocklets#Retrieves a list of all installed blocklets and their current state.
Parameters
Name
Type
Description
input.useCache
boolean
Whether to use cached data. Defaults to false.
input.includeRuntimeInfo
boolean
Whether to include runtime information like CPU and memory usage. Defaults to true.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlocklets({ input: { includeRuntimeInfo: true } });
  response.blocklets.forEach((blocklet) => {
    console.log(`- ${blocklet.meta.title}: ${blocklet.status}`);
  });
} catch (error) {
  console.error('Error fetching blocklets:', error);
}getBlocklet#Retrieves the detailed state of a specific blocklet by its DID.
Parameters
Name
Type
Description
input.did
string
The DID of the blocklet to retrieve.
input.attachRuntimeInfo
boolean
Optional. Include live runtime metrics.
input.attachDiskInfo
boolean
Optional. Include disk usage details.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const blockletDid = 'z8...';
const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlocklet({ input: { did: blockletDid, attachRuntimeInfo: true } });
  console.log('Blocklet state:', response.blocklet);
} catch (error) {
  console.error(`Error fetching blocklet ${blockletDid}:`, error);
}getBlockletMeta#Retrieves the metadata for a specific blocklet version from its blocklet registry (store).
Parameters
Name
Type
Description
input.did
string
The DID of the blocklet.
input.storeUrl
string
The URL of the blocklet store.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletMeta({
    input: {
      did: 'z8tZ...',
      storeUrl: 'https://store.arcblock.io',
    },
  });
  console.log('Blocklet metadata:', response.meta);
} catch (error) {
  console.error('Error fetching blocklet meta:', error);
}getBlockletMetaFromUrl#Retrieves blocklet metadata directly from a URL pointing to a blocklet.yml or a registry URL.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletMetaFromUrl({
    input: { url: 'https://store.arcblock.io/api/blocklets/z8tZ...' },
  });
  console.log('Blocklet metadata from URL:', response.meta);
} catch (error) {
  console.error('Error fetching meta from URL:', error);
}getBlockletBaseInfo#Retrieves basic information for a blocklet, including user counts, passport stats, and backup status.
Parameters
Name
Type
Description
input.teamDid
string
The DID of the blocklet.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletBaseInfo({ input: { teamDid: 'z8tZ...' } });
  console.log('Blocklet base info:', response);
} catch (error) {
  console.error('Error fetching base info:', error);
}getBlockletDiff#Compares a set of local file hashes with the blocklet's files on the server to determine what has changed. This is useful for incremental updates.
Parameters
Name
Type
Description
input.did
string
The DID of the blocklet.
input.hashFiles
HashFileInput[]
An array of objects, each with a file path and a hash.
input.rootDid
string
Optional. The DID of the root blocklet if checking a component.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletDiff({
    input: {
      did: 'z8tZ...',
      hashFiles: [{ file: 'index.js', hash: '...' }],
    },
  });
  console.log('Changes:', response.blockletDiff);
} catch (error) {
  console.error('Error getting blocklet diff:', error);
}getBlockletRuntimeHistory#Retrieves the runtime history (CPU and memory usage) for a specific blocklet.
Parameters
Name
Type
Description
input.did
string
The DID of the blocklet.
input.hours
number
The number of past hours to retrieve history for.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletRuntimeHistory({
    input: { did: 'z8tZ...', hours: 24 },
  });
  console.log('Blocklet runtime history:', response.historyList);
} catch (error) {
  console.error('Error fetching runtime history:', error);
}getDynamicComponents#Retrieves metadata for dynamic components available at a given URL.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getDynamicComponents({ input: { url: 'https://store.arcblock.io' } });
  console.log('Dynamic components:', response.components);
} catch (error) {
  console.error('Error fetching dynamic components:', error);
}getBlockletsFromBackup#Lists available blocklets that can be restored from a backup source.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletsFromBackup();
  console.log('Available backups:', response.backups);
} catch (error) {
  console.error('Error fetching backups:', error);
}getLauncherSession#Retrieves session details from a launcher, typically used during the blocklet installation process.
Parameters
Name
Type
Description
input.launcherSessionId
string
The session ID provided by the launcher.
input.launcherUrl
string
The URL of the launcher service.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getLauncherSession({
    input: {
      launcherSessionId: '...',
      launcherUrl: 'https://launcher.arcblock.io',
    },
  });
  console.log('Launcher session:', response.launcherSession);
} catch (error) {
  console.error('Error fetching launcher session:', error);
}Blocklet Configuration & Security#Queries for retrieving a blocklet's configuration and security policies.
getBlockletSpaceGateways#Retrieves the configured DID Space gateways for a specific blocklet.
Parameters
Name
Type
Description
input.did
string
The DID of the blocklet.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletSpaceGateways({ input: { did: 'z8tZ...' } });
  console.log('Space Gateways:', response.spaceGateways);
} catch (error) {
  console.error('Error fetching space gateways:', error);
}getBlockletSecurityRules#Retrieves all security rules for a given blocklet.
Parameters
Name
Type
Description
input.did
string
The DID of the blocklet.
input.paging
PagingInput
Optional. Pagination options.
input.query
BlockletSecurityRuleQueryInput
Optional. Search query for filtering rules.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletSecurityRules({ input: { did: 'z8tZ...' } });
  console.log('Security Rules:', response.securityRules);
} catch (error) {
  console.error('Error fetching security rules:', error);
}getBlockletSecurityRule#Retrieves a single security rule by its ID for a given blocklet.
Parameters
Name
Type
Description
input.did
string
The DID of the blocklet.
input.id
string
The ID of the security rule.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletSecurityRule({ input: { did: 'z8tZ...', id: 'rule-id-123' } });
  console.log('Security Rule:', response.securityRule);
} catch (error) {
  console.error('Error fetching security rule:', error);
}getBlockletAccessPolicies#Retrieves all access policies for a given blocklet.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletAccessPolicies({ input: { did: 'z8tZ...' } });
  console.log('Access Policies:', response.accessPolicies);
} catch (error) {
  console.error('Error fetching access policies:', error);
}getBlockletAccessPolicy#Retrieves a single access policy by its ID for a given blocklet.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletAccessPolicy({ input: { did: 'z8tZ...', id: 'policy-id-123' } });
  console.log('Access Policy:', response.accessPolicy);
} catch (error) {
  console.error('Error fetching access policy:', error);
}getBlockletResponseHeaderPolicies#Retrieves all response header policies for a given blocklet.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletResponseHeaderPolicies({ input: { did: 'z8tZ...' } });
  console.log('Response Header Policies:', response.responseHeaderPolicies);
} catch (error) {
  console.error('Error fetching response header policies:', error);
}getBlockletResponseHeaderPolicy#Retrieves a single response header policy by its ID for a given blocklet.
SDK Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient('https://your-server.did.abtnet.io/api');
try {
  const response = await client.getBlockletResponseHeaderPolicy({ input: { did: 'z8tZ...', id: 'header-policy-123' } });
  console.log('Response Header Policy:', response.accessPolicy);
} catch (error) {
  console.error('Error fetching response header policy:', error);
}
Next, explore queries for managing users and controlling access in the User & Access Management section.

Name	Type	Description
`input.hours`	`number`	The number of past hours to retrieve history for.

Name	Type	Description
`input.useCache`	`boolean`	Whether to use cached data. Defaults to `false`.
`input.includeRuntimeInfo`	`boolean`	Whether to include runtime information like CPU and memory usage. Defaults to `true`.

Name	Type	Description
`input.did`	`string`	The DID of the blocklet to retrieve.
`input.attachRuntimeInfo`	`boolean`	Optional. Include live runtime metrics.
`input.attachDiskInfo`	`boolean`	Optional. Include disk usage details.

Name	Type	Description
`input.did`	`string`	The DID of the blocklet.
`input.storeUrl`	`string`	The URL of the blocklet store.

Name	Type	Description
`input.teamDid`	`string`	The DID of the blocklet.

Name	Type	Description
`input.did`	`string`	The DID of the blocklet.
`input.hashFiles`	`HashFileInput[]`	An array of objects, each with a `file` path and a `hash`.
`input.rootDid`	`string`	Optional. The DID of the root blocklet if checking a component.

Name	Type	Description
`input.did`	`string`	The DID of the blocklet.
`input.hours`	`number`	The number of past hours to retrieve history for.

Name	Type	Description
`input.launcherSessionId`	`string`	The session ID provided by the launcher.
`input.launcherUrl`	`string`	The URL of the launcher service.

Name	Type	Description
`input.did`	`string`	The DID of the blocklet.

Name	Type	Description
`input.did`	`string`	The DID of the blocklet.
`input.paging`	`PagingInput`	Optional. Pagination options.
`input.query`	`BlockletSecurityRuleQueryInput`	Optional. Search query for filtering rules.

Name	Type	Description
`input.did`	`string`	The DID of the blocklet.
`input.id`	`string`	The ID of the security rule.

Queries

User & Access Management

Table of Contents

Node Information
- getNodeInfo
- getNodeEnv
- checkNodeVersion
- getNodeRuntimeHistory
- resetNodeStatus
- getDelegationState
Blocklet Information & Lifecycle
- getBlocklets
- getBlocklet
- getBlockletMeta
- getBlockletMetaFromUrl
- getBlockletBaseInfo
- getBlockletDiff
- getBlockletRuntimeHistory
- getDynamicComponents
- getBlockletsFromBackup
- getLauncherSession
Blocklet Configuration & Security
- getBlockletSpaceGateways
- getBlockletSecurityRules
- getBlockletSecurityRule
- getBlockletAccessPolicies
- getBlockletAccessPolicy
- getBlockletResponseHeaderPolicies
- getBlockletResponseHeaderPolicy

Overview

Getting Started

Authentication

API Reference

Advanced Usage

Node & Blocklet Management

Node Information#

getNodeInfo#

getNodeEnv#

checkNodeVersion#

getNodeRuntimeHistory#

resetNodeStatus#

getDelegationState#

Blocklet Information & Lifecycle#

getBlocklets#

getBlocklet#

getBlockletMeta#

getBlockletMetaFromUrl#

getBlockletBaseInfo#

getBlockletDiff#

getBlockletRuntimeHistory#

getDynamicComponents#

getBlockletsFromBackup#

getLauncherSession#

Blocklet Configuration & Security#

getBlockletSpaceGateways#

getBlockletSecurityRules#

getBlockletSecurityRule#

getBlockletAccessPolicies#

getBlockletAccessPolicy#

getBlockletResponseHeaderPolicies#

getBlockletResponseHeaderPolicy#

Queries

User & Access Management