# API reference

URL: /docs/api

Every Storefront API and Merchant API endpoint, generated from the engine's own OpenAPI document.

The reference is generated from the OpenAPI document the Elara One engine produces from its own code, so it matches what the API does. Each page shows the request, its headers and body, example code and every response.

```text
https://api.elaraone.app/api/v1
```

## Two APIs, one base URL [#two-apis-one-base-url]

<Cards>
  <Card title="Storefront API" href="/docs/api/storefront/catalogue/list-products" description="What a shop needs: catalogue, search, cart, checkout, orders, customer accounts, forms, content, consent and chat." />
  <Card title="Merchant API" href="/docs/api/merchant/crm/list-contacts" description="Back-office integrations: CRM contacts, companies, tasks and notes, orders, forms, flows, pages and conversations." />
</Cards>

| Detail | Storefront API | Merchant API |
|---|---|---|
| Paths | `/v1/products`, `/v1/cart`, `/v1/checkout/…` | `/v1/merchant/…` |
| Called by | Your storefront server | Your integrations and back-office jobs |
| Credentials | Store key and server secret; a customer token on account routes | Store key and server secret, plus a merchant API key as a bearer token |

Every call carries `X-Tenant-Key`, and every call from a server also carries `X-Tenant-Secret`. See [Authentication](/docs/authentication).

## Shared behaviour [#shared-behaviour]

- **Responses** wrap their payload in `data`. Lists add `links` and `meta` for [pagination](/docs/concepts/pagination).
- **Errors** are `{ "error": { "code", "message", "details" } }`, with a stable `code` to branch on. See [Errors](/docs/concepts/errors).
- **Money** is `{ "amount", "currency", "formatted" }` with `amount` in minor units. See [Money](/docs/concepts/money).
- **Writes you might retry** take an `Idempotency-Key`. See [Idempotency keys](/docs/concepts/idempotency).
- **Rate limits** are reported in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `Retry-After`. See [Rate limits](/docs/concepts/rate-limits).
- **Times** are ISO 8601 in UTC.

## Use it with your tools [#use-it-with-your-tools]

The OpenAPI document behind this reference is at [`/api/openapi/storefront`](/api/openapi/storefront): import it into Postman, Insomnia or a client generator. Every reference page also has a Markdown copy at its URL plus `.md`, and [`/llms-full.txt`](/llms-full.txt) includes the whole reference for AI tools.

Changes to the API are announced in the [changelog](/changelog). See [Versioning](/docs/concepts/versioning) for what we treat as a breaking change.