Source: https://www.puesto.dev/docs/building-with-ai
Markdown source: https://www.puesto.dev/docs/building-with-ai.md
Description: Agent-readable Markdown mirrors, an llms.txt index, and a stable OpenAPI spec URL for building on the Jobs API with AI tools.

# Building with AI



Every page in these docs is available as plain Markdown, and the whole corpus is
published in the formats AI coding agents and assistants expect. This page is
the map.

## Markdown mirror of any page [#markdown-mirror-of-any-page]

Append `.md` to any documentation URL to get the raw Markdown for that page,
served as `text/markdown`:

```
https://www.puesto.dev/docs/authentication      → HTML
https://www.puesto.dev/docs/authentication.md   → Markdown
```

This works for every page, including the auto-generated API reference. Each API
operation renders as compact Markdown — method and path, parameter tables,
response fields, an authenticated `curl` example, and a link to the full spec:

```
https://www.puesto.dev/docs/api/jobs/search-jobs.md
```

You can also grab the Markdown from the UI: use **Copy as Markdown** or
**Open in AI** at the top of any docs page.

## llms.txt and the full corpus [#llmstxt-and-the-full-corpus]

* [`/llms.txt`](/llms.txt) — a curated index of the documentation with a short
  set of instructions for agents (auth, conventions, behavior rules).
* [`/llms-full.txt`](/llms-full.txt) — the entire documentation corpus as a
  single Markdown file, ready to paste into a model's context.

Both follow the [llms.txt convention](https://llmstxt.org).

## OpenAPI spec [#openapi-spec]

The machine-readable OpenAPI 3.1 description of the API lives at a stable URL:

* [`/api/v1/openapi.json`](/api/v1/openapi.json)

Point code generators, API explorers, or agent tools at this URL to get typed
clients and request builders.

## Agent behavior rules [#agent-behavior-rules]

If you are configuring an agent to call the Jobs API, follow these rules:

* **Never ask a user to paste their secret key into chat.** Keys (prefixed
  `sk_`) are created in a team's **API Keys** settings and used server-side.
* **Send the key in the `Authorization` header**, never in the query string, so
  it is not captured in logs or history.
* **Respect `Retry-After`.** On a `429 Too Many Requests` response, wait for the
  duration in the `Retry-After` header before retrying. See
  [Rate limits](/docs/rate-limits).
* **Handle RFC 7807 errors.** Failures return `application/problem+json`. See
  [Errors](/docs/errors).

## MCP server [#mcp-server]

An official Model Context Protocol (MCP) server for the Jobs API is planned.
Per-client install configurations will be published here when it ships. In the
meantime, point your agent at [`/llms.txt`](/llms.txt) and
[`/api/v1/openapi.json`](/api/v1/openapi.json).