Types

The Blocklet Server Client API utilizes a variety of GraphQL types to structure the data for queries and mutations. This section provides a comprehensive reference for all data types, input objects, enums, and scalars used throughout the API. Understanding these types is crucial for constructing valid requests and interpreting the responses from the Blocklet Server.

Scalar Types#

Scalar types represent the leaves of a GraphQL query. They are primitive values like strings, numbers, or booleans.

Scalar

Description

String

Represents textual data, represented as UTF-8 character sequences.

Boolean

Represents true or false.

Int

Represents a signed 32‐bit integer.

Float

Represents signed double-precision floating-point values.

ID

Represents a unique identifier, often used to refetch an object or as a key for a cache.

Any

Represents any JSON-compatible value.

Bytes

Represents a byte array.

Int32

Represents a 32-bit signed integer.

Uint32

Represents a 32-bit unsigned integer.

Int64

Represents a 64-bit signed integer.

Uint64

Represents a 64-bit unsigned integer.

Float32

Represents a 32-bit floating-point number.

Upload

Represents a file upload, typically used in mutations.

Enum Types#

Enums are a special kind of scalar that is restricted to a particular set of allowed values.

BackendServiceType#

Defines the type of backend service a routing rule points to.

Value

Description

daemon

The service is the node daemon itself.

blocklet

The service is a running blocklet.

redirect

The rule performs an HTTP redirect.

none

No backend service is configured.

general_proxy

The rule acts as a general proxy to a specified URL.

direct_response

The rule returns a direct, static response.

rewrite

The rule rewrites the request path.

component

The service is a specific component within a blocklet.

BackupTo#

Specifies the destination for a blocklet backup.

Value

Description

spaces

Backup to a decentralized storage space.

disk

Backup to the local disk.

BlockletSource#

Indicates the origin from which a blocklet was installed.

Value

Description

registry

Installed from a blocklet registry/store.

local

Installed from a local directory.

upload

Installed from an uploaded file.

url

Installed from a direct URL.

custom

Installed through a custom or unknown method.

BlockletStatus#

Represents the current lifecycle status of a blocklet.

Value

Description

added

Blocklet has been added but not yet downloaded.

downloading

Blocklet is currently being downloaded.

downloaded

Blocklet has been downloaded successfully.

installing

Blocklet is currently being installed.

installed

Blocklet has been installed but is not running.

starting

Blocklet is in the process of starting.

running

Blocklet is currently running.

stopping

Blocklet is in the process of stopping.

stopped

Blocklet is stopped.

error

An error occurred in the blocklet's lifecycle.

upgrading

Blocklet is currently being upgraded.

restarting

Blocklet is restarting.

corrupted

Blocklet installation is corrupted.

waiting

Blocklet is waiting for a dependency or resource.

deleted

Blocklet has been deleted.

unknown

The status of the blocklet is unknown.

HeaderMatchType#

Defines the matching strategy for HTTP headers in routing rules.

Value

Description

exact

The header value must be an exact match.

partial

The header value must contain the specified string.

regexp

The header value must match the specified regular expression.

Notification_NotificationSeverity#

Defines the severity level of a notification.

Value

Description

info

Informational message.

success

Indicates a successful operation.

error

Indicates an error has occurred.

warning

Indicates a potential issue or warning.

Notification_NotificationSource#

Specifies the source of the notification.

Value

Description

system

Notification originated from the system/node.

component

Notification originated from a blocklet component.

Notification_NotificationType#

Defines the type or category of the notification.

Value

Description

notification

A standard notification message.

connect

A notification related to DID Connect.

feed

A feed-style update.

hi

A simple greeting or test notification.

passthrough

A notification that is passed through without special handling.

NotificationActivity_ActivityTypeEnum#

Defines the type of user activity for feed-style notifications.

Value

Description

comment

A user made a comment.

like

A user liked an item.

follow

A user followed another user or item.

tips

A user sent a tip.

mention

A user was mentioned.

assign

A user was assigned a task.

un_assign

A user was unassigned from a task.

NotificationAttachmentType#

Defines the type of attachment included in a notification.

Value

Description

asset

A digital asset.

vc

A Verifiable Credential.

token

A digital token.

text

A plain text attachment.

image

An image attachment.

divider

A visual divider for formatting.

transaction

A transaction record.

dapp

A decentralized application link.

link

A hyperlink.

section

A formatted section of content.

PublishType#

Specifies the type of artifact being published.

Value

Description

resource

A single resource file.

pack

A packed blocklet bundle.

ReleaseStatus#

Indicates the status of a release in a publishing project.

Value

Description

draft

The release is a draft and not yet published.

published

The release has been published.

SenderType#

Defines the type of webhook sender.

Value

Description

slack

A Slack webhook.

api

A generic API webhook.

StatusCode#

Represents the status code of an API response.

Value

Description

ok

The request was successful.

blocklet_not_found

The requested blocklet could not be found.

blocklet_not_purchased

The requested blocklet has not been purchased.

forbidden

The request is forbidden due to insufficient permissions.

internal

An internal server error occurred.

timeout

The request timed out.

Input Objects#

Input objects are complex types used as arguments for mutations and queries, allowing you to pass structured data in a single parameter.

AigneConfigInput#

Configuration for the AI Gateway (Aigne).

provider
String
The AI service provider (e.g., 'openai').
model
String
The specific model to use (e.g., 'gpt-4').
key
String
The API key for the service.
url
String
The base URL for the API endpoint.
accessKeyId
String
Access Key ID for providers like AWS.
secretAccessKey
String
Secret Access Key for providers like AWS.
validationResult
String
The result of the last connection validation.

AutoBackupInput#

Configuration for automatic backups.

enabled
Boolean
Whether automatic backups are enabled.

AutoBlockPolicyInput#

Configuration for automatic IP blocking policies.

enabled
Boolean
Whether automatic blocking is enabled.
windowSize
Uint32
The time window in seconds to monitor requests.
windowQuota
Uint32
The maximum number of requests allowed within the window.
blockDuration
Uint32
The duration in seconds to block an IP after exceeding the quota.
statusCodes
[Uint32!]
A list of HTTP status codes to consider for blocking.

AutoCheckUpdateInput#

Configuration for automatic update checks.

enabled
Boolean
Whether automatic update checks are enabled.

BaseUserInfoInput#

Basic user information used in various input types.

did
String
The user's Decentralized Identifier (DID).
pk
String
The user's public key.
role
String
The user's role.
avatar
String
URL to the user's avatar image.
fullName
String
The user's full name.
email
String
The user's email address.
approved
Boolean
Whether the user is approved.
createdAt
Uint32
Timestamp of when the user was created.
updatedAt
Uint32
Timestamp of the last update to the user's profile.
locale
String
The user's preferred locale (e.g., 'en').

BlockPolicyInput#

Configuration for IP blocking policies.

enabled
Boolean
Whether the block policy is enabled.
blacklist
[String!]
A list of IP addresses to permanently block.
autoBlocking
AutoBlockPolicyInput
Configuration for automatic IP blocking.

BlockletAccessPolicyInput#

Defines a blocklet access policy.

id
String
The unique identifier for the policy.
name
String
A descriptive name for the policy.
description
String
A detailed description of the policy.
roles
Any
The roles this policy applies to.
reverse
Boolean
If true, the policy logic is inverted (deny instead of allow).
isProtected
Boolean
If true, the policy cannot be easily modified or deleted.

BlockletAccessPolicyQueryInput#

Input for querying BlockletAccessPolicy objects.

search
String
A search string to filter policies by name or description.

BlockletDistInput#

Describes the distribution file of a blocklet.

tarball
String
The URL of the blocklet's tarball file.
integrity
String
The integrity hash of the tarball for verification.

BlockletDockerInput#

Defines Docker-related settings for a blocklet.

dockerImage
String
The name of the Docker image to use.
dockerArgs
[DockerRunKeyValuePairInput!]
Arguments to pass to the docker run command.
dockerEnvs
[DockerEnvKeyValuePairInput!]
Environment variables to set in the container.
dockerCommand
String
The command to execute inside the container.

BlockletGatewayInput#

Configuration for a blocklet's gateway settings.

requestLimit
RequestLimitInput
Request limiting configuration.
blockPolicy
BlockPolicyInput
IP blocking policy configuration.
proxyPolicy
ProxyPolicyInput
Proxy policy configuration.
cacheEnabled
Boolean
Whether caching is enabled at the gateway.
wafPolicy
WAFPolicyInput
Web Application Firewall policy configuration.
teamDid
String
The DID of the team associated with this configuration.

BlockletResponseHeaderPolicyInput#

Defines a response header policy.

id
String
The unique identifier for the policy.
name
String
A descriptive name for the policy.
description
String
A detailed description of the policy.
securityHeader
String
JSON string of security-related headers.
cors
String
JSON string of CORS headers.
customHeader
String
JSON string of custom headers to add.
removeHeader
String
JSON string of headers to remove.
isProtected
Boolean
If true, the policy cannot be easily modified or deleted.

BlockletResponseHeaderPolicyQueryInput#

Input for querying BlockletResponseHeaderPolicy objects.

search
String
A search string to filter policies by name or description.

BlockletSecurityRuleInput#

Defines a security rule that combines access and header policies for a specific path.

id
String
The unique identifier for the rule.
pathPattern
String
The URL path pattern this rule applies to.
componentDid
String
The DID of the component this rule is associated with.
priority
Uint32
The execution priority of the rule (lower numbers execute first).
responseHeaderPolicyId
String
The ID of the response header policy to apply.
accessPolicyId
String
The ID of the access policy to apply.
enabled
Boolean
Whether the rule is currently active.
remark
String
An optional remark or note about the rule.
accessPolicy
BlockletAccessPolicyInput
The full access policy object (used when creating a new rule).
responseHeaderPolicy
BlockletResponseHeaderPolicyInput
The full response header policy object (used when creating a new rule).

BlockletSecurityRuleQueryInput#

Input for querying BlockletSecurityRule objects.

search
String
A search string to filter rules by path pattern or remark.

BlockletStoreInput#

Represents a blocklet store/registry.

name
String
The name of the store.
description
String
A description of the store.
url
String
The URL of the store.
logoUrl
String
The URL of the store's logo.
maintainer
String
The maintainer of the store.
cdnUrl
String
The CDN URL used by the store.
protected
Boolean
Whether the store requires authentication.
id
String
The unique identifier of the store.
scope
String
The scope of the store (e.g., 'public', 'private').

ConfigEntryInput#

Represents a single configuration key-value pair.

key
String
The configuration key.
value
String
The configuration value.
required
Boolean
Whether this configuration is required.
description
String
A description of the configuration item.
validation
String
A validation rule or pattern for the value.
secure
Boolean
If true, the value is sensitive and should be treated as a secret.
custom
Boolean
If true, this is a custom, user-defined configuration.
shared
Boolean
If true, this configuration is shared among components.

ConfigNavigationInput#

Represents a navigation item in the user interface.

id
String
The unique ID of the navigation item.
title
String
The display title.
link
String
The destination URL or path.
icon
String
The icon for the navigation item.
section
String
The section where this item should appear (e.g., 'sidebar').
component
String
The component this navigation item belongs to.
parent
String
The ID of the parent navigation item, if any.
role
String
The role required to see this item.
visible
Boolean
Whether the item is visible.
from
String
The source of this navigation configuration (e.g., 'blocklet', 'user').
activeIcon
String
The icon to display when the navigation item is active.
color
String
The color of the navigation item text.
activeColor
String
The color when the navigation item is active.
description
String
A description for the navigation item.
private
Boolean
Indicates if the navigation item is private.

ConnectedAccountInfoInput#

Information about a user's account from a third-party provider.

name
String
User's name from the provider.
picture
String
URL of the user's profile picture.
email
String
User's email from the provider.
emailVerified
Boolean
Whether the email is verified by the provider.
sub
String
The subject identifier from the provider.
extraData
Any
Any additional data from the provider.

ConnectedAccountInput#

Represents a user's connected third-party account.

provider
String
The name of the third-party provider (e.g., 'github').
did
String
The DID associated with this connected account.
pk
String
The public key.
id
String
The unique ID of the connection.
lastLoginAt
Uint32
Timestamp of the last login with this account.
userInfo
ConnectedAccountInfoInput
Detailed user information from the provider.
extra
Any
Any additional metadata.

DockerEnvKeyValuePairInput#

Represents a single environment variable for a Docker container.

key
String
The environment variable key.
value
String
The environment variable value.
description
String
A description of the variable.
secure
Boolean
If true, the value is sensitive.
shared
Boolean
If true, the variable is shared.
required
Boolean
If true, this variable must be set.
custom
String
Indicates if it's a custom variable.

DockerRunKeyValuePairInput#

Represents a key-value pair for Docker run arguments, such as volume mounts or port mappings.

key
String
The argument key (e.g., '-v', '-p').
value
String
The argument value.
path
String
The path for volume mounts.
type
String
The type of argument.
name
String
The name of the argument.
prefix
String
A prefix for the argument.
protocol
String
The protocol for port mappings (e.g., 'tcp').
proxyBehavior
String
Defines how this argument affects proxying.

DownloadTokenInput#

Token used for downloading a private blocklet.

did
String
The DID of the blocklet requiring the token.
token
String
The download token.

EnableEventInput#

Structure for enabling a specific event for a webhook.

type
String
The type of the event (e.g., 'blocklet.started').
source
String
The source of the event.

GatewayInput#

Structure for configuring the main node gateway.

requestLimit
RequestLimitInput
Request limiting configuration.
blockPolicy
BlockPolicyInput
IP blocking policy configuration.
proxyPolicy
ProxyPolicyInput
Proxy policy configuration.
cacheEnabled
Boolean
Whether caching is enabled at the gateway.
wafPolicy
WAFPolicyInput
Web Application Firewall policy configuration.

HashFileInput#

Represents a file and its corresponding hash.

file
String
The path to the file.
hash
String
The hash of the file content.

InviteSettingsInput#

Structure for configuring user invitation settings.

enabled
Boolean
Whether user invitations are enabled.

IssuerInput#

Represents the issuer of a credential or passport.

id
String
The DID of the issuer.
name
String
The name of the issuer.
pk
String
The public key of the issuer.

LoginEmailSettingsInput#

Structure for email-based login settings.

enabled
Boolean
Whether email login is enabled.
requireVerified
Boolean
If true, users must verify their email address.
requireUnique
Boolean
If true, email addresses must be unique across all users.
trustOauthProviders
Boolean
If true, email addresses from OAuth providers are trusted by default.
enableDomainBlackList
Boolean
Whether to use a domain blacklist.
domainBlackList
[String!]
A list of email domains to block.
enableDomainWhiteList
Boolean
Whether to use a domain whitelist.
domainWhiteList
[String!]
A list of allowed email domains.
trustedIssuers
[IssuerInput!]
A list of trusted issuers for email verification.

LoginPhoneSettingsInput#

Structure for phone-based login settings.

enabled
Boolean
Whether phone login is enabled.
requireVerified
Boolean
If true, users must verify their phone number.
requireUnique
Boolean
If true, phone numbers must be unique.
trustedIssuers
[IssuerInput!]
A list of trusted issuers for phone verification.
enableRegionBlackList
Boolean
Whether to use a region blacklist.
regionBlackList
[String!]
A list of blocked country codes.
enableRegionWhiteList
Boolean
Whether to use a region whitelist.
regionWhiteList
[String!]
A list of allowed country codes.

NodeInfoInput#

Structure for updating the node's information.

name
String
The display name of the node.
description
String
A description of the node.
autoUpgrade
Boolean
Whether the node should upgrade automatically.
enableWelcomePage
Boolean
Whether to show the welcome page.
registerUrl
String
The URL for user registration.
webWalletUrl
String
The URL of the web wallet.
blockletRegistryList
[BlockletStoreInput!]
A list of configured blocklet registries.
diskAlertThreshold
Uint32
The disk usage percentage at which to trigger an alert.
enableBetaRelease
Boolean
Whether to allow installation of beta releases.
nftDomainUrl
String
The URL for NFT domain services.
enableFileSystemIsolation
Boolean
Whether to isolate blocklet file systems.
enableDocker
Boolean
Whether to enable Docker for blocklets.
isDockerInstalled
Boolean
Read-only field indicating if Docker is installed.
enableDockerNetwork
Boolean
Whether to enable custom Docker networking.
enableSessionHardening
Boolean
Whether to enable advanced session security features.

OauthClientInput#

Structure for creating or updating an OAuth client.

redirectUris
[String!]
An array of allowed redirect URIs.
tokenEndpointAuthMethod
String
The authentication method for the token endpoint.
grantTypes
[String!]
The OAuth grant types this client is allowed to use.
responseTypes
[String!]
The OAuth response types this client is allowed to use.
clientName
String
The name of the client application.
clientId
String
The unique ID of the client.
clientSecret
String
The client secret.

PagingInput#

Standard structure for pagination parameters.

page
Uint32
The page number to retrieve.
pageSize
Uint32
The number of items per page.

PassportDisplayInput#

Structure for defining how a passport is displayed.

type
String
The display type (e.g., 'text', 'image').
content
String
The content to be displayed.

PermissionInput#

Structure for creating or updating a permission.

name
String
The name of the permission (e.g., 'user:create').
description
String
A description of what the permission allows.
isProtected
Boolean
If true, the permission cannot be easily modified or deleted.

ProxyPolicyInput#

Structure for configuring proxy behavior.

enabled
Boolean
Whether the proxy policy is enabled.
trustRecursive
Boolean
Whether to trust all proxies in the chain.
trustedProxies
[String!]
A list of trusted proxy IP addresses.
realIpHeader
String
The HTTP header used to identify the real client IP.

RequestLimitInput#

Structure for configuring request rate limiting.

enabled
Boolean
Whether rate limiting is enabled.
global
Uint32
The global request limit.
rate
Uint32
The number of requests per time unit.
methods
[String!]
The HTTP methods to which this limit applies.

RoleUpdateInput#

Structure for updating a user role.

name
String
The unique name of the role.
title
String
The human-readable title of the role.
description
String
A description of the role.
extra
String
Extra metadata for the role in JSON format.

RoutingRuleInput#

Structure for defining a routing rule.

id
String
The unique ID of the rule.
from
RoutingRuleFromInput
The source criteria for the rule.
to
RoutingRuleToInput
The destination target for the rule.
isProtected
Boolean
If true, the rule cannot be easily modified or deleted.

SessionConfigInput#

Structure for configuring user session settings.

cacheTtl
Uint32
The Time-to-Live (TTL) for session cache, in seconds.
ttl
Uint32
The TTL for the session itself, in seconds.
email
LoginEmailSettingsInput
Email login settings.
phone
LoginPhoneSettingsInput
Phone login settings.
salt
String
The salt used for session key generation.
enableBlacklist
Boolean
Whether to enable session blacklisting.

TagInput#

Structure for creating or updating a tag.

id
Uint32
The unique ID of the tag (used for updates).
title
String
The title of the tag.
description
String
A description of the tag.
color
String
The color associated with the tag (hex code).

UserAddressInput#

Structure for a user's physical address.

country
String
The country.
province
String
The state or province.
city
String
The city.
postalCode
String
The postal code.
line1
String
The first line of the address.
line2
String
The second line of the address.

UserInfoInput#

Comprehensive structure for user information, used for creating or updating users.

did
String
The user's DID.
pk
String
The user's public key.
role
String
The user's assigned role.
avatar
String
URL to the user's avatar.
fullName
String
The user's full name.
email
String
The user's email address.
approved
Boolean
Whether the user's account is approved.
remark
String
An administrative remark about the user.
extra
Any
Extra metadata in JSON format.
tags
[TagInput!]
A list of tags to associate with the user.
address
UserAddressInput
The user's physical address.

UserQueryInput#

Structure for filtering and querying users.

role
String
Filter users by role.
approved
Boolean
Filter users by approval status.
search
String
A search term to match against user fields.
tags
[Uint32!]
Filter users by associated tag IDs.
includeTags
Boolean
Whether to include tag details in the response.
includeUserSessions
Boolean
Whether to include session details in the response.

UserSessionQueryInput#

Structure for querying user sessions.

userDid
String
Filter sessions by user DID.
visitorId
String
Filter sessions by visitor ID.
appPid
String
Filter sessions by application PID.
status
String
Filter sessions by status (e.g., 'active').
includeUser
Boolean
Whether to include user details in the response.

WAFPolicyInput#

Structure for Web Application Firewall (WAF) configuration.

enabled
Boolean
Whether the WAF is enabled.
mode
String
The operational mode of the WAF (e.g., 'detection', 'blocking').
inboundAnomalyScoreThreshold
Uint32
The anomaly score threshold for inbound traffic.
outboundAnomalyScoreThreshold
Uint32
The anomaly score threshold for outbound traffic.
logLevel
Uint32
The logging level for WAF events.

WebHookParamInput#

Structure for defining a parameter for a webhook.

name
String
The name of the parameter.
description
String
A description of the parameter.
required
Boolean
Whether the parameter is required.
defaultValue
String
The default value for the parameter.
value
String
The current value of the parameter.
type
String
The data type of the parameter (e.g., 'string').

WebhookEndpointStateInput#

Structure for creating or updating a webhook endpoint.

url
String
The URL to which webhook payloads will be sent.
description
String
A description of the webhook endpoint.
enabledEvents
[EnableEventInput!]
A list of events that this endpoint subscribes to.
status
String
The status of the endpoint (e.g., 'enabled', 'disabled').
Publishing & Projects
Advanced Usage