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

# Marea Alcalina API

> Spin up a digital menu or product catalog + a public hosted storefront, then sell through WhatsApp, web checkout, or in-person — in under 10 calls.

Storefronts ship in Spanish (default), English, or Portuguese. The order channel is the operator's choice — WhatsApp, web checkout, or in-person pickup — configurable per storefront.

<Note>
  **These docs are agent-first.** Every page is also available as raw markdown at `<page>.md`, and every API reference page ships with a copy-paste-for-LLM block. Every error returns a `nextActions[]` array (`{label, method, url}`) — surface it to the user verbatim; **do NOT swallow 402 / 451 / 422 silently.** If you're an agent reading these docs to integrate, start with [llms.txt](/llms.txt) and [AGENTS.md](/AGENTS.md).
</Note>

## What kind of integration are you building?

<CardGroup cols={2}>
  <Card title="I run a store on Marea" icon="store" href="/quickstart/products">
    You signed up at [mareaalcalina.com](https://mareaalcalina.com), you have a storefront, you want API access to it (POS sync, custom dashboard, automation). **This is the common case.** Grab your `mk_user_*` from the dashboard and start with [Add products](/quickstart/products).
  </Card>

  <Card title="I'm building an agent or integration" icon="rocket" href="/quickstart/bootstrap">
    You're building an AI agent, vertical SaaS, or agency tool that creates Marea accounts for *other* people. You need to bootstrap users on their behalf. Start with [Bootstrap a user](/quickstart/bootstrap).
  </Card>
</CardGroup>

If you're not sure which one you are, you're probably the first one.

## Auth in 30 seconds

Every call uses a Bearer token. The one you use depends on what you're doing:

```http theme={null}
GET /v1/me HTTP/1.1
Host: api.mareaalcalina.com
Authorization: Bearer mk_user_xxxxxxxxxxxxxxxx
```

| Key prefix  | Who holds it                   | Use it for                                                                                                                                                                                                              |
| ----------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mk_user_*` | A specific Marea user          | **Default.** All catalog + storefront + product + publish calls — **across every storefront that user owns** (1 on Free, up to 5,000 on Agency Growth). Owner-scoped, not storefront-scoped. Mints from your dashboard. |
| `mk_dev_*`  | An agent / partner integration | Bootstrapping *other* users via `POST /v1/users`, then using each returned `mk_user_*` to manage all of that user's storefronts. Mints from the developer dashboard.                                                    |

**Most integrations only ever need `mk_user_*`.** Partners ([three archetypes](/concepts/keys#partner-keys)) hold one `mk_dev_*` and many `mk_user_*` — one per user they bootstrap. Full model: [/concepts/keys](/concepts/keys).

## Five things every integration must do

1. **Send `Idempotency-Key` on every POST and PATCH.** Same key + same body returns the original response (replay-safe). See [Safe mutations](/concepts/safe-mutations).
2. **Branch on `error.type`, not `error.message`.** The `type` field is a stable 10-value enum; messages are localized. See [Errors](/concepts/errors).
3. **Surface `nextActions[]` verbatim.** It's a `{label, method, url}[]` array of concrete remediation steps. Don't paraphrase.
4. **Read `X-RateLimit-Remaining` and respect `Retry-After`.** See [Rate limits](/concepts/rate-limits) for current numbers.
5. **Handle the publish gates.** `POST .../publish` returns 402 (pre-paywall), 422 (0 products), or 451 (ToS not accepted) — surface each `nextActions[]` explicitly; don't auto-accept ToS or auto-publish without user confirmation. See [Publishing](/concepts/publishing).

## Webhooks

Marea uses a **Stripe-style endpoint model**: register an endpoint (URL + signing secret + `subscribedEvents[]`) and Marea fans out matching events to it. Up to 16 endpoints per account.

<CardGroup cols={2}>
  <Card title="Webhook endpoints" icon="bolt" href="/concepts/webhooks">
    Five events: `user.verified`, `user.cancelled`, `order.created`, `order.status_updated`, `order.paid`. A single developer endpoint receives `order.*` from every storefront the key bootstrapped — no per-merchant registration needed.
  </Card>

  <Card title="Receiver helpers" icon="shield-check" href="/api/webhooks/receiver-helpers">
    Drop-in JavaScript and Python verifiers: HMAC-SHA256 + 5-minute replay window using the endpoint's raw 64-char-hex `signingSecret`. One algorithm for every event type.
  </Card>
</CardGroup>

## Agent-friendly resources

* [**llms.txt**](/llms.txt) — job-to-be-done index of the entire docs surface
* [**AGENTS.md**](/AGENTS.md) — common patterns + what NOT to do (cheatsheet)
* [**OpenAPI 3.1 spec**](https://api.mareaalcalina.com/v1/openapi.json) — Zod-derived; 5-min cached
* [**Postman collection**](/marea.postman.json) — auto-generated from the OpenAPI spec
* [**MCP server**](https://mcp.mareaalcalina.com) — paste-token install for Claude Desktop / Cursor / Continue.dev
* **Per-page markdown:** every page is also at `<page>.md` (e.g., [/concepts/errors.md](/concepts/errors))