Why Apiary/Blueprint HTML is hard for LLMs
Apiary renders its docs as a heavily JavaScript-driven single-page app. The actual content — endpoints, parameters, request/response bodies — is embedded in the DOM after JS execution, which means raw HTML fetched by an LLM is mostly script tags, not readable content. Even when rendered, the structure uses deeply nested divs with presentational class names rather than semantic markup.Here are the approaches ranked by impact:
1. Publish an OpenAPI/Swagger file (highest impact)
Convert the .apib Blueprint source to OpenAPI 3.0 YAML and host it at a predictable URL like /openapi.yaml. Tools like apib2swagger or Apiary's own export can do this. OpenAPI is structured, has a well-known schema, and LLMs are trained extensively on it — it's essentially a native format.
2. Link to the raw .apib source
API Blueprint is just annotated Markdown. If the raw .apib file is publicly accessible (e.g. in a GitHub repo), an LLM can read it directly and understand endpoints, parameters, and examples far better than from the rendered HTML.
3. Add an llms.txt file
An emerging convention (similar to robots.txt) where you place a plain-text or Markdown summary of your API at yourdomain.com/llms.txt. You control the content, so you can write it to be optimally structured for AI consumption.
4. Static pre-rendered HTML fallback
If you control the Apiary rendering pipeline, generate a static HTML version with proper semantic tags (<article>, <section>, <h2>, <code>) rather than relying on JavaScript to inject content. This also helps with SEO.
5. Structured <meta> and schema.org markup
Adding JSON-LD schema or well-labelled <header>/<section> tags around each endpoint group gives parsers anchors to navigate the document.
The single most impactful thing for Unmade specifically would be hosting an OpenAPI spec file — it would make the API immediately usable by LLMs, code generation tools, and Postman/Insomnia all at once.
Why Apiary/Blueprint HTML is hard for LLMs
Apiary renders its docs as a heavily JavaScript-driven single-page app. The actual content — endpoints, parameters, request/response bodies — is embedded in the DOM after JS execution, which means raw HTML fetched by an LLM is mostly script tags, not readable content. Even when rendered, the structure uses deeply nested divs with presentational class names rather than semantic markup.Here are the approaches ranked by impact:
1. Publish an OpenAPI/Swagger file (highest impact)
Convert the
.apibBlueprint source to OpenAPI 3.0 YAML and host it at a predictable URL like/openapi.yaml. Tools likeapib2swaggeror Apiary's own export can do this. OpenAPI is structured, has a well-known schema, and LLMs are trained extensively on it — it's essentially a native format.2. Link to the raw
.apibsourceAPI Blueprint is just annotated Markdown. If the raw
.apibfile is publicly accessible (e.g. in a GitHub repo), an LLM can read it directly and understand endpoints, parameters, and examples far better than from the rendered HTML.3. Add an
llms.txtfileAn emerging convention (similar to
robots.txt) where you place a plain-text or Markdown summary of your API atyourdomain.com/llms.txt. You control the content, so you can write it to be optimally structured for AI consumption.4. Static pre-rendered HTML fallback
If you control the Apiary rendering pipeline, generate a static HTML version with proper semantic tags (
<article>,<section>,<h2>,<code>) rather than relying on JavaScript to inject content. This also helps with SEO.5. Structured
<meta>and schema.org markupAdding JSON-LD schema or well-labelled
<header>/<section>tags around each endpoint group gives parsers anchors to navigate the document.The single most impactful thing for Unmade specifically would be hosting an OpenAPI spec file — it would make the API immediately usable by LLMs, code generation tools, and Postman/Insomnia all at once.