Building with AI

Agent-readable Markdown mirrors, an llms.txt index, and a stable OpenAPI spec URL for building on the Jobs API with AI tools.

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

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

/llms.txt — a curated index of the documentation with a short set of instructions for agents (auth, conventions, behavior rules).
/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.

OpenAPI spec

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

/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

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.
Handle RFC 7807 errors. Failures return application/problem+json. See Errors.

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 and /api/v1/openapi.json.