docs: update Stacks Blockchain API reference to latest OpenAPI spec (v3 endpoints)

[rafa-stacks]

What & why

Updates the Stacks Blockchain API documentation to match the latest OpenAPI spec, which restructured many endpoints (v1/v2 → v3) and added new endpoint groups. The docs had drifted from the spec, so this brings the reference tree back to 1:1 coverage and documents the new cursor pagination.

Changes

Spec source

• Repointed the fetch script (scripts/fetch-openapi-specs.mts) at the up-to-date stacks-blockchain-api repo and regenerated openapi/stacks-blockchain-api.json (82 endpoints, was 68).

Reference pages (English) — now match the spec exactly

• Added 42 new endpoint pages, including two brand-new groups:
  • Staking (11 — bonds, allowlists, registrations, signers)
  • Microblocks (3)
  • plus new v3 routes across Accounts, Transactions, Blocks, Faucets (BTC/sBTC), Proof of Transfer, Names (pricing), Mempool, Smart Contracts, and Stacking.
• Removed 28 pages for endpoints no longer in the spec (mostly legacy v1 accounts/blocks/transactions routes superseded by v2/v3).
• Deleted the empty Fees group (the Fees tag was dropped from the spec).
• Cleaned up 3 pre-existing dangling nav entries (info/pox-details, transactions/transaction-fee-priorities, transactions/dropped-mempool-transactions).

Content pages

• Removed the Requesting proofs page (EN + ES) and its nav entries.
• Rewrote the Pagination page to document cursor-based pagination (limit/cursor params; cursor.next/previous/current response shape; a walk-the-list example), with a note that legacy endpoints still use offset/limit. Grounded in the actual spec.

Verification

• Zero drift: documented pages match the 82 spec operations 1:1.
• Every meta.json entry ↔ file is consistent.
• fumadocs-mdx compiles cleanly; dev-server render check confirms new pages return 200 with correct titles/paths/groups, deleted pages 404, and the Pagination page renders correctly.

Reviewer notes

• Spanish docs not updated. content/docs/es/.../reference/ is a separately-maintained, already-divergent translation — scaffolding English content there would mix languages. The ES Pagination page also still describes offset pagination. Left for a proper translation pass.
• Generated titles are scaffold-quality (mechanically derived from the spec). A few sidebar labels read slightly oddly (e.g. "Regtest BTC tokens to address") and could use a light human polish.
• The new-files commit is unsigned — signing requires the hardware security key configured on this repo, which the automated tooling can't touch. Re-sign if branch protection requires it.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hiro-systems-docs	Ready	Preview	Jul 8, 2026 7:14pm