Your data, on tap. For whoever needs it.

Every endpoint requires a Bearer token in the Authorization header. Keys are scoped per-permission and per-tenant — there are no global admin keys.

curl https://heirspears.com/api/v1/orders \
  -H "Authorization: Bearer mtx_live_..."

Rate limit: 600 req/min per key (2,400 on Pro). When exceeded, the response is HTTP 429 with Retry-After and X-RateLimit-Remaining headers.

Scopes: read:orders, read:products, read:customers. Pick the minimum a key needs.

List your active catalog. Useful for inventory sync, menu mirroring, or seeding a third-party search index.

curl https://heirspears.com/api/v1/products \
  -H "Authorization: Bearer mtx_live_..."

{
  "data": [
    {
      "id": "8f3...",
      "name": "Country sourdough",
      "slug": "country-sourdough",
      "list_price_cents": 900,
      "currency": "USD",
      "category_id": "3a2...",
      "dietary_tags": ["vegan"],
      "is_active": true,
      "updated_at": "2026-04-29T18:21:00Z"
    }
  ],
  "next_cursor": null
}

Filter with ?category=loaves, ?since=2026-04-01T00:00:00Z, or ?limit=50 (max 200, paginate with cursor).

List orders, most recent first. The endpoint most accounting + BI integrations will use daily.

curl "https://heirspears.com/api/v1/orders?status=delivered&since=2026-04-28" \
  -H "Authorization: Bearer mtx_live_..."

{
  "data": [
    {
      "id": "ord_...",
      "order_number": "HP-00342",
      "status": "delivered",
      "subtotal_cents": 4500,
      "tax_cents": 225,
      "delivery_fee_cents": 800,
      "total_cents": 5525,
      "currency": "USD",
      "customer": { "email": "amy@example.com", "name": "Amy K." },
      "delivery_date": "2026-04-29",
      "items": [ /* line items */ ],
      "created_at": "2026-04-28T19:14:00Z",
      "delivered_at": "2026-04-29T13:42:00Z"
    }
  ],
  "next_cursor": "eyJ..."
}

Query params: status, since / until (ISO 8601), limit (max 200), cursor.

We POST JSON to URLs you configure in Settings → Webhooks. Every request includes an X-Mitryxa-Signature header (HMAC-SHA256 of the raw body, hex-encoded with your webhook secret).

Events you can subscribe to:

Verifying a payload (Node):

import crypto from "node:crypto";

export function isValidSignature(
  rawBody: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Retries: Failed deliveries (non-2xx) retry at 1m, 5m, 15m, 1h, 6h. Max 5 attempts before the event is marked failed in your webhook log.

Idempotency: Each event has a unique event_id. If you see the same event_id twice, it's a retry — handle it idempotently.

• Store keys in your secret manager, never in source control.
• Issue one key per integration. Revoke any key from Settings → API keys when rotating.
• Always verify the webhook signature before processing the payload.
• Use scopes — a Slack bot does not need read:customers, just read:orders.
• Never embed an API key in a public mobile app or front-end. Use a server-side proxy.
• Don't poll for changes when a webhook would do — saves rate-limit budget on both sides.

Errors return a JSON body with an error string and a status code.

• 401Missing, malformed, or invalid key.
• 403Key valid but missing the scope this endpoint requires.
• 404Resource not found in your tenant. (RLS — never an information leak about another tenant.)
• 429Rate limit exceeded. Wait the time in Retry-After and retry.
• 5xxServer-side issue. Retry with exponential backoff.