> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/reference/api/stacks-node-rpc/stacker-db.md).
# Stacker DB
Endpoints for interacting with StackerDB instances.
## Get StackerDB chunk (latest version)
> Get the latest version of a chunk of data from a StackerDB instance.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/{slot_id}":{"get":{"summary":"Get StackerDB chunk (latest version)","tags":["StackerDB"],"operationId":"getStackerDbChunk","description":"Get the latest version of a chunk of data from a StackerDB instance.\n","parameters":[{"$ref":"#/components/parameters/standard-principal"},{"$ref":"#/components/parameters/contract-name"},{"name":"slot_id","in":"path","required":true,"description":"Slot ID (u32 range)","schema":{"type":"integer","minimum":0,"maximum":4294967295}}],"responses":{"200":{"description":"StackerDB chunk data","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"standard-principal":{"name":"principal","in":"path","required":true,"description":"Standard Stacks address (standard principal, not contract principal).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"$ref":"#/components/schemas/StandardPrincipal"}},"contract-name":{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}},"schemas":{"StandardPrincipal":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},"responses":{"BadRequest":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}
```
## Get StackerDB chunk (specific version)
> Get a specific version of a chunk of data from a StackerDB instance.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/{slot_id}/{slot_version}":{"get":{"summary":"Get StackerDB chunk (specific version)","tags":["StackerDB"],"operationId":"getStackerDbChunkVersioned","description":"Get a specific version of a chunk of data from a StackerDB instance.\n","parameters":[{"$ref":"#/components/parameters/standard-principal"},{"$ref":"#/components/parameters/contract-name"},{"name":"slot_id","in":"path","required":true,"description":"Slot ID (u32 range)","schema":{"type":"integer","minimum":0,"maximum":4294967295}},{"name":"slot_version","in":"path","required":true,"description":"Specific slot version (u32 range)","schema":{"type":"integer","minimum":0,"maximum":4294967295}}],"responses":{"200":{"description":"StackerDB chunk data","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"standard-principal":{"name":"principal","in":"path","required":true,"description":"Standard Stacks address (standard principal, not contract principal).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"$ref":"#/components/schemas/StandardPrincipal"}},"contract-name":{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}},"schemas":{"StandardPrincipal":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},"responses":{"BadRequest":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}
```
## Get StackerDB metadata
> Get metadata about a StackerDB instance, including slot information.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}":{"get":{"summary":"Get StackerDB metadata","tags":["StackerDB"],"operationId":"getStackerDbMetadata","description":"Get metadata about a StackerDB instance, including slot information.\n","parameters":[{"$ref":"#/components/parameters/standard-principal"},{"$ref":"#/components/parameters/contract-name"}],"responses":{"200":{"description":"StackerDB metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackerDbMetadata"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"standard-principal":{"name":"principal","in":"path","required":true,"description":"Standard Stacks address (standard principal, not contract principal).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"$ref":"#/components/schemas/StandardPrincipal"}},"contract-name":{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}},"schemas":{"StandardPrincipal":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41},"StackerDbMetadata":{"type":"array","items":{"type":"object","properties":{"slot_id":{"type":"integer","description":"Slot identifier (unique for each DB instance)"},"slot_version":{"type":"integer","description":"Slot version (a lamport clock)"},"data_hash":{"type":"string","description":"Data hash (hex, no 0x prefix)"},"signature":{"type":"string","description":"signature over the above (hex, no 0x prefix)"}}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}
```
## Write StackerDB chunk
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/chunks":{"post":{"summary":"Write StackerDB chunk","tags":["StackerDB"],"operationId":"postStackerDbChunk","description":"Write a chunk of data to a StackerDB instance.\n\nThe request body should contain a JSON object with the chunk data including\nslot_id, slot_version, signature, and hex-encoded data.\n\nThe response indicates whether the chunk was accepted, and if not, provides\ndetailed error information. Note that failed writes return HTTP 200 with\naccepted: false, not HTTP error codes.\n","parameters":[{"$ref":"#/components/parameters/standard-principal"},{"$ref":"#/components/parameters/contract-name"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackerDbChunkData"}}}},"responses":{"200":{"description":"Chunk submission result (both success and failure cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackerDbChunkAckData"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"standard-principal":{"name":"principal","in":"path","required":true,"description":"Standard Stacks address (standard principal, not contract principal).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"$ref":"#/components/schemas/StandardPrincipal"}},"contract-name":{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}},"schemas":{"StandardPrincipal":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41},"StackerDbChunkData":{"type":"object","required":["slot_id","slot_version","sig","data"],"properties":{"slot_id":{"type":"integer","minimum":0,"maximum":4294967295,"description":"Slot identifier (u32 range)"},"slot_version":{"type":"integer","minimum":0,"maximum":4294967295,"description":"Slot version (lamport clock, u32 range)"},"sig":{"type":"string","description":"Hex-encoded signature from the stacker","pattern":"^[0-9a-f]{130}$"},"data":{"type":"string","description":"Hex-encoded chunk data (must be even length)","pattern":"^([0-9a-f]{2})*$"}}},"StackerDbChunkAckData":{"type":"object","required":["accepted"],"properties":{"accepted":{"type":"boolean","description":"Whether the chunk was accepted"},"reason":{"type":["string","null"],"description":"JSON-encoded reason for rejection (only present when accepted is false)"},"metadata":{"type":["object","null"],"description":"Slot metadata (present on successful acceptance)","properties":{"slot_id":{"type":"integer","minimum":0,"description":"Slot identifier"},"slot_version":{"type":"integer","minimum":0,"description":"Slot version"},"data_hash":{"type":"string","description":"Hex-encoded SHA512/256 hash of the data","pattern":"^[0-9a-f]{64}$"},"signature":{"type":"string","description":"Hex-encoded signature","pattern":"^[0-9a-f]{130}$"}}},"code":{"type":["integer","null"],"description":"Error code (only present when accepted is false)"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}
```
## List StackerDB replicas
> Get a list of replicas for a StackerDB instance.
```json
{"openapi":"3.1.0","info":{"title":"Stacks 3.0+ RPC API","version":"1.0.0"},"tags":[{"name":"StackerDB","description":"Endpoints for interacting with StackerDB instances."}],"servers":[{"url":"http://localhost:20443","description":"Local Stacks Node"}],"security":[],"paths":{"/v2/stackerdb/{principal}/{contract_name}/replicas":{"get":{"summary":"List StackerDB replicas","tags":["StackerDB"],"operationId":"listStackerDbReplicas","description":"Get a list of replicas for a StackerDB instance.\n","parameters":[{"$ref":"#/components/parameters/standard-principal"},{"$ref":"#/components/parameters/contract-name"}],"responses":{"200":{"description":"List of StackerDB replicas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackerDbReplicas"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"standard-principal":{"name":"principal","in":"path","required":true,"description":"Standard Stacks address (standard principal, not contract principal).\nMust be 28-41 characters long using Stacks c32check format.\n","schema":{"$ref":"#/components/schemas/StandardPrincipal"}},"contract-name":{"name":"contract_name","in":"path","required":true,"description":"Contract name. Must start with a letter and can contain letters, numbers,\nhyphens, and underscores. Maximum length is 40 characters for new contracts.\nLegacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$","minLength":1,"maxLength":128}}},"schemas":{"StandardPrincipal":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41},"StackerDbReplicas":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string"},"port":{"type":"integer"},"public_key_hash":{"type":"string","description":"20-byte public key hash"}}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.stacks.co/reference/api/stacks-node-rpc/stacker-db.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.