API docs by Redocly

splinterd API (0.4.1)

Download OpenAPI specification:Download

REST API for the Splinter daemon

Biome

Routes supporting user management in Splinter applications. Optionally compiled.

Create new user with username and password credent

Create new user with username and password credentials

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
username
required
any

username of a new user

hashed_password
required
any

Hashed password to be used for user authentication

Responses

Request samples

Content type
application/json
{
  • "username": "alice@acme.com",
  • "hashed_password": "F4AABE0B40C9ABB8B6FD2EEACB39C965"
}

Response samples

Content type
application/json
{
  • "message": "User created successfully",
  • "data": {
    }
}

Authenticates a user with username and password cr

Authenticates a user with username and password credentials

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
username
required
any

username of user

hashed_password
required
any

Hashed password to be used for user authentication

Responses

Request samples

Content type
application/json
{
  • "username": "alice@acme.com",
  • "hashed_password": "8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b"
}

Response samples

Content type
application/json
{
  • "message": "Successful login",
  • "user_id": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4",
  • "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc",
  • "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
}

Removes access tokens associated with a user

Removes access tokens associated with a user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "message": "User successfully logged out"
}

Issues a new access token

Issues a new access token

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
refresh_token
required
any

a refresh token issues by biome

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
}

Response samples

Content type
application/json
{
  • "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
}

Verifies a user with username and password credent

Verifies a user with username and password credentials

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
username
required
any

username of user

hashed_password
required
any

Hashed password to be used for user authentication

Responses

Request samples

Content type
application/json
{
  • "username": "alice@acme.com",
  • "hashed_password": "8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b"
}

Response samples

Content type
application/json
{
  • "message": "Successful verification",
  • "user_id": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
}

Lists all users

Lists all users

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Fetch a user by ID

Fetch a user by ID

path Parameters
user_id
required
string
Example: f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4

ID of the user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "username": "alice@acme.com",
  • "user_id": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
}

Update a user

Update a user

path Parameters
user_id
required
string
Example: f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4

ID of the user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
username
required
any

Existing username of user

hashed_password
required
any

Hashed password to be used for user authentication

new_password
any

Hash of the new password to be used for user authentication

Array of objects (BiomeNewUserKey)

Responses

Request samples

Content type
application/json
{
  • "username": "alice@acme.com",
  • "hashed_password": "8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b"
}

Response samples

Content type
application/json
{
  • "message": "Credentials and key updated successfully",
  • "data": [
    ]
}

Delete a user

Delete a user

path Parameters
user_id
required
string
Example: f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4

ID of the user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "message": "User deleted successfully"
}

List keys of a user

List keys of a user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a key's display name

Update a key's display name

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
public_key
required
any

Public key

new_display_name
required
any

Updated display name for the key

Responses

Request samples

Content type
application/json
{
  • "public_key": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118",
  • "new_display_name": "Admin key pair"
}

Response samples

Content type
application/json
{
  • "message": "Key updated successfully"
}

Add a new key for user

Add a new key for user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
display_name
string

Display name for key

encrypted_private_key
string

Encrypted private key

public_key
string

Public key

user_id
string

Internal unique identifier for the user

Responses

Request samples

Content type
application/json
{
  • "display_name": "Biome Admin Key",
  • "encrypted_private_key": "XNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc",
  • "public_key": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118",
  • "user_id": "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
}

Response samples

Content type
application/json
{
  • "message": "Key added successfully",
  • "data": {
    }
}

Fetch key of a user

Fetch key of a user

path Parameters
public_key
required
string
Example: 026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118

Public key of the user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete key of a user

Delete key of a user

path Parameters
user_id
required
string
Example: f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4

ID of the user

public_key
required
string
Example: 026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118

Public key of the user

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "message": "User deleted successfully",
  • "data": {
    }
}

diagnostics

Used to check if server is successfully running

Used to check if server is successfully running

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "version": "0.4.1",
  • "node_id": "node-009",
  • "display_name": "Cargill Node 009",
  • "service_endpoint": "tcp://foo.bar.biz",
  • "network_endpoints": [
    ],
  • "advertised_endpoints": [
    ]
}

Proposals

Fetches a list of pending circuit proposals for this node

This endpoint can be used to view all of the circuit proposals that the node is a proposed member of. If a circuit management type is provided via the "management_type" query parameter, only circuit proposals that have the given circuit management type will be returned. If a node ID is provided via the "member" query parameter, only circuit proposals that have the given node as a member will be returned. If no filter is provided, all of the node's circuit proposals will be returned.

query Parameters
offset
integer
Default: 0

paging offset

limit
integer
Default: 100

maximum number of items to return (max 100)

management_type
string

Only show proposed circuits matching the given circuit management type

member
string

Only show proposed circuits that have a member with the given node ID

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Fetches a circuit proposal by the circuit's ID

This endpoint can be used to view a specific circuit proposal that the node is a proposed member of.

path Parameters
circuit_id
required
string

Circuit ID of the proposal to fetch

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "proposal_type": "Create",
  • "circuit_id": "01234-ABCDE",
  • "circuit_hash": "8ce518770b962429a953b10220905ac9adf86a855f0b085695f444edf991b8ca",
  • "circuit": {
    },
  • "votes": [
    ],
  • "requester": "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118",
  • "requester_node_id": "alpha-node-000"
}

Admin Service

Send circuit management payload in bytes to admin

Send circuit management payload in bytes to admin service

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "message": "DatabaseError({description})"
}

Register the handler for a circuit management type

Register the handler for a circuit management type

path Parameters
type
required
string

The circuit management type is the type of circuit the handler will manage

query Parameters
last
integer
Default: 0

A timestamp in milliseconds from the Unix Epoch, indicating the last received event.

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "circuit_management_type": "gameroom",
  • "error_reason": "string"
}

Circuits

Fetches a list of circuits that the node belongs to

This endpoint can be used to view all or some of the circuits that the node is a member of. If a node ID is provided via the "filter" query parameter, only circuits that have the given node ID as a member will be returned; if no filter is provided, all of the node's circuits will be returned.

query Parameters
offset
integer
Default: 0

paging offset

limit
integer
Default: 100

maximum number of items to return (max 100)

filter
string

Node ID that must be present in the returned circuits

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Fetches a circuit by its ID

This endpoint can be used to view a specific circuit that the node is a member of.

path Parameters
circuit_id
required
string

ID of the circuit to fetch

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "id": "01234-ABCDE",
  • "members": [
    ],
  • "roster": [
    ],
  • "management_type": "gameroom"
}

Splinter Registry

Add a node to the registry

This endpoint can be used to add a new node to the Splinter registry. The node must be valid (see the Splinter registry documentation for details on node validity).

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
identity
string
endpoints
Array of strings
display_name
string
keys
Array of strings
metadata
object

Responses

Request samples

Content type
application/json
{
  • "identity": "node-123123-asdf",
  • "endpoints": [
    ],
  • "display_name": "Cargill - Node 1",
  • "keys": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "message": "DatabaseError({description})"
}

List nodes in the registry

This endpoint can be used to view all or some of the nodes in the registry. If metadata filters are provided via the "filter" query parameter, only nodes that match the given filters will be returned. See the Splinter registry documentation for details on metadata filters.

query Parameters
offset
integer
Default: 0

paging offset

limit
integer
Default: 100

maximum number of items to return (max 100)

filter
string
Example: filter=%7B%22company%22%3A%5B%22%3D%22%2C%22Cargill%22%5D%7D

url-encodeded stringified JSON containing property filters on the node's metadata properties in the format {METADATA_PROPERTY:[{"operator":OPERATOR,"value":VALUE}]}

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Fetch a node in the registry by its identity

This endpoint can be used to view a specific nodes in the registry.

path Parameters
identity
required
string

identity of node to fetch

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add or replace a node in the registry

This endpoint can be used to add a new node to the registry, or replace an existing node. When replacing an existing node, the node identity cannot be changed. This action is idempotent.

path Parameters
identity
required
string

identity of node to add/replace

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Request Body schema: application/json
identity
string
endpoints
Array of strings
display_name
string
keys
Array of strings
metadata
object

Responses

Request samples

Content type
application/json
{
  • "identity": "node-123123-asdf",
  • "endpoints": [
    ],
  • "display_name": "Cargill - Node 1",
  • "keys": [
    ],
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "message": "DatabaseError({description})"
}

Delete a node from the registry

This endpoint can be used to remove a node from the registry.

path Parameters
identity
required
string

identity of node to delete

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "message": "DatabaseError({description})"
}

Scabbard

Submit a list of batches to the Scabbard service

This endpoint can be used to submit batches to a Scabbard service. The body of the request must be a list of valid Sabre batches. If the batches are submitted successfully, the response will contain a link for checking the status of the submitted batches.

path Parameters
circuit
required
string

Circuit the targeted service belongs to

service_id
required
string

ID of the targeted service

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
{
  • "link": "/scabbard/abcde-01234/ABCD/batch_statuses?ids=6ff35474a572087e08fd6a54d563bd8172951b363e5c9731f1a40a855e14bba45dac515364a08d8403f4fb5d4a206174b7f63c29e4f4e425dc71b95494b8a798"
}

Get the statuses of a list of batches

This endpoint can be used to check the status of one or more batches that were submitted to a Scabbard service. The IDs of the batches to check should be specified with the ids query parameter. The wait query parameter requests that the server wait for the given number of seconds for the batches to be committed; however, this wait time is not guaranteed.

path Parameters
circuit
required
string

Circuit the targeted service belongs to

service_id
required
string

ID of the targeted service

query Parameters
ids
required
string

Comma-separated list of batch IDs

wait
integer
Default: 300

Time (in seconds) to wait for batches to be committed. If not provided, the server will return the batch statuses immediately. If the parameter is provided without a value, the default time (300 seconds) will be used.

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of entries from a Scabbard service's state

This endpoint can be used to fetch a list of entries from a Scabbard service's state. The entries can be filtered using an address prefix provided with the prefix query parameter.

path Parameters
circuit
required
string

Circuit the targeted service belongs to

service_id
required
string

ID of the targeted service

query Parameters
prefix
string
Example: prefix=00ec01

An address prefix for filtering state entries. If no prefix is specified, all state entries will be returned.

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the value at an address in a Scabbard service's state

This endpoint can be used to fetch the value at a specific address in a Scabbard service's state.

path Parameters
circuit
required
string

Circuit the targeted service belongs to

service_id
required
string

ID of the targeted service

address
required
string
Example: 000000a87cb5eafdcca6a814e4add97c4b517d3c530c2f44b31d18e3b0c44298fc1c14

The address of the value to retrieve from state

header Parameters
SplinterProtocolVersion
integer
Example: 1

The protocol version which the client can understand. If not provided, the node will respond using its latest protocol version.

Responses

Response samples

Content type
application/json
[
  • 0
]