# StackerDB
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"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"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":[{"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":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"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}},{"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":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"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"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"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":[{"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":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"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}},{"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":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"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"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"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":[{"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":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"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}}],"responses":{"200":{"description":"StackerDB metadata","content":{"application/json":{"schema":{"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)"}}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"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"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"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":[{"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":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"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}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"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})*$"}}}}}},"responses":{"200":{"description":"Chunk submission result (both success and failure cases)","content":{"application/json":{"schema":{"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)"}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"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"},{"url":"https://api.mainnet.hiro.so","description":"Stacks Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Stacks Testnet API"}],"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":[{"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":{"type":"string","pattern":"^S[PTMN][0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26,39}$","minLength":28,"maxLength":41}},{"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}}],"responses":{"200":{"description":"List of StackerDB replicas","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string"},"port":{"type":"integer"},"public_key_hash":{"type":"string","description":"20-byte public key hash"}}}}}}},"400":{"description":"Bad request","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.stacks.co/reference/api/stacks-node-rpc/stackerdb.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.