Ctrlk
Quick LinksPlatform
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Stacker DB

Endpoints for interacting with StackerDB instances.

Get StackerDB chunk (latest version)

get
/v2/stackerdb/{principal}/{contract_name}/{slot_id}

Get the latest version of a chunk of data from a StackerDB instance.

Path parameters
principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
slot_idintegerRequired

Slot ID

Responses
200

StackerDB chunk data

application/octet-stream
string · binaryOptional
get/v2/stackerdb/{principal}/{contract_name}/{slot_id}
GET /v2/stackerdb/{principal}/{contract_name}/{slot_id} HTTP/1.1
Host: localhost:20443
Accept: */*

binary

Get StackerDB chunk (specific version)

get
/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}

Get a specific version of a chunk of data from a StackerDB instance.

Path parameters
principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
slot_idintegerRequired

Slot ID

slot_versionintegerRequired

Specific slot version

Responses
200

StackerDB chunk data

application/octet-stream
string · binaryOptional
get/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}
GET /v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version} HTTP/1.1
Host: localhost:20443
Accept: */*

binary

Get StackerDB metadata

get
/v2/stackerdb/{principal}/{contract_name}

Get metadata about a StackerDB instance, including slot information.

Path parameters
principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Responses
200

StackerDB metadata

application/json
slot_idintegerOptional

Slot identifier (unique for each DB instance)

slot_versionintegerOptional

Slot version (a lamport clock)

data_hashstringOptional

Data hash (hex, no 0x prefix)

signaturestringOptional

signature over the above (hex, no 0x prefix)

get/v2/stackerdb/{principal}/{contract_name}
GET /v2/stackerdb/{principal}/{contract_name} HTTP/1.1
Host: localhost:20443
Accept: */*

[
  {
    "slot_id": 0,
    "slot_version": 1,
    "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
]

Write StackerDB chunk

post
/v2/stackerdb/{principal}/{contract_name}/chunks

Write a chunk of data to a StackerDB instance.

The request body should contain a JSON object with the chunk data including slot_id, slot_version, signature, and hex-encoded data.

The response indicates whether the chunk was accepted, and if not, provides detailed error information. Note that failed writes return HTTP 200 with accepted: false, not HTTP error codes.

Path parameters
principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Body
slot_idintegerRequired

Slot identifier

slot_versionintegerRequired

Slot version (lamport clock)

sigstringRequired

Hex-encoded signature from the stacker

Pattern: ^[0-9a-f]{130}$
datastringRequired

Hex-encoded chunk data

Pattern: ^[0-9a-f]*$
Responses
200

Chunk submission result (both success and failure cases)

application/json
acceptedbooleanRequired

Whether the chunk was accepted

reasonstring · nullableOptional

JSON-encoded reason for rejection (only present when accepted is false)

codeinteger · nullableOptional

Error code (only present when accepted is false)

post/v2/stackerdb/{principal}/{contract_name}/chunks
POST /v2/stackerdb/{principal}/{contract_name}/chunks HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 195

{
  "slot_id": 1,
  "slot_version": 2,
  "sig": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01",
  "data": "deadbeefcafebabe"
}
{
  "accepted": true,
  "reason": null,
  "metadata": {
    "slot_id": 1,
    "slot_version": 2,
    "data_hash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "signature": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01"
  },
  "code": null
}

List StackerDB replicas

get
/v2/stackerdb/{principal}/{contract_name}/replicas

Get a list of replicas for a StackerDB instance.

Path parameters
principalstring · min: 28 · max: 170Required

Stacks address (28-41 characters) or a Contract identifier in format {address}.{contract_name} (e.g. SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info). Contract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-infoPattern: ^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$
contract_namestring · min: 1 · max: 128Required

Contract name. Must start with a letter and can contain letters, numbers, hyphens, and underscores. Maximum length is 40 characters for new contracts. Legacy contracts may have names up to 128 characters.

Example: get-infoPattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
Responses
200

List of StackerDB replicas

application/json
ipstringOptional
portintegerOptional
public_key_hashstringOptional

20-byte public key hash

get/v2/stackerdb/{principal}/{contract_name}/replicas
GET /v2/stackerdb/{principal}/{contract_name}/replicas HTTP/1.1
Host: localhost:20443
Accept: */*

[
  {
    "ip": "127.0.0.1",
    "port": 20444,
    "public_key_hash": "03abc123..."
  }
]
PreviousAtlas
NextModels

Last updated

Was this helpful?