# Use the API with AI

Give an AI agent the BuildBase HTTP API - MCP tools with each operation's exact contract, llms.txt, Markdown pages and OpenAPI imports.

## In short

AI assistants work best with the exact facts in front of them. This page is how to hand them over: connect your AI tool to BuildBase so it can look up any operation itself, point it at the plain-text versions of these docs, or give it the OpenAPI file so it can call the API. The same pieces serve a person asking ChatGPT for help and an autonomous agent writing code.

## The console MCP server

BuildBase's own MCP server, [https://api.console.buildbase.app/mcp](https://api.console.buildbase.app/mcp), works in Claude, ChatGPT, Cursor, VS Code and other MCP clients. You sign in as yourself; [BuildBase in your AI tools](/console/ai-agents) sets it up in one command. Three of its tools are about the documentation and the API:

| Tool                | Give it                                                                                  | It returns                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `search_docs`       | A question or keywords                                                                   | The best matching sections of these docs, each with its URL                                                             |
| `fetch_doc`         | A URL on the docs site, such as a `search_docs` result                                   | That page as Markdown                                                                                                   |
| `get_api_operation` | An `operationId` (`workspaces.list`) or `METHOD /path` (`GET /api/v1/public/workspaces`) | The operation's exact contract from the OpenAPI spec: parameters, request schema, credential, rate limits and responses |

All three only read. With them an agent answers "how do I list a user's workspaces?" from the contract itself, not from memory.

## Text versions of these docs

| File                 | What it holds                                        |
| -------------------- | ---------------------------------------------------- |
| `/llms.txt`          | The index of the docs, one line per page, for agents |
| `/llms/http-api.txt` | The HTTP API guides and reference, one line per page |
| `/llms-full.txt`     | Every page's text in one file                        |
| Any page plus `.md`  | That page as Markdown, such as `/http-api/errors.md` |

Each is under [https://docs.buildbase.app](https://docs.buildbase.app). A request for a page with `Accept: text/markdown` gets the Markdown twin too:

```bash
curl -s -H "Accept: text/markdown" "https://docs.buildbase.app/http-api/errors"
```

## Import the OpenAPI file

| Into                                        | How                                                                                                                                                                                   |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A custom GPT's **Actions** in ChatGPT       | **Create new action**, **Import from URL**, paste the spec URL below. Keep only the operations the GPT needs, and set **Authentication** to **API key**, custom header `x-session-id` |
| OpenAI function calling, Anthropic tool use | Turn each operation you want into a tool: `operationId` as the name, its summary as the description, its parameters and request body as the input schema                              |
| Postman, code generators                    | [The OpenAPI spec](/http-api/openapi#use-it-in-tools)                                                                                                                                 |

The spec: `https://docs.buildbase.app/openapi/public-v1.json`, or your own server's `GET /api/v1/openapi.json`.

A tool definition built from `workspaces.list`, in Anthropic's tool use format:

```json
{
  "name": "workspaces_list",
  "description": "List the workspaces the signed-in user belongs to. GET /api/v1/public/workspaces, x-session-id header.",
  "input_schema": { "type": "object", "properties": {} }
}
```

Your code runs the tool: it sends the request with the session it holds and returns the JSON to the model. Never put a session id or an API key in the prompt or the tool's schema, where the model, its logs and anyone reading the chat can see it.

## Example prompts

For a person using an AI assistant:

```text
Using the BuildBase HTTP API docs at https://docs.buildbase.app/http-api,
write a Python script that exchanges my API key for a session and lists my
workspaces. Read the key from the BUILDBASE_API_TOKEN environment variable.
```

```text
I got 429 from POST /api/v1/public/token/exchange. Using
https://docs.buildbase.app/http-api/rate-limits.md, tell me the limit and
how my code should wait.
```

For an agent with the console MCP server:

```text
Use get_api_operation for "POST /api/v1/public/workspaces/{workspaceId}/credits/purchase"
and tell me which credential it needs, its rate limits and its request body.
```

## Next steps

- [BuildBase in your AI tools](/console/ai-agents) - connect the MCP server.
- [The OpenAPI spec](/http-api/openapi) - what the `x-*` fields an agent reads mean.
- [Make your app agent ready](/agents/agent-ready) - let your own users' agents into your app.
