API Reference
Node & Blocklet Management

These mutations allow you to programmatically manage the lifecycle and configuration of your Blocklets and the underlying Blocklet Server node. You can install, start, stop, update, and configure applications and their components.
For fetching the state of your node and blocklets, refer to the Node & Blocklet Management Queries section.
Blocklet Lifecycle#These mutations control the fundamental lifecycle of a Blocklet, from installation to deletion.
installBlocklet#Installs a new Blocklet from a registry, URL, or uploaded file. This is the primary method for adding new applications to your node.
Parameters
Name
Type
Description
input
RequestVersionedBlockletInput
An object containing the installation parameters.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.installBlocklet({
  input: {
    type: 'url',
    url: 'https://store.arcblock.io/api/blocklets/z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD',
    title: 'My New Blocklet',
    startImmediately: true,
  },
});
console.log(result.blocklet);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD",
      "name": "my-new-blocklet",
      "version": "1.0.0",
      "title": "My New Blocklet"
    },
    "status": "running"
  }
}startBlocklet#Starts one or more components of an installed Blocklet. If no specific componentDids are provided, it attempts to start the entire application.
Parameters
Name
Type
Description
input
RequestComponentsInput
An object specifying the Blocklet and components to start.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.startBlocklet({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD'
  },
});
console.log(result.blocklet.status);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "status": "running"
  }
}stopBlocklet#Stops one or more running components of a Blocklet.
Parameters
Name
Type
Description
input
RequestComponentsInput
An object specifying the Blocklet and components to stop.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.stopBlocklet({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD'
  },
});
console.log(result.blocklet.status);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "status": "stopped"
  }
}restartBlocklet#Restarts one or more components of a Blocklet.
Parameters
Name
Type
Description
input
RequestComponentsInput
An object specifying the Blocklet and components to restart.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.restartBlocklet({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD'
  },
});
console.log(result.blocklet.status);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "status": "running"
  }
}reloadBlocklet#Reloads a running Blocklet's components without a full stop/start cycle, which is faster for applying configuration changes.
Parameters
Name
Type
Description
input
RequestComponentsInput
An object specifying the Blocklet and components to reload.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.reloadBlocklet({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD'
  },
});
console.log(result.blocklet.status);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "status": "running"
  }
}deleteBlocklet#Permanently removes a Blocklet and its components from the node.
Parameters
Name
Type
Description
input
RequestDeleteBlockletInput
An object specifying the Blocklet to delete and whether to retain its data.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.deleteBlocklet({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD',
    keepData: false
  },
});
console.log(result.code);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "status": "deleted"
  }
}Component Management#These mutations handle the lifecycle of individual components within an existing Blocklet.
installComponent#Installs a new component into an existing Blocklet.
Parameters
Name
Type
Description
input
RequestInstallComponentInput
An object containing the component installation details.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.installComponent({
  input: {
    rootDid: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD',
    url: 'https://store.arcblock.io/api/blocklets/z8ia...', 
    mountPoint: '/new-component'
  },
});
console.log(result.code);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "children": [
      {
        "meta": {
          "did": "z8ia..."
        },
        "status": "installed",
        "mountPoint": "/new-component"
      }
    ]
  }
}deleteComponent#Removes a component from a Blocklet.
Parameters
Name
Type
Description
input
RequestDeleteComponentInput
An object specifying the component to delete.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.deleteComponent({
  input: {
    rootDid: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD',
    did: 'z8ia...', 
    keepData: false
  },
});
console.log(result.code);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    }
  }
}Upgrades & Updates#Manage the update process for Blocklets and their components.
checkComponentsForUpdates#Checks for available updates for a Blocklet and its components.
Parameters
Name
Type
Description
input
RequestBlockletInput
An object containing the DID of the Blocklet to check.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.checkComponentsForUpdates({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD'
  },
});
console.log(result.preUpdateInfo);Response
{
  "code": "ok",
  "preUpdateInfo": {
    "updateId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "updateList": [
      {
        "id": "z8iZttmN8a3xH1x9J2g1e2j7J3d6i8KkM4qD",
        "meta": {
          "did": "z8iZttmN8a3xH1x9J2g1e2j7J3d6i8KkM4qD",
          "name": "component-a",
          "version": "1.2.0"
        }
      }
    ]
  }
}upgradeComponents#Upgrades selected components of a Blocklet to their latest available versions.
Parameters
Name
Type
Description
input
RequestUpdateComponentsInput
An object specifying the update session and the components to upgrade.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.upgradeComponents({
  input: {
    rootDid: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD',
    updateId: 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
    selectedComponents: ['z8iZttmN8a3xH1x9J2g1e2j7J3d6i8KkM4qD']
  },
});
console.log(result.code);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "status": "running"
  }
}cancelDownloadBlocklet#Cancels a pending download for a Blocklet or its components.
Parameters
Name
Type
Description
input
RequestBlockletInput
An object specifying the Blocklet DID whose download should be canceled.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.cancelDownloadBlocklet({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD'
  },
});
console.log(result.code);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "status": "stopped"
  }
}Configuration & Operations#Mutations for configuring various aspects of the node and individual Blocklets.
updateNodeInfo#Updates the general information and settings for the Blocklet Server node.
Parameters
Name
Type
Description
input
NodeInfoInput
An object containing the node settings to update.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.updateNodeInfo({
  input: {
    name: 'My Production Node',
    description: 'Main server for production applications.',
    autoUpgrade: true
  },
});
console.log(result.info.name);Response
{
  "code": "ok",
  "info": {
    "did": "z1...",
    "name": "My Production Node",
    "description": "Main server for production applications.",
    "autoUpgrade": true
  }
}configBlocklet#Sets or updates configuration values (environment variables) for a Blocklet or its components.
Parameters
Name
Type
Description
input
RequestConfigBlockletInput
An object containing the DID of the Blocklet and an array of configuration key-value pairs.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.configBlocklet({
  input: {
    did: ['z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD'],
    configs: [
      {
        "key": "API_ENDPOINT",
        "value": "https://api.example.com"
      }
    ]
  },
});
console.log(result.code);Response
{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD"
    },
    "configs": [
      {
        "key": "API_ENDPOINT",
        "value": "https://api.example.com"
      }
    ]
  }
}updateBlockletSettings#Updates various structured settings for a specific Blocklet, such as gateway policies, invite settings, and AIGNE configuration.
Parameters
Name
Type
Description
input
RequestBlockletSettingsInput
An object containing the Blocklet DID and the settings to update.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.updateBlockletSettings({
  input: {
    did: 'z8ia1jRZ8i9aY2Y7j2g1e2j7J3d6i8KkM4qD',
    invite: { enabled: true },
    gateway: { cacheEnabled: true }
  },
});
console.log(result.code);Response
{
  "code": "ok"
}restartServer#Restarts the entire Blocklet Server daemon. This will cause a brief service interruption.
Example
import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient(endpoint);
const result = await client.restartServer();
console.log(result.sessionId);Response
{
  "code": "ok",
  "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}resetNode#Resets various parts of the node to a clean state. This is a destructive operation and should be used with caution.
Parameters
Name
Type
Description
input
RequestResetNodeInput
An object with boolean flags specifying which parts of the node to reset.
Example
import BlockletServerClient from '@blocklet/server-js';

// Reset all blocklets and routing rules
const client = new BlockletServerClient(endpoint);
const result = await client.resetNode({
  input: {
    blocklets: true,
    routingRules: true
  },
});
console.log(result.code);Response
{
  "code": "ok"
}
This section detailed how to manage the lifecycle and configuration of nodes and Blocklets. To manage users and their access rights, proceed to the User & Access Management Mutations section.
Overview

Getting Started

Authentication

API Reference

Advanced Usage

Node & Blocklet Management

Blocklet Lifecycle#

installBlocklet#

startBlocklet#

stopBlocklet#

restartBlocklet#

reloadBlocklet#

deleteBlocklet#

Component Management#

installComponent#

deleteComponent#

Upgrades & Updates#

checkComponentsForUpdates#

upgradeComponents#

cancelDownloadBlocklet#

Configuration & Operations#

updateNodeInfo#

configBlocklet#

updateBlockletSettings#

restartServer#

resetNode#

Mutations

User & Access Management
