> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agents compatibility

> How AI coding agents, RAG systems, and automation should use this documentation safely and accurately.

This page is the **contract for machine consumers** of Yuno docs: what to read first, what counts as authoritative, and what not to do.

## Read order (mandatory)

1. **`llms.txt`** at the **repository root** (not an MDX page). Flat index of doc URLs and file paths for agents. On the live Mintlify site, an auto-generated index may also appear at `/llms.txt`. Regenerate after navigation changes: `python3 scripts/generate_llms_txt.py`.
2. **[`AGENTS.md`](/AGENTS.md)**. Project terminology, style, boundaries, and DX rules for edits.
3. **`api-reference/openapi.json`**. **Only** source of truth for HTTP paths, methods, request/response shapes, and `operationId` names. If prose and OpenAPI disagree, **follow OpenAPI** and file a docs bug.
4. **[MCP tool reference](/ai/mcp-tool-reference)**. When using the Yuno MCP server, tool names map to the same API as in OpenAPI.

## API requests (REST)

Every documented call uses these **exact header names** (case-sensitive in examples):

| Header               | Role                              |
| -------------------- | --------------------------------- |
| `public-api-key`     | Public key (Dashboard)            |
| `private-secret-key` | Secret key. **Server-side only.** |

The `account_id` value from the Dashboard is **not** an HTTP header. Place it inside the `account_id` field of request bodies that take it (such as `POST /v1/checkout/sessions` and `POST /v1/payments`).

Use **sandbox** base URL `https://api-sandbox.y.uno` for integration tests unless the page explicitly targets production.

## MCP vs REST

| Topic       | MCP (`@yuno-payments/mcp-server`)                                                         | REST                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Credentials | Env vars such as `YUNO_PUBLIC_KEY` (see [LLM & MCP integration](/ai/llm-mcp-integration)) | Headers `public-api-key`, `private-secret-key`. Plus `account_id` value inside `account_id` body fields. |
| Use case    | IDE / agent debugging, sandbox                                                            | Production and programmatic integration                                                                  |
| Authority   | Tool schemas + OpenAPI                                                                    | OpenAPI + MDX guides                                                                                     |

<Note>
  The MCP server maps those environment variables to the same Yuno API. When you emit raw `curl` for merchants, use the HTTP header names in the table above.
</Note>

## Rules for generated answers

* **Do not invent** endpoints, fields, enums, or error codes. Cite `openapi.json` or an MDX path from `llms.txt`.
* **Do not** recommend production keys inside MCP or chat logs.
* Prefer **checkout session** flows as documented; do not conflate “session” with a generic web session.
* For Brazil **PIX**, document that **`customer.document`** (CPF/CNPJ) is required. See [Payment methods](/core-concepts/payment-methods) and OpenAPI `POST /v1/payments`.

## CI and spec parity

* **`python3 scripts/openapi_paths_parity.py`**. Local `paths` must match [production OpenAPI bundle](https://docs.y.uno/api-reference/openapi.json).
* **`python3 scripts/sync_openapi_from_official.py`**. Refreshes **metadata-only** (`info`, license) from `~/yuno-docs-official/openapi.yaml` without changing `paths`.

## What “100% compatible” means here

| Expectation                        | Status                                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------------------------ |
| Machine index (`llms.txt`) in repo | Yes. Commit and refresh when `docs.json` navigation changes                                |
| Single OpenAPI contract file       | Yes. `api-reference/openapi.json`                                                          |
| Explicit agent + editor rules      | Yes. `AGENTS.md` + `.cursor/rules/yuno-docs-ai-agents.mdc`                                 |
| Hosted `llms-full.txt`             | Provided by Mintlify at deploy time on the live site (not stored in this repo due to size) |
| Weighted compatibility score       | Run `python3 scripts/agent_compatibility_score.py` (0 to 100 checklist; `--json` for CI)   |

## Related

* [LLM & MCP integration](/ai/llm-mcp-integration)
* [Remote MCP server](/ai/remote-mcp-server)
* [Agent orchestration](/ai/agent-orchestration)
* [Agent error recovery](/ai/agent-error-recovery)