Read BuilderBooks as data, not as HTML.

Every public page has a machine-readable twin at the same path. An agent never has to scrape markup to learn what a skill costs, what it does, or what commands it ships with.

Start here

/llms.txt: every public page, with a one-line description each.
/openapi.json: the OpenAPI 3.1 contract for every JSON endpoint.
/version.json: the build and base URL this deployment answers for.
/sitemap.xml: every indexable URL.

JSON endpoints

GET /catalog.json
The whole catalogue, skills and bundles in one read. Narrow it with ?cluster=, ?sort=price or ?sort=-price, and ?limit=.
GET /skills/{slug}.json
One skill, with its commands, clusters, price and source book.
GET /bundles/{slug}.json
One bundle, with the skills it contains and the price at that count.

Every endpoint is also reachable under the version prefix: /v1/catalog.json is the same resource as /catalog.json, pinned to major version 1.

Markdown twins

Append .md to any public path, or send Accept: text/markdown. /library.md, /skills/the-mom-test.md and /pricing.md all return the same facts as the HTML page, as Markdown with YAML front matter.

Headers on every response

api-version: the major version that answered. Currently 1.
x-build-version, x-base-url: which build answered, and the origin it speaks for.
etag, cache-control: responses are cacheable for an hour. Send If-None-Match and expect a 304.
ratelimit-limit, ratelimit-remaining, ratelimit-reset, ratelimit-policy: the budget, 600 requests per hour per client. Informational today, enforced later with the same headers.

Live readiness

This site is continuously verified by ora. The current score, fetched live with a bounded time budget and a cached fallback path:

Errors

Errors are JSON, never HTML, and carry the same headers as a success. The shape is stable:

{
  "error": {
    "code": "not_found",
    "message": "No skill with slug 'nope'.",
    "hints": ["/catalog.json lists every skill and bundle."]
  }
}

400 means the query was malformed, 404 that the resource does not exist, 500 that we broke something. In all three the hints array points at the endpoint that answers the question you were asking.

Versioning and deprecation

Breaking changes ship as a new prefix, /v2/. The previous major stays available for at least six months after the successor is announced, and every response on a retiring version carries a deprecation and a sunset header before it goes.

Licence and fair use

The catalogue metadata is free to read, cache and index. Skill files themselves are delivered only to buyers, through a signed download link. Identify your agent with a User-Agent we can reach you at, and stay inside the published budget.

Something missing? Write to contact@pa.ventures and ask for it.

Open the OpenAPI spec Contact us