Add Stacks Blockchain API reference section#1845
Merged
Merged
Conversation
Migrate the Stacks Blockchain API prose documentation from the Hiro docs
repo (hiro-docs/content/docs/en/apis/stacks-blockchain-api/) into the
Stacks.co reference section. This is the indexed REST API hosted by Hiro
at api.hiro.so — the most-used API for Stacks developers — which
previously had no presence on Stacks.co.
What's added:
- 6 prose pages: overview, usage, architecture, pagination, nonce
handling, and requesting proofs
- Architecture diagram SVG asset
- OpenAPI spec YAML block in SUMMARY.md referencing the spec slug
"stacks-blockchain-api"
- Cross-link from the Stacks Node RPC README to the new section
The new section sits between "Stacks Node RPC" and "Stacks Mesh API" in
the reference sidebar, matching the existing API README patterns (hint
blocks, details/summary, OpenAPI spec link).
Source content was converted from Hiro's MDX format to GitBook markdown:
- :::callout → {% hint style="info" %}...{% endhint %}
- ```terminal / ```console -c → ```bash
- <span className="font-bold"> → **bold**
- Frontmatter stripped to description-only
- Internal links converted to relative paths
Manual steps required before this fully works:
1. Register the OpenAPI spec in GitBook. The YAML block in SUMMARY.md
references `spec: stacks-blockchain-api`, which must be registered at
the GitBook organization level. It cannot be created through Git
alone. Options:
a) GitBook CLI:
npx @gitbook/cli@latest openapi publish \
--spec stacks-blockchain-api \
--organization <ORG_ID> \
https://raw.githubusercontent.com/hirosystems/stacks-blockchain-api/master/openapi.yaml
b) GitBook API (POST /v1/orgs/<ORG_ID>/openapi)
c) GitBook web dashboard under the org's OpenAPI settings
Once registered by URL, GitBook polls it every 6 hours for updates.
2. The spec may need dereferencing before upload if it contains $ref
pointers that GitBook can't resolve. Hiro's build uses
@apidevtools/swagger-parser for this. If GitBook rejects the raw
YAML, dereference it first and upload the resolved JSON.
3. For ongoing maintenance, the CLI publish command can be added to a
GitHub Action so the spec stays in sync when the upstream
openapi.yaml changes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Broken links (architecture.md): - Replace dead rosetta-api.org URL with Mesh specifications GitHub repo - Remove dead docs.stacks.co/clarity/example-contracts/bns link (404) - Update blockstack/stacks-blockchain GitHub URL to canonical stacks-network/stacks-core (eliminates two-hop redirect chain) Typos carried from Hiro source: - nonce-handling.md: "the's" → "there's" - pagination.md: "items return" → "items returned" - requesting-proofs.md: "confirmation" → "confirmations" - requesting-proofs.md: "Merkel" → "Merkle" Orphaned repo paths (architecture.md): - Convert bare /src/api/routes, /src/event-stream, /docs/openapi.yaml into clickable GitHub links to hirosystems/stacks-blockchain-api README.md: - Remove office hours / addevent.com references (no longer offered) - Split combined warning hint into separate rate-limit warning and Discord support info hint usage.md: - Promote h3 subheadings (Base URL, Making requests, Authentication) to h2 to fix heading hierarchy (h1 → h2, not h1 → h3) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The file lives at the repo root (openapi.yaml), not under docs/. The previous link to /blob/master/docs/openapi.yaml returned 404. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Update the spec slug from `stacks-blockchain-api` to `stacks-blockchain-api-dereferenced` to match the spec already registered in GitBook (last updated ~2 months ago). This avoids needing a new spec registration and lets us test the integration immediately. Can be updated to the latest version if needed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- README: rewrite intro to explain what the API is, how it extends
Node RPC, who maintains it, and how it relates to other Stacks APIs
- usage: normalize "Stacks API" → "Stacks Blockchain API" for
consistency across the section; fix "api-key" → "API key"
- architecture: correct inaccurate claim that the API implements
Rosetta/Mesh (it was removed; replaced by standalone Mesh API);
add repo link to Development Setup for context
- pagination: remove misleading empty object {} from sample JSON
- nonce-handling: fix grammar "For all transactions go through" →
"For all transactions to go through"
- requesting-proofs: fix wording "endpoints will request the proof" →
"endpoints return the proof"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
wileyj
reviewed
Mar 20, 2026
wileyj
reviewed
Mar 20, 2026
wileyj
reviewed
Mar 20, 2026
Contributor
wileyj
left a comment
wileyj
left a comment
There was a problem hiding this comment.
overall lgtm - one small nit about the testnet api link
rafa-stacks
reviewed
Mar 20, 2026
rafa-stacks
left a comment
rafa-stacks
left a comment
There was a problem hiding this comment.
Just a couple comments but overall LGTM! Thanks Alexis. We'll need to eventually update the architecture diagram, expand some of the text and also include the full API reference in this repo too, but this is a great initial PR
Contributor
I do think it's possible to render openapi yml directly - i'm pretty sure it's done that way for stacks-core openapi |
- Use mainnet API URL with real principal in nonce example (wileyj) - Remove "Express.js" from routes reference (rafa-stacks) - Update stale docs link to docs.stacks.co (rafa-stacks) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
good on my end - i'll defer to @rafa-stacks to verify, but i think ti's good to merge |
|
I tried approving but I don't have repo write permissions so it won't let me. LGTM |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the Stacks Blockchain API — the most widely used API for Stacks developers — to the Stacks.co reference section. This is the indexed REST API hosted by Hiro at
api.hiro.so, which previously had no dedicated presence on Stacks.co despite being the primary API most developers interact with. Adding it here means the full reference spec is co-located alongside the Node RPC, Mesh, and Bridge APIs.This PR was co-authored with Claude Code for the initial migration and conversion work. All content was manually reviewed, revised, and tested by @alexis-stacks prior to opening this PR — including a full manual pass in the GitBook live preview to confirm that all pages load, render correctly, and display as expected. The OpenAPI spec registration in GitBook was handled manually and confirmed working. Text revisions throughout were made collaboratively and approved before inclusion.
What's included
6 new prose pages under
docs/reference/api/stacks-blockchain-api/:proof=0parameterModified files:
stacks-blockchain-api-dereferencedspec already registered in GitBookAssets:
.gitbook/assets/Migration details
Source content was migrated from the Hiro docs repo and converted from MDX to GitBook markdown:
:::callout→{% hint %}blocks```terminal/```console -c→```bash<span className="font-bold">→**bold**description:onlyPost-migration fixes
blockstack/stacks-blockchainGitHub URL)/docs/openapi.yaml→ root-levelopenapi.yaml)