+++
title = "Bonsai docs and API for agents"
description = "Read these docs as Markdown, and use the API's OpenAPI description and llms.txt, from an agent or a language model."
weight = 25
updated = 2026-11-11

[extra]
nav_title = "Docs and API for agents"
weight = 70
+++

Agents read documentation and call APIs too. Both are available in forms made for them.

## These docs, in Markdown

Every docs page and blog post on bonsai.io is also served as Markdown, without the site's navigation and markup around it. Ask for it with an `Accept` header:

```bash
curl -H "Accept: text/markdown" https://bonsai.io/docs/cli/mcp-server/
```

Or add `index.md` to a page's address:

```
https://bonsai.io/docs/cli/mcp-server/index.md
```

The answer carries a `Link` header with the page's canonical address.

To have an agent read a page, give it the address and ask:

> Read https://bonsai.io/docs/cli/scripting/ and write a CI job that creates a cluster for the tests.

## The API's OpenAPI description

The [Bonsai API v1](@/docs/api/overview/index.md) is described by an OpenAPI 3.0 document. Give it to an agent to write a client, or to an agent framework that turns operations into tools. None of these need a token:

| | |
|---|---|
| `https://api.bonsai.io/v1/openapi.json` | The OpenAPI description, as JSON |
| `https://api.bonsai.io/v1/openapi.yml` | The same, as YAML |
| `https://api.bonsai.io/llms.txt` | A summary of the API for language models |
| `https://api.bonsai.io/v1` | The API's version, and these links |

The [API reference](@/docs/api/reference/_index.md) is built from the same description.

## Calling the API from an agent

An agent with the CLI doesn't need its own HTTP client or your token. `bonsai api` sends any request with the token the CLI holds:

```bash
bonsai api GET /clusters --paginate
bonsai api GET /clusters/search-nozais/metrics
```

An agent you build yourself calls the API with a Bearer token:

```bash
curl https://api.bonsai.io/v1/clusters \
  -H "Authorization: Bearer $BONSAI_TOKEN"
```

A few things make the API easy on agents:

- **Slow changes are [Actions](@/docs/api/actions/index.md).** Creating a cluster answers at once with an Action to poll, so a tool call never has to wait.
- **Retries are safe.** An [`Idempotency-Key`](@/docs/api/retrying-safely/index.md) header means a repeated create can't make a second cluster.
- **Errors are specific.** Each has a `code` that says what to do, such as which scope the token is missing. See [Errors](@/docs/api/errors/index.md).
- **Tokens are scoped.** Give an agent's token only the [scopes](@/docs/api/authentication/index.md#scopes) it needs.

## Which should an agent use?

- An agent with a shell: the [CLI and its skill](@/docs/agents/claude-code/index.md).
- An MCP client: the [MCP server](@/docs/agents/mcp-clients/index.md).
- An agent you're building, or one that runs where the CLI can't: the [API](@/docs/api/quickstart/index.md).