secondlayer
.md

Instance API

Discovery and batch reads, plus the catalog, archive check and node reads of a self-hosted instance. Envelope and cursors are in REST conventions; running an instance is Self-host.

Surface discovery

GET/v1
Open .md

Lists the public read surfaces on this instance, where this document lives, the list envelope shape, and the cursor format. A starting point for an agent that has only the base URL.

Returns

The API discovery object.

  • 200The surfaces this instance serves
  • 401This bind requires the instance token, and it was missing or wrong

Batch public reads

POST/v1/batch
Open .md

Up to 10 GET reads under /v1/index/, /v1/subgraphs, /v1/streams/ and /v1/contracts in one round trip. Items run in parallel through the full app, so auth, rate limits and retention apply per item; the request's Authorization header is forwarded to every item. Results come back in request order, each with its own HTTP status and JSON body. A refused or failed item does not fail the batch.

Body

requestsarray of objectrequired#

The reads to run, 1 to 10.

Returns

The Batch response object.

  • 200One result per request, in request order
  • 400The body is not { requests: [...] }, requests is empty, or it holds more than 10 items (VALIDATION_ERROR)
  • 401This bind requires the instance token, and it was missing or wrong

This document

GET/v1/openapi.json
Open .md

The OpenAPI 3.1 description of this instance, as JSON. It describes the instance's own mode: a self-hosted instance includes the /api write plane, the hosted archive leaves it out.

Returns

  • 200The OpenAPI document
  • 401This bind requires the instance token, and it was missing or wrong

Local instance catalog

GET/v1/instanceSelf-hosted instances
Open .md

What this instance is and holds: its mode and network, the feature manifest, the history it claims, and the subgraphs and webhooks deployed on it. No signup or pricing, ever.

Returns

The Instance catalog object.

  • 200The catalog. If the database is unreachable, lists come back empty rather than failing.
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong

Default feature manifest

GET/v1/instance/featuresSelf-hosted instances
Open .md

Which modules this instance runs, including which protocol decoders are on.

Returns

The Instance feature manifest object.

  • 200The declared mode and feature manifest.
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong

Operational vitals

GET/v1/instance/metricsSelf-hosted instances
Open .md

Process uptime, database size, the last 24 hours of webhook delivery outcomes, and rows processed per hour. A value that can't be measured comes back null instead of failing the request.

Returns

The Instance metrics object.

  • 200Current vitals.
  • 400A parameter, filter, cursor or body field was refused; code says which
  • 401This bind requires the instance token, and it was missing or wrong

Verify this instance against a signed archive

POST/v1/archive/verify
Open .md

Compares identity digests of this instance's blocks, transactions and events against the range digests in a signed archive manifest. Read-only: the instance fetches the manifest, nothing is uploaded. Semantic replay (--deep) is CLI only. Without from_block or to_block, a manifest with more than 40 matching ranges is refused with 400. A missing key, an unreachable manifest, a failed signature or no matching digests answer 200 unanchored with a reason, never clean.

Body

againststring · urirequired#

https URL of latest.json or a snapshot manifest. Local paths and plain http are refused.

targetstring#

raw (default) or all check blocks, transactions and events. decode:<name> and subgraph:<name> parse, but only raw datasets have digests, so they answer unanchored with no digests.

from_blockinteger#

First height to check. Needed, with or without to_block, when the manifest has more than 40 matching ranges.

to_blockinteger#

Last height to check. Must be at least from_block.

insecureboolean#

Compare even when the signature does not verify. signature.verified stays false.

public_key_pemstring#

Archive signing key to verify with. Without it the instance uses ARCHIVE_SIGNING_PUBLIC_KEY (or STREAMS_SIGNING_PUBLIC_KEY); the hosted API also fetches the published key.

Returns

The Archive verification object.

  • 200The comparison, or unanchored with the reason it could not run
  • 400The body is not JSON (INVALID_JSON), against is missing or not https, a field has the wrong type, target is not recognised, to_block is below from_block, or more than 40 ranges matched without a height window (VALIDATION_ERROR)
  • 401This bind requires the instance token, and it was missing or wrong

Contract ABI from the local Stacks node

GET/api/node/contracts/{contract_id}/abiSelf-hosted instances
Open .md

Fetches the contract's interface from the Stacks node this instance follows (/v2/contracts/interface) and returns it unchanged. Nothing is cached. Self-hosted only; needs the instance token whenever one is set.

Path parameters

contract_idstringrequired#

Contract principal, <address>.<name>. A value without a . does not match the route and gets 404.

Returns

The Contract ABI object.

  • 200The contract's ABI as the node reports it
  • 401This bind requires the instance token, and it was missing or wrong
  • 404The node has no contract with that id, or the id has no .
  • 502The node could not be reached or answered with an error; error carries its message

The API discovery object

Object
Open .md

The public read surfaces and how to page them.

Returned by Surface discovery

Attributes

surfacesarray of objectrequired#

Each surface's name, base path, a one-line description, and its auth rule.

openapistringrequired#

Path of this OpenAPI document.

envelope_examplesobjectrequired#

An illustrative cursor-paginated list envelope.

cursor_formatstringrequired#

Index and Streams cursor format.

The Batch response object

Object
Open .md

The batch results.

Returned by Batch public reads

Attributes

resultsarray of objectrequired#

One entry per request, in order: the item's path, the HTTP status it got, and its JSON body. A path outside the allowed prefixes gets status 400; an item that throws gets status 500 with code INTERNAL_ERROR.

The Instance catalog object

Object
Open .md

What this instance is and holds.

Returned by Local instance catalog

Attributes

modeenum#

The mode the operator declared in INSTANCE_MODE.

3 possible values
ossplatformarchive
networkstring#

mainnet, testnet or devnet.

instance_idstring · nullable#

This instance's id, or null before first boot.

featuresobject#

Same manifest as /v1/instance/features.

scopeobject · nullable#

The history this instance claims: start_height, optional target_height, and how it was acquired (bootstrap.source is archive, genesis or import, with the archive manifest digest when restored). null on an instance older than the scope table.

subgraphsarray of object#

Deployed subgraphs: name, status, start_block, last_processed_block.

webhooksarray of object#

Webhooks: name, status, kind (chain).

consoleobject#

Console flags. Always false on a self-hosted instance.

The Instance feature manifest object

Object
Open .md

The declared mode and the modules this instance runs.

Returned by Default feature manifest

Attributes

modeenum#

The mode the operator declared in INSTANCE_MODE.

3 possible values
ossplatformarchive
featuresobject#

Module flags. protocolDatasets says which protocol decoders are on; signup, pricing and publicDirectory are always false here.

The Instance metrics object

Object
Open .md

Operational vitals.

Returned by Operational vitals

Attributes

uptime_sinteger#

Seconds since the API process started.

db_size_bytesinteger · nullable#

Postgres database size, or null if it can't be read.

deliveries_24hobject · nullable#

Webhook deliveries in the last 24 hours: total, failed (no status or 400+), and dlq (events currently dead-lettered).

rows_seriesarray of object#

Rows processed across all subgraphs, per hour over the last 24 hours: { t, rows }.

The Archive verification object

Object
Open .md

The outcome of an archive comparison.

Returned by Verify this instance against a signed archive

Attributes

statusenumrequired#

clean: every range matched. diverged: at least one did not. unanchored: the comparison could not be trusted or run; see reason.

3 possible values
cleandivergedunanchored
targetstringrequired#

The target that ran, normalised (raw, all, decode:<name>, subgraph:<name>).

againststringrequired#

The manifest URL, as sent.

signatureobjectrequired#

Whether the manifest signature verified, and why not when it did not.

coverageobject#

Lowest and highest height compared. Absent when nothing was compared.

rangesarray of objectrequired#

One row per compared range. status is match, digest-mismatch, count-mismatch, or missing when this instance has no rows there. Digests are null for an empty range.

reasonstring#

Why the result is unanchored: no public key, the fetch error, the signature failure, or no digests.

The Contract ABI object

Object
Open .md

A Clarity contract interface, exactly as the Stacks node's /v2/contracts/interface returns it.

Returned by Contract ABI from the local Stacks node

Attributes

functionsarray of object#

Every function: name, access (public, read_only or private), args and outputs.

variablesarray of object#

Data vars and constants: name, type, and access (variable or constant).

mapsarray of object#

Data maps: name, key type and value type.

fungible_tokensarray of object#

Fungible tokens the contract defines, by name.

non_fungible_tokensarray of object#

Non-fungible tokens the contract defines: name and type.

epochstring#

Stacks epoch the contract was deployed in, e.g. Epoch2_05.

clarity_versionstring#

Clarity version it was deployed with, e.g. Clarity1.

Edit on GitHub