# 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.<br>

```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":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro 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":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"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","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"StackerDB chunk data","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"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.<br>

```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":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro 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":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"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","schema":{"type":"integer","minimum":0}},{"name":"slot_version","in":"path","required":true,"description":"Specific slot version","schema":{"type":"integer","minimum":0}}],"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.<br>

```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":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro 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":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"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.<br>

```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":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro 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":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"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,"description":"Slot identifier"},"slot_version":{"type":"integer","minimum":0,"description":"Slot version (lamport clock)"},"sig":{"type":"string","description":"Hex-encoded signature from the stacker","pattern":"^[0-9a-f]{130}$"},"data":{"type":"string","description":"Hex-encoded chunk data","pattern":"^[0-9a-f]*$"}}}}}},"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.<br>

```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":"Hiro Mainnet API"},{"url":"https://api.testnet.hiro.so","description":"Hiro 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":"Stacks address (28-41 characters) or a Contract identifier in format `{address}.{contract_name}`\n(e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`).\nContract names have a maximum length of 40 characters for new contracts. Legacy contracts may have names up to 128 characters.\n","schema":{"type":"string","pattern":"^([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})|([0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127})$","minLength":28,"maxLength":170}},{"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"}}}}}}}}}
```