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)
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.AGENTS.md. Project terminology, style, boundaries, and DX rules for edits.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.- 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. |
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) |
