# Docs for AI agents

> Every page of these docs comes as Markdown for language models, with llms.txt to find them, llms-full.txt to read them all at once, and a prompt that gets a coding agent to build a BlueBot integration the right way.

These docs are written for people and for the models that help them. A coding agent building your integration should read the same pages you do, as plain Markdown it can take in whole, rather than guess at BlueBot's API from what it half remembers. Everything on this page is public and needs no key.

## llms.txt

[`https://usebluebot.com/llms.txt`](https://usebluebot.com/llms.txt) is the map, in the [llms.txt](https://llmstxt.org) format. It has:

- what BlueBot is, in one paragraph, and the facts an agent gets wrong most often: the base URL, how to authenticate, that a held text is accepted rather than refused, and to send an `Idempotency-Key`;
- **What BlueBot is not**, so an agent doesn't build something BlueBot won't do, such as texting people who never asked;
- every page of the docs, by section, as a link to its Markdown copy with its one-line description;
- an **Optional** section with the long lists (the app recipes and the error codes) that an agent reads only when it needs them.

Give an agent this address first. It's short enough to read in one go, and it tells the agent which page to open for each question.

## llms-full.txt

[`https://usebluebot.com/llms-full.txt`](https://usebluebot.com/llms-full.txt) is every page as Markdown, one after another, and each page starts with its address. It's large, a few hundred thousand characters, so use it when an agent has room for all of it or when you want to load the docs into a project's knowledge: a Claude Project, a ChatGPT project, or a retrieval index of your own.

## A Markdown copy of every page

Add `.md` to any page's address to get the page as Markdown:

| Page                                          | Its Markdown                                     |
| --------------------------------------------- | ------------------------------------------------ |
| `https://usebluebot.com/docs/quickstart`      | `https://usebluebot.com/docs/quickstart.md`      |
| `https://usebluebot.com/docs/webhooks/verify` | `https://usebluebot.com/docs/webhooks/verify.md` |
| `https://usebluebot.com/docs`                 | `https://usebluebot.com/docs.md`                 |

The copy says everything the page shows. Request examples come out as curl, TypeScript and Python. Tables built from BlueBot's own data (holds, scopes, limits, events) are written out in full, diagrams come as Mermaid, callouts as quotes, and every link is absolute, so the copy reads correctly wherever it's pasted. Each page's HTML also names its copy with `<link rel="alternate" type="text/markdown">`, so a crawler finds it on its own.

## The buttons on every page

Under each page's title:

- **Copy as Markdown** puts the page's Markdown on your clipboard, ready to paste into a chat or a file.
- **Open in Claude** starts a new Claude chat that reads the page's Markdown copy, so you can ask about it straight away.
- **Open in ChatGPT** does the same in ChatGPT.
- **.md** opens the Markdown copy itself.

The two "Open in" buttons send the assistant the page's address, never the page's words, so the chat opens instantly and the assistant reads the current version.

## The OpenAPI file

[`https://usebluebot.com/openapi.v1.json`](https://usebluebot.com/openapi.v1.json) describes every operation in OpenAPI 3.1: the paths, every field with its type and limits, an example of every request and answer, the scope each operation needs (`x-scope`) and the error codes it can answer (`x-error-codes`). An agent writing HTTP calls by hand, or generating a client, should work from it. [OpenAPI, Postman and Insomnia](https://usebluebot.com/docs/openapi)

## Point your coding agent at the docs

### Claude Code

Tell it where the docs are in your project's `CLAUDE.md`, so every session knows:

```markdown title="CLAUDE.md"
## BlueBot

This project texts through BlueBot. Before writing or changing BlueBot code, read
https://usebluebot.com/llms.txt and the Markdown pages it links that the task needs.
Use @usebluebot/sdk (never the npm package "bluebot"). The API key is BLUEBOT_API_KEY
and the webhook secret is BLUEBOT_WEBHOOK_SECRET. Only ever text BLUEBOT_TEST_NUMBER while testing.
```

Claude Code fetches the pages as it needs them. To let it check your account while it works, such as whether your Mac is online, add BlueBot's [MCP server](https://usebluebot.com/docs/mcp) with a read-only key.

### Cursor

Add the docs to Cursor's index once: open **Cursor Settings → Indexing & Docs**, press **Add Doc**, and give it `https://usebluebot.com/docs`. Then mention `@BlueBot` in a chat to have it read them. For a project, put the same instructions as the `CLAUDE.md` above in a rule, such as `.cursor/rules/bluebot.mdc`.

### Any other agent

Paste the address of `llms.txt`, or of the one page that matters, into the chat, and ask it to read it before it writes code. An agent that can't fetch pages can take the Markdown pasted in: use **Copy as Markdown**.

## A prompt to start an integration

Paste this into your coding agent, with the first line changed to what you're building. It sends the agent to the right pages and gives it the rules that keep an integration from texting someone twice or by mistake.

```text title="Prompt"
I want to build: <one sentence, e.g. "text each new Typeform respondent and log their reply in HubSpot">.

Use BlueBot to send and receive the texts. Before you write code, read https://usebluebot.com/llms.txt,
then the Markdown pages it links that this needs (at least the quickstart, sending a text, webhooks and
verifying signatures). Work from https://usebluebot.com/openapi.v1.json for exact fields.

Follow these rules:
- Use the official SDK: @usebluebot/sdk for TypeScript or the Python package bluebot. The npm package
  named "bluebot" is not ours.
- Read the key from BLUEBOT_API_KEY. Never put a key in code.
- Send an Idempotency-Key on every POST, built from something stable (the form response id, the row id),
  so a retry never sends a second text.
- A text that can't go yet comes back "queued" with a "hold" saying why. That's success; don't retry it.
- Put my own record id in the text's metadata so webhooks can be matched back to it.
- Verify every webhook with BLUEBOT_WEBHOOK_SECRET against the raw body, skip event ids you've already
  handled, and answer 2xx within 10 seconds, doing slow work afterwards.
- Never text anyone but BLUEBOT_TEST_NUMBER while we're testing.

Tell me your plan before you write code.
```

> **Test runs send real texts.** BlueBot sends real texts from your own number, and there's no sandbox phone. Keep an agent's test runs pointed at your own number, and read any send it wants to make before you let it run.

## Next

- [Quickstart](https://usebluebot.com/docs/quickstart): Text yourself in four steps.
- [MCP server](https://usebluebot.com/docs/mcp): Let an assistant use your texts directly.