API Reference

Networking & Services

This section details the mutations available for managing networking and service configurations on your Blocklet Server. These methods allow you to programmatically control routing, domains, certificates, webhooks, and notifications. For methods to retrieve networking and service data, please see the Networking & Services Queries documentation.
Routing Management#These mutations allow you to configure how incoming requests are routed to your blocklets and services.
addRoutingSite#Creates a new routing site with a specified domain and an initial set of routing rules.
const client = new BlockletServerClient();
const result = await client.addRoutingSite({
  input: {
    domain: 'example.com',
    type: 'proxy',
    rules: [],
  },
});Parameters
Name
Type
Description
input
RequestAddRoutingSiteInput
An object containing the site's configuration.
input.domain
string
The primary domain for the new site.
input.type
string
The type of the routing site (e.g., 'proxy').
input.rules
RoutingRuleInput[]
An array of routing rules to apply to the site.
Returns
Returns a ResponseRoutingSite object containing the newly created site's configuration.
{
  "code": "ok",
  "site": {
    "id": "z2k9f8z9...",
    "domain": "example.com",
    "domainAliases": [],
    "rules": [],
    "isProtected": false,
    "corsAllowedOrigins": []
  }
}addDomainAlias#Adds a domain alias to an existing routing site, allowing it to respond to requests from multiple domains.
const client = new BlockletServerClient();
const result = await client.addDomainAlias({
  input: {
    id: 'z2k9f8z9...',
    domainAlias: 'www.example.com',
  },
});Parameters
Name
Type
Description
input
RequestAddDomainAliasInput
An object containing the details for the domain alias.
input.id
string
The ID of the routing site to which the alias will be added.
input.domainAlias
string
The new domain alias to add.
input.force
boolean
(Optional) If true, forces the addition even if conflicts exist.
Returns
Returns the updated ResponseRoutingSite object with the new alias.
{
  "code": "ok",
  "site": {
    "id": "z2k9f8z9...",
    "domain": "example.com",
    "domainAliases": [{ "value": "www.example.com" }],
    "rules": [],
    "isProtected": false,
    "corsAllowedOrigins": []
  }
}deleteDomainAlias#Removes a domain alias from a routing site.
const client = new BlockletServerClient();
const result = await client.deleteDomainAlias({
  input: {
    id: 'z2k9f8z9...',
    domainAlias: 'www.example.com',
  },
});Parameters
Name
Type
Description
input
RequestDeleteDomainAliasInput
An object containing the details for the domain alias to remove.
input.id
string
The ID of the routing site.
input.domainAlias
string
The domain alias to remove.
Returns
Returns the updated ResponseRoutingSite object.
deleteRoutingSite#Permanently deletes a routing site and all its associated rules and aliases.
const client = new BlockletServerClient();
const result = await client.deleteRoutingSite({
  input: {
    id: 'z2k9f8z9...',
  },
});Parameters
Name
Type
Description
input
RequestDeleteRoutingSiteInput
An object containing the ID of the site to delete.
input.id
string
The ID of the routing site to delete.
Returns
Returns a GeneralResponse object indicating the success of the operation.
{
  "code": "ok"
}updateRoutingSite#Updates the properties of an existing routing site, such as its primary domain or CORS settings.
const client = new BlockletServerClient();
const result = await client.updateRoutingSite({
  input: {
    id: 'z2k9f8z9...',
    corsAllowedOrigins: ['https://app.example.com'],
  },
});Parameters
Name
Type
Description
input
RequestUpdateRoutingSiteInput
An object containing the fields to update.
input.id
string
The ID of the routing site to update.
input.domain
string
(Optional) The new primary domain for the site.
input.corsAllowedOrigins
string[]
(Optional) An array of origins allowed for CORS.
Returns
Returns the updated ResponseRoutingSite object.
addRoutingRule#Adds a new routing rule to an existing site.
const client = new BlockletServerClient();
const result = await client.addRoutingRule({
  input: {
    id: 'z2k9f8z9...',
    rule: {
      from: { pathPrefix: '/api' },
      to: { type: 'blocklet', did: 'z8iZhf...', port: 3000 },
    },
  },
});Parameters
Name
Type
Description
input
RequestAddRoutingRuleInput
An object containing the site ID and the rule to add.
input.id
string
The ID of the routing site.
input.rule
RoutingRuleInput
The routing rule object to add.
Returns
Returns the updated ResponseRoutingSite object containing the new rule.
updateRoutingRule#Modifies an existing routing rule within a site.
const client = new BlockletServerClient();
const result = await client.updateRoutingRule({
  input: {
    id: 'z2k9f8z9...',
    rule: {
      id: 'z1m2n3p4...',
      from: { pathPrefix: '/api/v2' },
      to: { type: 'blocklet', did: 'z8iZhf...', port: 3001 },
    },
  },
});Parameters
Name
Type
Description
input
RequestUpdateRoutingRuleInput
An object containing the site ID and the updated rule.
input.id
string
The ID of the routing site.
input.rule
RoutingRuleInput
The full rule object with updated values. Must include the rule id.
Returns
Returns the updated ResponseRoutingSite object.
deleteRoutingRule#Removes a routing rule from a site.
const client = new BlockletServerClient();
const result = await client.deleteRoutingRule({
  input: {
    id: 'z2k9f8z9...',
    ruleId: 'z1m2n3p4...',
  },
});Parameters
Name
Type
Description
input
RequestDeleteRoutingRuleInput
An object containing the site ID and the rule ID to delete.
input.id
string
The ID of the routing site.
input.ruleId
string
The ID of the rule to delete.
Returns
Returns the updated ResponseRoutingSite object.
takeRoutingSnapshot#Creates a snapshot of the current routing configuration, which can be used for backups or rollbacks.
const client = new BlockletServerClient();
const result = await client.takeRoutingSnapshot({
  input: {
    message: 'Backup before major update',
  },
});Parameters
Name
Type
Description
input
RequestTakeRoutingSnapshotInput
An object for the snapshot.
input.message
string
A descriptive message for the snapshot.
input.dryRun
boolean
(Optional) If true, performs a dry run without creating the snapshot.
Returns
Returns a ResponseTakeRoutingSnapshot object containing the hash of the new snapshot.
{
  "code": "ok",
  "hash": "z3t7p5..."
}Certificate Management#These mutations handle the lifecycle of SSL/TLS certificates for your domains.
addCertificate#Adds a new custom SSL certificate to the node.
const client = new BlockletServerClient();
const result = await client.addCertificate({
  input: {
    name: 'my-custom-cert',
    privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n',
    certificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n',
  },
});Parameters
Name
Type
Description
input
RequestAddNginxHttpsCertInput
An object containing the certificate details.
input.name
string
A friendly name for the certificate.
input.privateKey
string
The private key in PEM format.
input.certificate
string
The certificate chain in PEM format.
Returns
Returns a ResponseAddNginxHttpsCert object indicating success.
{
  "code": "ok"
}updateCertificate#Updates the friendly name of an existing certificate.
const client = new BlockletServerClient();
const result = await client.updateCertificate({
  input: {
    id: 'z1a2b3c4...',
    name: 'My Custom Cert (Updated)',
  },
});Parameters
Name
Type
Description
input
RequestUpdateNginxHttpsCertInput
An object with the certificate ID and new name.
input.id
string
The ID of the certificate to update.
input.name
string
The new friendly name.
Returns
Returns a ResponseUpdateNginxHttpsCert object indicating success.
deleteCertificate#Permanently deletes a custom certificate from the node.
const client = new BlockletServerClient();
const result = await client.deleteCertificate({
  input: {
    id: 'z1a2b3c4...',
  },
});Parameters
Name
Type
Description
input
RequestDeleteNginxHttpsCertInput
An object containing the ID of the certificate to delete.
input.id
string
The ID of the certificate to delete.
Returns
Returns a ResponseDeleteNginxHttpsCert object indicating success.
issueLetsEncryptCert#Initiates a request to issue a new Let's Encrypt certificate for a specific domain.
const client = new BlockletServerClient();
const result = await client.issueLetsEncryptCert({
  input: {
    domain: 'example.com',
    did: 'z8iZhf...',
    siteId: 'z2k9f8z9...',
  },
});Parameters
Name
Type
Description
input
RequestAddLetsEncryptCertInput
An object containing the details for the certificate issuance.
input.domain
string
The domain for which to issue the certificate.
input.did
string
The blocklet DID associated with this domain.
input.siteId
string
The ID of the routing site.
Returns
Returns a ResponseAddLetsEncryptCert object indicating the request was initiated.
Notification Management#Manage the state of notifications for users.
readNotifications#Marks one or more notifications as read for a specific receiver.
const client = new BlockletServerClient();
const result = await client.readNotifications({
  input: {
    notificationIds: ['zN7oPq...'],
    receiver: 'z1u2v3w4...',
  },
});Parameters
Name
Type
Description
input
RequestReadNotificationsInput
An object containing the notification IDs and receiver.
input.notificationIds
string[]
An array of notification IDs to mark as read.
input.receiver
string
The DID of the user who received the notifications.
Returns
Returns a ResponseReadNotifications object indicating the number of notifications affected.
{
  "code": "ok",
  "numAffected": 1
}unreadNotifications#Marks one or more notifications as unread for a specific receiver.
const client = new BlockletServerClient();
const result = await client.unreadNotifications({
  input: {
    notificationIds: ['zN7oPq...'],
    receiver: 'z1u2v3w4...',
  },
});Parameters
Name
Type
Description
input
RequestReadNotificationsInput
An object containing the notification IDs and receiver.
input.notificationIds
string[]
An array of notification IDs to mark as unread.
input.receiver
string
The DID of the user.
Returns
Returns a ResponseReadNotifications object indicating the number of notifications affected.
Webhook Management#Configure webhooks to send notifications to external services.
createWebHook#Creates a new webhook configuration.
const client = new BlockletServerClient();
const result = await client.createWebHook({
  input: {
    type: 'slack',
    title: 'Slack Notifications',
    description: 'Send alerts to our main Slack channel.',
    params: [{ name: 'url', value: 'https://hooks.slack.com/services/...' }],
  },
});Parameters
Name
Type
Description
input
RequestCreateWebHookInput
An object containing the webhook configuration.
input.type
SenderType
The type of webhook (e.g., 'slack', 'api').
input.title
string
A title for the webhook.
input.description
string
A description of the webhook's purpose.
input.params
WebHookParamInput[]
An array of parameters, such as the target URL.
Returns
Returns a ResponseCreateWebHook object with the newly created webhook sender configuration.
deleteWebHook#Deletes an existing webhook configuration.
const client = new BlockletServerClient();
const result = await client.deleteWebHook({
  input: {
    id: 'zW5xYv...',
  },
});Parameters
Name
Type
Description
input
RequestDeleteWebHookInput
An object containing the ID of the webhook to delete.
input.id
string
The ID of the webhook configuration.
Returns
Returns a ResponseDeleteWebHook object indicating success.
{
  "code": "ok"
}createWebhookEndpoint#Creates a new webhook endpoint to receive events from the Blocklet Server.
const client = new BlockletServerClient();
const result = await client.createWebhookEndpoint({
  input: {
    teamDid: 'z8iZhf...',
    input: {
      url: 'https://yourapp.com/webhooks',
      description: 'Webhook for new user signups',
      enabledEvents: [{ type: 'user.created', source: 'system' }]
    }
  }
});Parameters
Name
Type
Description
input
RequestCreateWebhookEndpointInput
An object containing the endpoint configuration.
input.teamDid
string
The DID of the team/blocklet this webhook belongs to.
input.input
WebhookEndpointStateInput
The detailed configuration for the new endpoint.
input.input.url
string
The URL where the webhook payloads will be sent.
input.input.description
string
(Optional) A description for the endpoint.
input.input.enabledEvents
EnableEventInput[]
An array of event types that will trigger this webhook.
Returns
Returns a ResponseCreateWebhookEndpoint object containing the state of the newly created endpoint.
updateWebhookEndpoint#Updates an existing webhook endpoint's configuration.
const client = new BlockletServerClient();
const result = await client.updateWebhookEndpoint({
  input: {
    teamDid: 'z8iZhf...',
    id: 'whep_123...',
    data: {
      description: 'Updated webhook description',
      enabledEvents: [{ type: 'user.created', source: 'system' }, { type: 'user.deleted', source: 'system' }]
    }
  }
});Parameters
Name
Type
Description
input
RequestUpdateWebhookEndpointInput
An object containing the updates.
input.teamDid
string
The DID of the team/blocklet.
input.id
string
The ID of the webhook endpoint to update.
input.data
WebhookEndpointStateInput
An object with the fields to update.
Returns
Returns a ResponseUpdateWebhookEndpoint object with the updated endpoint state.
deleteWebhookEndpoint#Deletes a webhook endpoint.
const client = new BlockletServerClient();
const result = await client.deleteWebhookEndpoint({
  input: {
    teamDid: 'z8iZhf...',
    id: 'whep_123...'
  }
});Parameters
Name
Type
Description
input
RequestDeleteWebhookEndpointInput
An object specifying the endpoint to delete.
input.teamDid
string
The DID of the team/blocklet.
input.id
string
The ID of the webhook endpoint to delete.
Returns
Returns a ResponseDeleteWebhookEndpoint object with the state of the deleted endpoint.
retryWebhookAttempt#Manually retries a failed webhook delivery attempt.
const client = new BlockletServerClient();
const result = await client.retryWebhookAttempt({
  input: {
    teamDid: 'z8iZhf...',
    eventId: 'evt_123...',
    webhookId: 'whep_123...',
    attemptId: 'att_123...'
  }
});Parameters
Name
Type
Description
input
RequestAttemptInput
An object identifying the specific attempt to retry.
input.teamDid
string
The DID of the team/blocklet.
input.eventId
string
The ID of the original event.
input.webhookId
string
The ID of the webhook endpoint.
input.attemptId
string
The ID of the failed attempt.
Returns
Returns a ResponseGetWebhookAttempt object containing the state of the new attempt.

After managing your node's networking and services, you might need to handle operational tasks. Proceed to the Data & Operations section to learn about mutations for managing backups and other data-related operations.

Name	Type	Description
`input`	`RequestAddRoutingSiteInput`	An object containing the site's configuration.
`input.domain`	`string`	The primary domain for the new site.
`input.type`	`string`	The type of the routing site (e.g., 'proxy').
`input.rules`	`RoutingRuleInput[]`	An array of routing rules to apply to the site.

Name	Type	Description
`input`	`RequestAddDomainAliasInput`	An object containing the details for the domain alias.
`input.id`	`string`	The ID of the routing site to which the alias will be added.
`input.domainAlias`	`string`	The new domain alias to add.
`input.force`	`boolean`	(Optional) If true, forces the addition even if conflicts exist.

Name	Type	Description
`input`	`RequestUpdateRoutingSiteInput`	An object containing the fields to update.
`input.id`	`string`	The ID of the routing site to update.
`input.domain`	`string`	(Optional) The new primary domain for the site.
`input.corsAllowedOrigins`	`string[]`	(Optional) An array of origins allowed for CORS.

Name	Type	Description
`input`	`RequestUpdateRoutingRuleInput`	An object containing the site ID and the updated rule.
`input.id`	`string`	The ID of the routing site.
`input.rule`	`RoutingRuleInput`	The full rule object with updated values. Must include the rule `id`.

Name	Type	Description
`input`	`RequestAddNginxHttpsCertInput`	An object containing the certificate details.
`input.name`	`string`	A friendly name for the certificate.
`input.privateKey`	`string`	The private key in PEM format.
`input.certificate`	`string`	The certificate chain in PEM format.

Overview

Getting Started

Authentication

API Reference

Advanced Usage

Networking & Services

Routing Management#

`addRoutingSite`#

`addDomainAlias`#

`deleteDomainAlias`#

`deleteRoutingSite`#

`updateRoutingSite`#

`addRoutingRule`#

`updateRoutingRule`#

`deleteRoutingRule`#

`takeRoutingSnapshot`#

Certificate Management#

`addCertificate`#

`updateCertificate`#

`deleteCertificate`#

`issueLetsEncryptCert`#

Notification Management#

`readNotifications`#

`unreadNotifications`#

Webhook Management#

`createWebHook`#

`deleteWebHook`#

`createWebhookEndpoint`#

`updateWebhookEndpoint`#

`deleteWebhookEndpoint`#

`retryWebhookAttempt`#

User & Access Management

Data & Operations

Name	Type	Description
`input`	`RequestDeleteDomainAliasInput`	An object containing the details for the domain alias to remove.
`input.id`	`string`	The ID of the routing site.
`input.domainAlias`	`string`	The domain alias to remove.

Name	Type	Description
`input`	`RequestDeleteRoutingSiteInput`	An object containing the ID of the site to delete.
`input.id`	`string`	The ID of the routing site to delete.

Name	Type	Description
`input`	`RequestAddRoutingRuleInput`	An object containing the site ID and the rule to add.
`input.id`	`string`	The ID of the routing site.
`input.rule`	`RoutingRuleInput`	The routing rule object to add.

Name	Type	Description
`input`	`RequestDeleteRoutingRuleInput`	An object containing the site ID and the rule ID to delete.
`input.id`	`string`	The ID of the routing site.
`input.ruleId`	`string`	The ID of the rule to delete.

Name	Type	Description
`input`	`RequestTakeRoutingSnapshotInput`	An object for the snapshot.
`input.message`	`string`	A descriptive message for the snapshot.
`input.dryRun`	`boolean`	(Optional) If true, performs a dry run without creating the snapshot.

Name	Type	Description
`input`	`RequestUpdateNginxHttpsCertInput`	An object with the certificate ID and new name.
`input.id`	`string`	The ID of the certificate to update.
`input.name`	`string`	The new friendly name.

Name	Type	Description
`input`	`RequestDeleteNginxHttpsCertInput`	An object containing the ID of the certificate to delete.
`input.id`	`string`	The ID of the certificate to delete.

Name	Type	Description
`input`	`RequestAddLetsEncryptCertInput`	An object containing the details for the certificate issuance.
`input.domain`	`string`	The domain for which to issue the certificate.
`input.did`	`string`	The blocklet DID associated with this domain.
`input.siteId`	`string`	The ID of the routing site.

Name	Type	Description
`input`	`RequestReadNotificationsInput`	An object containing the notification IDs and receiver.
`input.notificationIds`	`string[]`	An array of notification IDs to mark as read.
`input.receiver`	`string`	The DID of the user who received the notifications.

Name	Type	Description
`input`	`RequestCreateWebHookInput`	An object containing the webhook configuration.
`input.type`	`SenderType`	The type of webhook (e.g., `'slack'`, `'api'`).
`input.title`	`string`	A title for the webhook.
`input.description`	`string`	A description of the webhook's purpose.
`input.params`	`WebHookParamInput[]`	An array of parameters, such as the target URL.

Name	Type	Description
`input`	`RequestDeleteWebHookInput`	An object containing the ID of the webhook to delete.
`input.id`	`string`	The ID of the webhook configuration.

Name	Type	Description
`input`	`RequestCreateWebhookEndpointInput`	An object containing the endpoint configuration.
`input.teamDid`	`string`	The DID of the team/blocklet this webhook belongs to.
`input.input`	`WebhookEndpointStateInput`	The detailed configuration for the new endpoint.
`input.input.url`	`string`	The URL where the webhook payloads will be sent.
`input.input.description`	`string`	(Optional) A description for the endpoint.
`input.input.enabledEvents`	`EnableEventInput[]`	An array of event types that will trigger this webhook.

Name	Type	Description
`input`	`RequestUpdateWebhookEndpointInput`	An object containing the updates.
`input.teamDid`	`string`	The DID of the team/blocklet.
`input.id`	`string`	The ID of the webhook endpoint to update.
`input.data`	`WebhookEndpointStateInput`	An object with the fields to update.

Name	Type	Description
`input`	`RequestDeleteWebhookEndpointInput`	An object specifying the endpoint to delete.
`input.teamDid`	`string`	The DID of the team/blocklet.
`input.id`	`string`	The ID of the webhook endpoint to delete.

Name	Type	Description
`input`	`RequestAttemptInput`	An object identifying the specific attempt to retry.
`input.teamDid`	`string`	The DID of the team/blocklet.
`input.eventId`	`string`	The ID of the original event.
`input.webhookId`	`string`	The ID of the webhook endpoint.
`input.attemptId`	`string`	The ID of the failed attempt.