Complete API reference for programmatic access to BTQ documentation — REST endpoints, search, AI Q&A, and discovery

AI Integration

BTQ Core documentation exposes a full API for AI agents, scripts, and external services. Every endpoint is auto-generated from the documentation source — add a new .mdx page and it appears everywhere automatically.

All endpoints below use https://docs.bitcoinquantum.com as the base URL. Replace with your deployment URL.

Quick Start

The fastest way for an agent to answer a question about BTQ:

curl -X POST https://docs.bitcoinquantum.com/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "How does Dilithium compare to ECDSA?"}'

{
  "answer": "Dilithium signatures are larger than ECDSA (2420 bytes vs 72 bytes) but provide quantum resistance...",
  "sources": [
    { "title": "Dilithium Overview", "url": "/dilithium/overview" },
    { "title": "Quantum Threat", "url": "/concepts/quantum-threat" }
  ],
  "question": "How does Dilithium compare to ECDSA?"
}

API Reference

`POST /api/ask` — Ask a Question

Submit a natural-language question and receive an AI-generated answer grounded in the documentation, with source citations.

Retrieval uses a BM25 + semantic hybrid pipeline (BGE-small-en-v1.5, 384-dim local embeddings) fused with Reciprocal Rank Fusion — both exact-term and conceptual queries return accurate results.

Request body:

Field	Type	Required	Description
`question`	string	Yes	The question to answer (max 1000 characters)

curl -X POST https://docs.bitcoinquantum.com/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "What opcodes does BTQ add for Dilithium?"}'

Response 200:

{
  "answer": "BTQ Core adds two new opcodes: OP_CHECKSIGDILITHIUM (0xbb) and OP_CHECKSIGDILITHIUMVERIFY (0xbc), plus OP_DILITHIUM_PUBKEY as a marker...",
  "sources": [
    { "title": "New Opcodes", "url": "/dilithium/opcodes" }
  ],
  "question": "What opcodes does BTQ add for Dilithium?"
}

Response 429 (rate limited):

{ "error": "Rate limit exceeded", "retry_after_ms": 42000 }

Rate limiting: 20 requests per minute per IP by default. Configurable via ASK_RATE_LIMIT and ASK_RATE_WINDOW_MS.

Trusted callers (e.g. a self-hosted agent) can bypass rate limiting by setting the x-agent-key header to a shared secret configured via AGENT_API_KEY on the server:

curl -X POST https://docs.bitcoinquantum.com/api/ask \
  -H "Content-Type: application/json" \
  -H "x-agent-key: your-secret-key" \
  -d '{"question": "What is the BTQ block time?"}'

Error responses:

Status	Reason
`400`	Missing or invalid `question` field, or body is not valid JSON
`429`	Rate limit exceeded
`500`	Server error (e.g. OpenAI API failure)

`POST /api/chat` — Multi-Turn Chat

Streaming multi-turn conversation grounded in the documentation. Uses the same retrieval pipeline as /api/ask but supports message history and returns a streaming response.

Request body:

Field	Type	Required	Description
`messages`	array	Yes	Conversation history (max 20 messages, Vercel AI SDK `UIMessage` format)

curl -X POST https://docs.bitcoinquantum.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "parts": [{ "type": "text", "text": "How do I install BTQ Core?" }] }
    ]
  }'

Returns a streaming response in the Vercel AI SDK data stream protocol. Use the @ai-sdk/react useChat hook to consume it from a browser, or parse the stream directly for server-side usage.

Rate limiting: 20 requests per minute per IP by default. Configurable via CHAT_RATE_LIMIT and CHAT_RATE_WINDOW_MS.

For single-turn Q&A from an agent or script, prefer POST /api/ask — it returns a simple JSON response and includes source citations.

`GET /api/docs` — Page Index (JSON)

Returns metadata for every documentation page. Use this for programmatic discovery.

curl https://docs.bitcoinquantum.com/api/docs

{
  "pages": [
    {
      "title": "BTQ Core Documentation",
      "description": "The quantum-resistant Bitcoin fork with Dilithium integration",
      "url": "/",
      "markdown_url": "/llms.mdx/",
      "toc": [
        { "title": "Overview", "url": "#overview", "depth": 2 }
      ]
    },
    {
      "title": "Dilithium Overview",
      "description": "Understanding post-quantum cryptography in BTQ",
      "url": "/dilithium/overview",
      "markdown_url": "/llms.mdx/dilithium/overview",
      "toc": [...]
    }
  ]
}

Each page object includes:

Field	Type	Description
`title`	string	Page title
`description`	string \| null	Short description from frontmatter
`url`	string	Page URL path
`markdown_url`	string	Direct link to the markdown content
`toc`	array	Table of contents (headings with depth and anchor)

`GET /api/docs/[...slug]` — Single Page (JSON)

Returns full structured content for one page.

curl https://docs.bitcoinquantum.com/api/docs/dilithium/overview

{
  "title": "Dilithium Overview",
  "description": "Understanding post-quantum cryptography in BTQ",
  "url": "/dilithium/overview",
  "toc": [...],
  "content": "# Dilithium Overview\n\nDilithium is a lattice-based digital signature scheme...",
  "structuredData": {
    "headings": [
      { "id": "overview", "content": "Dilithium Overview" }
    ],
    "contents": [
      { "heading": "overview", "content": "Dilithium is a lattice-based..." }
    ]
  }
}

Field	Type	Description
`title`	string	Page title
`description`	string \| null	Short description
`url`	string	Page URL path
`toc`	array	Table of contents
`content`	string	Full page content as processed markdown
`structuredData`	object	Headings and content sections (useful for chunked RAG)

Returns 404 if the slug does not match any page.

`GET /api/search` — Full-Text Search

Orama-powered full-text search across all documentation.

curl "https://docs.bitcoinquantum.com/api/search?query=dilithium+signature+size"

Returns ranked search results with matched content snippets. Query parameter is query.

Markdown Endpoints

These endpoints return raw processed markdown — ideal for feeding directly into an LLM context window.

`GET /llms.txt` — Documentation Index

A lightweight text index of all pages with titles, URLs, and descriptions.

curl https://docs.bitcoinquantum.com/llms.txt

# Documentation

- [BTQ Core Documentation](/): The quantum-resistant Bitcoin fork with Dilithium integration
- [Installation](/getting-started/installation): Build and run BTQ Core
- [Dilithium Overview](/dilithium/overview): Understanding post-quantum cryptography
...

`GET /llms-full.txt` — Full Documentation Dump

All documentation pages concatenated into a single response.

curl https://docs.bitcoinquantum.com/llms-full.txt

Returns the entire corpus. For large doc sites, prefer fetching individual pages.

`GET /docs/[path].mdx` — Single Page Markdown

Fetch any page as processed markdown using its URL path with .mdx appended.

curl https://docs.bitcoinquantum.com/docs/dilithium/overview.mdx
curl https://docs.bitcoinquantum.com/docs/getting-started/installation.mdx

Discovery

`GET /sitemap.xml`

Standard XML sitemap listing every documentation page. Auto-generated from the content source.

curl https://docs.bitcoinquantum.com/sitemap.xml

`GET /robots.txt`

Points crawlers and agents to the sitemap.

curl https://docs.bitcoinquantum.com/robots.txt

Agent Workflow

The recommended pattern for an AI agent consuming these docs:

# Ask directly — retrieval, grounding, and citation handled server-side
curl -X POST https://docs.bitcoinquantum.com/api/ask \
  -H "Content-Type: application/json" \
  -H "x-agent-key: your-secret-key" \
  -d '{"question": "How do I migrate an existing Bitcoin wallet to BTQ?"}'

If you need more control over retrieval (e.g. building your own RAG pipeline):

Discover — Fetch /api/docs to get the full page index
Search — Use /api/search?query=... to find candidate pages
Read — Fetch individual pages via /api/docs/[slug] (JSON) or /docs/[path].mdx (markdown)

# List all pages
curl https://docs.bitcoinquantum.com/api/docs | jq '.pages[].title'

# Search for a topic
curl "https://docs.bitcoinquantum.com/api/search?query=wallet+migration"

# Read a specific page
curl https://docs.bitcoinquantum.com/api/docs/wallet/basics | jq '.content'

Usage Examples

Python

import requests

BASE = "https://docs.bitcoinquantum.com"
AGENT_KEY = "your-secret-key"  # optional, bypasses rate limit

resp = requests.post(
    f"{BASE}/api/ask",
    json={"question": "What is the signature size for Dilithium?"},
    headers={"x-agent-key": AGENT_KEY},
)
data = resp.json()
print(data["answer"])
for src in data["sources"]:
    print(f"  - {src['title']}: {BASE}{src['url']}")

TypeScript / Node.js

const BASE = "https://docs.bitcoinquantum.com";

// Ask a question
const res = await fetch(`${BASE}/api/ask`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-agent-key": process.env.BTQ_DOCS_AGENT_KEY ?? "",
  },
  body: JSON.stringify({ question: "How do I install BTQ Core?" }),
});
const { answer, sources } = await res.json();

// Browse the full page index
const { pages } = await fetch(`${BASE}/api/docs`).then(r => r.json());

cURL — Browse and Read

# List all pages
curl -s https://docs.bitcoinquantum.com/api/docs | jq '.pages[] | {title, url}'

# Read a page as JSON (includes TOC and structured data)
curl -s https://docs.bitcoinquantum.com/api/docs/concepts/quantum-threat | jq

# Read a page as raw markdown
curl https://docs.bitcoinquantum.com/docs/concepts/quantum-threat.mdx

Page Actions UI

Every documentation page includes interactive buttons:

Action	Description
Copy Markdown	Copies the page content as markdown to your clipboard
Open in ChatGPT	Opens ChatGPT with a prompt to read the page
Open in Claude	Opens Claude with a prompt to read the page
Open in Scira AI	Opens Scira AI with the page context
Open in T3 Chat	Opens T3 Chat with the page context
GitHub	View the source `.mdx` file on GitHub

Rate Limits

Endpoint	Default limit	Window	Env variables
`/api/ask`	20 req/min	60s	`ASK_RATE_LIMIT`, `ASK_RATE_WINDOW_MS`
`/api/chat`	20 req/min	60s	`CHAT_RATE_LIMIT`, `CHAT_RATE_WINDOW_MS`

All other endpoints (/api/docs, /api/search, markdown endpoints) are not rate limited.

Trusted callers bypass /api/ask rate limiting via the x-agent-key header (see above). When rate limited, the response includes a Retry-After header indicating when to retry.

Adding Documentation

When you add new pages, they appear in all endpoints automatically:

Create a .mdx file in content/docs/
Add frontmatter with title and description
Add the page to the relevant meta.json for navigation
Run yarn embeddings to regenerate the semantic search index

No API configuration changes are needed. All endpoints derive from the same source.getPages() call. Remember to regenerate embeddings.json after content changes — retrieval quality degrades if the index is stale.

Endpoint Summary

Endpoint	Method	Returns	Use case
`/api/ask`	POST	JSON (answer + sources)	Single-turn Q&A with AI answer
`/api/chat`	POST	Stream	Multi-turn conversational chat
`/api/docs`	GET	JSON (page index)	Browse all pages with metadata
`/api/docs/[slug]`	GET	JSON (full page)	Read one page as structured JSON
`/api/search`	GET	JSON (search results)	Full-text search
`/llms.txt`	GET	Text	Lightweight page index
`/llms-full.txt`	GET	Text	Full documentation dump
`/docs/[path].mdx`	GET	Markdown	Single page as raw markdown
`/sitemap.xml`	GET	XML	Standard sitemap for crawlers
`/robots.txt`	GET	Text	Crawler directives

AI Integration

On this page