Reference

API overview

A small, predictable REST API: JSON in, JSON out, one error format everywhere.

Base URL

https://api.askmerra.com/v1

Two public APIs

API	Who calls it	Authentication
Catalog Push API	Your servers, ERPs, platform connectors	Secret key: `Authorization: Bearer sk_live_…`
Widget API	Browsers on your allowed domains (the widget, or your own chat UI)	Site key in the query string + proof-of-work session token

Secret keys

Create secret keys in Dashboard → API keys (owners and admins). The full key is shown once; we only store a hash. Up to 10 keys can be active per shop, so you can rotate without downtime: create a new key, deploy it, revoke the old one.

curl https://api.askmerra.com/v1/catalog/ping -H "Authorization: Bearer $ASKMERRA_SECRET_KEY"

Keep secret keys on the server

Never embed a secret key in a web page, mobile app or public repository. If one leaks, revoke it immediately in the dashboard.

Errors

Every error has the same shape:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit: 120 requests per minute per key",
    "details": { "retryAfterSec": 12 },
    "requestId": "req_7f3c…"
  }
}

Status	Code	Meaning
400	`validation_error`	The body or query does not match the schema. details lists each issue (path + message).
401	`unauthorized`	Missing Authorization header.
401	`invalid_api_key`	Unknown or revoked secret key.
401	`invalid_site_key`	Unknown or revoked site key (widget API).
401	`session_expired / session_mismatch`	Widget session token expired or issued for another shop, visitor or site.
403	`origin_not_allowed`	Widget API called from a domain that is not in the shop’s allowed domains.
403	`client_not_allowed`	Widget API called by something that is not a browser.
404	`not_found`	Unknown route or resource.
413	`fst_err_ctp_body_too_large`	Request body too large (Push API: 10 MB).
429	`rate_limited`	Too many requests. Wait for the number of seconds in the Retry-After header.
500	`internal_error`	Something went wrong on our side. Retry with backoff; contact us with the requestId if it persists.

Every response carries an x-request-id header. Include it when contacting support.

Rate limits

Push API: 120 requests per minute per secret key (up to 500 products per request → 60,000 products per minute).
Widget API: per visitor, per IP address and per shop (see the security model).

When limited you receive 429 with a Retry-After header. Retry with exponential backoff and jitter.

Versioning

The version is part of the path (/v1). Within a version we only make additive changes (new endpoints, new optional fields, new response fields, new error codes), so ignore unknown fields. Breaking changes ship as a new version with at least 12 months of overlap.