---
title: "Developers and agents"
description: "The BuilderBooks API for agents: JSON twins for every skill and bundle, Markdown twins for every page, an OpenAPI 3.1 contract, versioning and rate limits."
url: "https://builderbooks.dev/developers"
type: "page"
site: "BuilderBooks.dev"
---

# 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](/llms.txt): every public page, with a one-line description each.
- [/openapi.json](/openapi.json): the OpenAPI 3.1 contract for every JSON endpoint.
- [/version.json](/version.json): the build and base URL this deployment answers for.
- [/sitemap.xml](/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` and `x-base-url`: which build answered, and the origin it speaks for.
- `etag` and `cache-control`: responses are cacheable for an hour. Send `If-None-Match` and expect a `304`.
- `ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset` and `ratelimit-policy`: the budget, 600 requests per hour per client. Informational today, enforced later with the same headers.

## Errors

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

```json
{
  "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](mailto:contact@pa.ventures) and ask for it. See also the [contact page](/contact).