Docs for AI agents

These docs are published for machines as well as people. Every page has a clean Markdown twin, the whole corpus is available as a single file, and the API has a complete machine-readable contract — so a coding agent can read the documentation properly instead of scraping rendered HTML and guessing at endpoint names.

The machine-readable surface

All four are static, public, and need no authentication or JavaScript.

llms.txt and llms-full.txt

llms.txt is a convention — a Markdown file at the root of a site that tells a language model what the site is and where the good parts are, in the same spirit as robots.txt for crawlers. It solves a specific problem: a model given a rendered docs site spends its context on navigation chrome, and a model given a sitemap has no idea which of 200 URLs matter.

curl -s https://ospulse.app/llms.txt

Ours contains a one-paragraph description of the platform, the API base URL and authentication scheme, a pointer to the OpenAPI document, and a flat list of every documentation page with its one-line description — each linking to that page's Markdown twin rather than its HTML.

# OSPulse
 
> OSPulse is a dependency drift and open-source supply-chain intelligence platform...
 
The REST API is at https://api.ospulse.app, versioned under /api/v1/, and authenticates
with `Authorization: Bearer {token}`. The machine-readable contract is at
https://ospulse.app/openapi.json (OpenAPI 3.0.1, 246 operations).
 
Every documentation page is available as Markdown by appending `index.md` to its URL.
 
## Documentation
 
- [Quickstart](https://ospulse.app/docs/quickstart/index.md): Make your first authenticated
  API call in under five minutes.
- [Authentication](https://ospulse.app/docs/authentication/index.md): Create, use, scope, and
  rotate API tokens.
...
 
## Optional
 
- [OpenAPI specification](https://ospulse.app/openapi.json): the full machine-readable API contract
- [Full documentation corpus](https://ospulse.app/llms-full.txt): every page inlined into one file

llms-full.txt is the same corpus with the content inlined, each page tagged with its source URL. Use it when you want the entire documentation set in one retrieval — building a local index, seeding a RAG store, or handing a long-context model everything at once.

Every page has a Markdown twin

Append index.md to any docs URL and you get the page as plain Markdown — headings, prose, and code fences, with the layout, navigation, and styling stripped out:

curl -s https://ospulse.app/docs/quickstart/index.md

This works for every page in the sidebar, and the twin is generated from the same source as the rendered page at build time, so it is never stale. Components become plain Markdown: steps become headings, callouts become blockquotes, and multi-language tabs become consecutive code blocks labelled with their languages.

For an agent, the practical consequence is that fetching documentation costs a fraction of the tokens and none of the parsing risk. Prefer index.md over the HTML page in every automated context.

The "Copy page" menu

Every docs page carries a Copy page control in its header, for when the human is the one moving context into an assistant:

The two "open in" actions deliberately pass a URL rather than pasting the page contents — the assistant fetches the current version, so a conversation started today does not carry a stale copy of the docs.

A prompt pattern that works

The failure mode with API documentation is not that a model cannot read it — it is that the model answers from a plausible-sounding memory of some other API instead. Anchor it explicitly, and forbid invention:

You are integrating with the OSPulse API.
 
Sources of truth, in priority order:
1. https://ospulse.app/openapi.json — the OpenAPI 3.0.1 contract. Every endpoint,
   parameter, and response schema is defined here.
2. https://ospulse.app/llms.txt — a map of the documentation. Fetch the specific
   pages it lists when you need conceptual detail.
 
Rules:
- Only use endpoints, parameters, and fields that appear in the OpenAPI document.
  If something you need is not there, say so — do not invent it.
- The base URL is https://api.ospulse.app. Paths already include /api/v1.
- Authenticate with the header: Authorization: Bearer $OSPULSE_TOKEN.
  Read the token from the environment; never hard-code it.
- Collections are offset-paginated: pass `take` and `skip`, and read
  { items, totalEstimate, take, skip } from the response.
- Errors are RFC 7807 problem documents. Surface `detail` and `correlationId`.
 
Task: <what you actually want built>

Those six rules remove the mistakes agents make most often against this API: inventing endpoints, using cursor pagination that does not exist, omitting the /api/v1 prefix, and swallowing the correlationId that support needs.

Building an integration with an assistant

Coding agents do well on this API when they are given the contract up front rather than left to discover it. A workflow that reliably produces working code:

curl -sO https://ospulse.app/openapi.json
curl -s https://ospulse.app/llms.txt -o ospulse-docs.txt

jq -r '.paths | to_entries[] | .key as $p | .value | to_entries[]
       | "\(.key | ascii_upcase) \($p)  — \(.value.summary)"' openapi.json \
  | grep -i 'packages\|scans'

Read these before writing code:
  https://ospulse.app/docs/authentication/index.md
  https://ospulse.app/docs/api/pagination/index.md
  https://ospulse.app/docs/api/errors/index.md
  https://ospulse.app/docs/concepts/health-scoring/index.md

npx @stoplight/prism-cli mock openapi.json --port 4010

grep -oE '/api/v1/[a-zA-Z0-9/{}_.:-]+' -r src/ | sort -u | while read -r m; do
  path="${m#*:}"
  jq -e --arg p "$path" '.paths | has($p)' openapi.json >/dev/null 2>&1 \
    || echo "NOT IN SPEC: $path"
done

Crawling and citation

The Markdown twins and llms.txt exist precisely so that agents do not have to render or scrape these pages. If you are building a retrieval index, fetch llms-full.txt on a schedule rather than crawling — it is one request instead of dozens, and it is the same content.

When an assistant answers from these docs, linking the page it used lets the reader verify the answer against the current version. The canonical URL of every page is declared in its metadata, and the Markdown twin lives at that URL plus index.md.

Next steps