> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/developers/ai-agents/.

# Build with AI agents: give your agent the docs

Hand your coding agent the whole Diffio API in one URL. Every docs page is also plain Markdown, so Claude Code, Codex, Cursor or any other agent reads exactly what you would.

## Give your agent the docs

One URL holds every guide and endpoint as plain text. Paste it, or the prompt, into Claude Code, Codex, Cursor or any coding agent.

[https://diffio.ai/docs/llms-full.txt](https://diffio.ai/docs/llms-full.txt)

## Paste this prompt

Copy it, replace the first line with what you want built, and paste it into your agent. It points the agent at the docs and the SDK before it writes any code.

**Prompt**

```text
I want to build this with the Diffio speech restoration API: <describe what you want to build>

Before writing code, read the Diffio API docs: https://diffio.ai/docs/llms-full.txt
(plain text, every guide and endpoint). The OpenAPI document is at https://api.diffio.ai/v2/openapi.json.

Use the official SDK, version 1.0 or later (`pip install diffio` or `npm install diffio`), and read the API key
from the DIFFIO_API_KEY environment variable. Follow the docs exactly: field names, the upload flow and error
codes. If the docs do not cover something, say so instead of guessing.
```

## Connect the docs MCP server

Agents that speak MCP can search the docs, read one page and read one API operation instead of loading every page. It is read-only and needs no key: `search_docs`, `get_page`, `get_api_operation`.

**Claude Code: Terminal**

```bash
claude mcp add --transport http diffio-docs https://diffio.ai/docs/mcp
```

**Cursor: .cursor/mcp.json**

```json
{
  "mcpServers": {
    "diffio-docs": {
      "url": "https://diffio.ai/docs/mcp"
    }
  }
}
```

**VS Code: .vscode/mcp.json**

```json
{
  "servers": {
    "diffio-docs": {
      "type": "http",
      "url": "https://diffio.ai/docs/mcp"
    }
  }
}
```

**Codex: ~/.codex/config.toml**

```toml
[mcp_servers.diffio-docs]
url = "https://diffio.ai/docs/mcp"
```

## Every way to read the docs

None of these needs an API key.

- ### All API docs in one file

  [`https://diffio.ai/docs/llms-full.txt`](https://diffio.ai/docs/llms-full.txt)

  Every guide and endpoint page as Markdown, in reading order. Give an agent this one.
- ### OpenAPI 3.1 document

  [`https://api.diffio.ai/v2/openapi.json`](https://api.diffio.ai/v2/openapi.json)

  Machine-readable schema for every /v2 route, for code generators and typed clients.
- ### Docs MCP server

  `https://diffio.ai/docs/mcp`

  Streamable HTTP, read-only, no key: search_docs, get_page and get_api_operation.
- ### Docs index

  [`https://diffio.ai/llms.txt`](https://diffio.ai/llms.txt)

  One line per page with its Markdown URL, so an agent can fetch only the pages it needs.
- ### Any single page

  [`https://diffio.ai/docs/developers/quick-start.md`](https://diffio.ai/docs/developers/quick-start.md)

  Add .md to a docs URL, or request the HTML URL with Accept: text/markdown.

**Fetch any page as Markdown**

```bash
# Add .md to any docs URL
curl https://diffio.ai/docs/api-reference/create-project.md

# Or ask for Markdown at the normal URL
curl -H "Accept: text/markdown" https://diffio.ai/docs/api-reference/create-project/
```

## What your agent must get right

The prompt points the agent at these, and the docs bundle opens with them: the details agents most often get wrong.

1. Base URL `https://api.diffio.ai/v2`. Send the key as `Authorization: Bearer <key>` and read it from the `DIFFIO_API_KEY` environment variable. Never ship the key to a browser or mobile app.
2. Prefer the SDKs: `pip install diffio` (Python) or `npm install diffio` (Node.js), version 1.0 or later. Earlier versions use an older API that these docs do not describe.
3. Request and response fields are snake_case (`file_name`, `latest_generation`, `upload_token`), and the objects both SDKs return keep those names.
4. The flow is: create a project, upload the file by following `upload.requests`, create a generation with `model` `diffio-flash` or `diffio-pro`, wait for `status` `complete`, then get media URLs. Pass `generation` when you create the project to queue the restore in the same call.
5. Let browsers upload straight to Diffio: hand them the project's `upload` (its `upload_token` covers that one upload for 24 hours) and keep the API key on your server.
6. Wait with webhooks in production; poll `GET /projects/{project_id}/generations/{generation_id}` every few seconds otherwise.
7. Media URLs from `GET .../media` need no API key and expire after 6 hours (`expires_at`); request a new grant instead of storing them.
8. Building for many users? Send `Diffio-End-User: <your user id>` so each user sees only their own projects and usage.
9. Send an `Idempotency-Key` on project, generation and edit creates when your own code may retry them; the SDKs add one for their own retries.
10. Branch on `error.code`, not the HTTP status: one status can mean several things with different fixes. Every code and its retry rule is listed at https://diffio.ai/docs/api-reference/errors/.

## Keep the docs in your repo

For an agent that works offline or keeps losing context, save the docs into the repository and point its instructions file (`AGENTS.md`, `CLAUDE.md` or `.cursor/rules`) at them.

**Save the docs**

```bash
mkdir -p docs && curl -sSf https://diffio.ai/docs/llms-full.txt -o docs/diffio-api.md
```

**AGENTS.md**

```markdown
## Diffio API

- Read docs/diffio-api.md before changing code that calls Diffio
  (refresh it with: curl -sSf https://diffio.ai/docs/llms-full.txt -o docs/diffio-api.md).
- Base URL `https://api.diffio.ai/v2`. Send the key as `Authorization: Bearer <key>` and read it from the `DIFFIO_API_KEY` environment variable. Never ship the key to a browser or mobile app.
- Prefer the SDKs: `pip install diffio` (Python) or `npm install diffio` (Node.js), version 1.0 or later. Earlier versions use an older API that these docs do not describe.
- Request and response fields are snake_case (`file_name`, `latest_generation`, `upload_token`), and the objects both SDKs return keep those names.
- The flow is: create a project, upload the file by following `upload.requests`, create a generation with `model` `diffio-flash` or `diffio-pro`, wait for `status` `complete`, then get media URLs. Pass `generation` when you create the project to queue the restore in the same call.
- Let browsers upload straight to Diffio: hand them the project's `upload` (its `upload_token` covers that one upload for 24 hours) and keep the API key on your server.
- Wait with webhooks in production; poll `GET /projects/{project_id}/generations/{generation_id}` every few seconds otherwise.
- Media URLs from `GET .../media` need no API key and expire after 6 hours (`expires_at`); request a new grant instead of storing them.
- Building for many users? Send `Diffio-End-User: <your user id>` so each user sees only their own projects and usage.
- Send an `Idempotency-Key` on project, generation and edit creates when your own code may retry them; the SDKs add one for their own retries.
- Branch on `error.code`, not the HTTP status: one status can mean several things with different fixes. Every code and its retry rule is listed at https://diffio.ai/docs/api-reference/errors/.
```

The file is rebuilt on every docs release; fetch it again before new work.

## Give your agent a key

[Create a key with Write permission](https://diffio.ai/developers/api-keys/) and set it as `DIFFIO_API_KEY` in the shell your agent runs in. Every API account starts with a one-time $5 credit, enough for an agent to run real restores while it builds and tests. Keep the key in the environment, never in code the agent commits.

## Related pages

- [Podcast cleanup in a SaaS app](https://diffio.ai/docs/developers/guides/saas-podcast-cleanup/): A complete server, browser upload and webhook build to hand an agent.
- [Errors](https://diffio.ai/docs/api-reference/errors/): Every error code with its retry rule.
- [Quickstart](https://diffio.ai/docs/developers/quick-start/): Restore a first file in one call, by hand.
- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [API reference](https://diffio.ai/docs/api-reference/introduction/): Base URL, authentication, errors and every endpoint.
