Agent integration guide

This is the orchestration recipe for an autonomous agent working against the HANK documentation corpus: how to chain the platform’s real machine surfaces into a discover → search → retrieve → ground → cite loop, and — for an authoring agent — publish back through review. It deliberately does NOT repeat the raw call mechanics: authentication, the stable error-code catalog, and rate-limit backoff all live in the API quickstart, and the full API reference documents every endpoint and schema.

Two authenticated surfaces back the loop — a JSON-RPC Model Context Protocol server at https://docs.hank.ai/mcp and a bearer REST API at https://docs.hank.ai/api/v1 — alongside a handful of anonymous public read endpoints (/llms.txt, /api/structure, /api/search, /api/ask, and the per-page .md twin). Every read surface serves PUBLIC, published content ONLY: internal or draft topics never appear, regardless of any header you send.

Start at the manifest

Begin every run at /llms.txt — the curated, machine-readable index. Its Programmatic access section names every surface in this guide (Ask AI, MCP, structure, full corpus, the REST publish path), then one section per public product links each topic at its raw-markdown .md URL. For one-shot grounding, /llms-full.txt returns the ENTIRE public corpus concatenated as raw markdown — every published topic plus the latest public release notes per product — each block delimited by a <!-- source: … --> comment so you can attribute and link back every passage.

curl https://docs.hank.ai/llms.txt          # the curated index + capabilities
curl https://docs.hank.ai/llms-full.txt     # the entire public corpus in one fetch

Discover the tree

Never guess slugs — learn the real ones first. GET https://docs.hank.ai/api/structure returns the public product → manual → topic tree (slugs + titles only). The MCP list_docs tool returns the same tree and optionally filters to one product. Feed the slugs you find straight into get_page / get_section or the .md twin.

curl https://docs.hank.ai/api/structure

Search for topics

GET https://docs.hank.ai/api/search?q=… runs a hybrid keyword + semantic search (so a query that is semantically related but does not keyword-match still surfaces). The response is a page envelope — read total and hasMore, and advance ?offset by ?limit, to walk every match. Scope to one product with ?product=<slug>, or restrict the corpus with ?kind=topic / ?kind=changelog.

curl "https://docs.hank.ai/api/search?q=rate+limits&product=hank-codes&limit=10&offset=0"

{
  "results": [
    {
      "kind": "topic",
      "title": "Rate limits",
      "productSlug": "hank-codes",
      "manualSlug": "getting-started",
      "topicSlug": "rate-limits",
      "excerptHtml": "How request quotas work."
    }
  ],
  "total": 3,
  "hasMore": false
}

The MCP search_docs tool takes the same query / limit / offset / product / kind arguments and returns count, total, hasMore, and hits. A changelog hit is self-describing: it carries the entry date/version and a ready-to-follow path deep-link to /<product>/changelog#<anchor> — never a fabricated topic URL.

Retrieve clean context

Pull token-efficient Markdown into the model context — not scraped HTML. Three ways, cheapest first:

• get_section (MCP) — ONE anchored section (its heading, plain-text content, and deep-link href) by product/manual/topic slug plus a heading anchor. The empty anchor selects the lead/title section. Cheapest: pull only the section you need.
• get_page (MCP) — the whole page (title, excerpt, MDX body) when you need the full topic.
• The .md twin — GET /hank-codes/getting-started/welcome/index.md (pattern: /<product>/<manual>/<topic>/index.md) returns the raw text/markdown body. It is the <link rel="alternate" type="text/markdown"> advertised in every topic page’s head, so a crawler discovers it without scraping. Anonymous for public topics.

curl https://docs.hank.ai/hank-codes/getting-started/welcome/index.md

Ground answers

When you need a grounded answer rather than raw context, POST https://docs.hank.ai/api/ask is the platform’s own retrieval-augmented (RAG) endpoint. Send { "question": "…" } and get back an answer, its citations, and a refused flag.

curl -X POST https://docs.hank.ai/api/ask \
  -H "Content-Type: application/json" \
  -d '{ "question": "How do rate limits work?" }'

{
  "answer": "Write responses carry X-RateLimit-* headers; a 429 includes Retry-After…",
  "citations": [
    {
      "kind": "topic",
      "title": "Rate limits",
      "productSlug": "hank-codes",
      "manualSlug": "getting-started",
      "topicSlug": "rate-limits",
      "anchor": "",
      "snippet": "How request quotas work."
    }
  ],
  "refused": false
}

Cite your sources

Always cite the canonical URL a human reader lands on, so an answer is verifiable. Build it from the citation slugs: a topic citation maps to /<product>/<manual>/<topic> (append #<anchor> for the exact heading); a changelog citation maps to /<product>/changelog#<anchor>. The .md twin shares that path — just drop the trailing /index.md to get the page link.

// citation = one entry from the /api/ask `citations` array (or an MCP hit)
const path =
  citation.kind === "changelog"
    ? "/" + citation.productSlug + "/changelog"
    : "/" + citation.productSlug + "/" + citation.manualSlug + "/" + citation.topicSlug;
const url = "https://docs.hank.ai" + path + (citation.anchor ? "#" + citation.anchor : "");

Authoring agents

A publishing agent writes through the MCP upsert_topic tool or POST https://docs.hank.ai/api/v1/topics/upsert. Both are idempotent: key on a stable sourceKey and a re-run UPDATES the same topic instead of forking a duplicate — safe to replay across runs. See the quickstart for the full body schema, the publish pipeline, and the error codes.

The agent-loop concern is the response: a bot/agent write is ALWAYS force-pended to a pending status — it never auto-publishes to the public site. Read back the returned status and self-correct from it.

{ "slug": "rate-limits", "status": "pending", "createdByBot": true, "created": false }

Be a good citizen

• Back off on writes. Write responses carry X-RateLimit-Limit / -Remaining / -Reset; over the quota the API returns 429 with Retry-After. Honor it — the quickstart shows the backoff loop. GET reads are not write-rate-limited; Ask-AI has its own per-caller cap.
• Prefer cached reads. Lean on /llms.txt, /llms-full.txt, and the .md twins (all edge-cached) over re-deriving the corpus on every turn.
• Use the right credential. The public read surfaces above need no token. The MCP tools and the /api/v1 write path require a Hank-issued identity with the hank-docs scope — see the quickstart for how to obtain and send it.

Next steps

• Get a token and learn the call mechanics in the API quickstart.
• Browse every endpoint and schema in the API reference.
• Generate a client from the OpenAPI 3.1 document.
• Track releases in the changelog.