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. 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. 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)	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

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.

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 and OpenAPI POST /v1/payments.

CI and spec parity

• python3 scripts/openapi_paths_parity.py. Local paths must match production OpenAPI bundle.
• 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
• Remote MCP server
• Agent orchestration
• Agent error recovery