Documentation Index

Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt

Use this file to discover all available pages before exploring further.

​

AGENTS.md — Marea Alcalina API

Following the agents.md spec. This file is for AI agents (Claude, GPT, Cursor, Continue.dev, generic LLM-driven tools) consuming the Marea public API. For the full doc index in agent-friendly markdown form, fetch llms.txt.

​

What this API is for

​

Auth model

• mk_dev_* — developer key, held by the agent or app builder. Holds developer:bootstrap, developer:read, developer:issueUserKey. Default rpd: 50 (configurable at issue time; the dev rpd IS the bootstrap cap, not a separate quota).
• mk_user_* — per-user key, returned by POST /v1/users and scoped to one user. Issued restricted (only me:verify + me:resendVerification) until the 6-digit code is verified, then upgraded in-place to full catalog scopes (catalog:read, catalog:write, storefront:publish). Cannot bootstrap, cannot see other users’ data.

​

Common patterns

• Bootstrap → verify → use. POST /v1/users returns a restricted mk_user_* key + emails the user a 6-digit code. The user reads the code aloud (or the agent fetches it via Gmail-MCP), agent calls POST /v1/users/:userId/verify, the same key is upgraded to full per-user scope. See Bootstrap quickstart.
• Idempotency on every mutation. Pass Idempotency-Key: <uuid-v4> on every POST and PATCH. Same key + same body returns the original response (replay-safe). Same key + different body returns 409 idempotency_conflict. See Safe mutations.
• Branch on error.type, not error.message. The type field is a stable 10-value enum; message is localized and may change. See Errors.
• Surface nextActions[] verbatim. Every error returns { label, method, url }[] — these are the concrete actions the user can take. Don’t paraphrase; render verbatim.
• Read rate-limit headers proactively. X-RateLimit-Remaining is on every response. When you hit 429, read Retry-After (seconds) and back off. Defaults: rpm: 60. Dev keys: rpd: 50. User keys: rpd: 10000.
• Markdown for ingestion. Every doc page also serves at <page>.md (e.g., /concepts/errors.md); use that variant when ingesting docs into your context — cleaner than the HTML.

​

When to call which tool

​

What NOT to do

• Don’t swallow nextActions[]. The most common agent failure mode is silently retrying past a 402 (paywall) or 451 (ToS not accepted) without ever surfacing the action to the user. Render the array verbatim.
• Don’t auto-accept the ToS on the user’s behalf. A 451 → modal flow requires user input by design. The agent cannot bypass.
• Don’t bootstrap past your dev key’s rpd cap. Default is 50/day (configurable at issue time). Hitting it returns 429 rate_limited with code: rate_limit_exceeded and rpd_exceeded in error.message. Read Retry-After (seconds-until-the-day-rolls-over) and back off.
• Don’t call publish without explicit user confirmation. Publish is destructive and user-visible. Use MCP elicitation if you have the MCP tool; otherwise prompt the user explicitly.
• Don’t cache mk_user_* keys across users or sessions. Per-user keys belong in the user’s own context.
• Don’t poll verification status faster than the API allows. The user-facing rate limit is rpm: 60 per user-key. Poll at most once every 30s during the verify window; better, subscribe to the user.verified agent webhook on the developer key — see Agent webhooks.
• Don’t reuse the same Idempotency-Key with a different body. That returns 409 idempotency_conflict and you must generate a fresh key. If you’re retrying with edits, that’s a new request — new key.
• Don’t branch on the localized error.message. Branch on error.type (stable enum) or error.code (stable string).

​

Errors

​

Where to find docs

• llms.txt index: https://docs.mareaalcalina.com/llms.txt — agent-curated overview of the entire surface
• llms-full.txt: https://docs.mareaalcalina.com/llms-full.txt — concatenation of all pages (Mintlify auto-emits in production)
• Per-page markdown: https://docs.mareaalcalina.com/<page>.md (e.g., /concepts/errors.md)
• OpenAPI 3.1 spec: https://api.mareaalcalina.com/v1/openapi.json — Zod-derived from the cloud-functions code; 5-min cached
• Postman collection: https://docs.mareaalcalina.com/marea.postman.json — auto-generated from the OpenAPI spec
• MCP server: https://mcp.mareaalcalina.com — paste-token install for Claude Desktop / Cursor / Continue.dev; 7 marea.* tools (verify + resend are deliberately REST-only)
• API catalog (RFC 9727): https://mareaalcalina.com/.well-known/api-catalog — discoverability for agent crawlers

​

Conventions

• Locale: Accept-Language is honored. Default es-MX. Pass Accept-Language: en for English error messages, pt for Portuguese.
• Currency: configurable per storefront. Pass currency: "MXN" | "USD" | "CAD" | "BRL" | ... on storefront create.
• Phone format: E.164 (+52...).
• Timestamps: ISO 8601 strings.
• IDs: prefixed (usr_, stf_, prd_, dev_).