Littledata MonitorAI guide

Customer API (other Littledata apps)

This API lets server-side Littledata applications load a store’s monitoring value messaging and open audit findings (info, warning, or error only). Use it to show the same outcomes in another product surface.

Base URL: Your deployed monitoring API origin (the same host you use for other monitoring API calls).

Authentication

Provide the shared secret in one of these ways (same value in both cases):

Method	How
Header (preferred)	`X-Api-Key: <secret>`
Query parameter	`?token=<secret>` on the same URL

The secret is configured for the monitoring service as CUSTOMER_API_KEY (set in deployment environment for prod / dev as appropriate). Do not expose this key in client-side or public code—call this API only from your backend.

Why prefer the header?

Query strings are more likely to show up in access logs (load balancers, proxies, API gateways), error reports, or referrer headers if a user follows a link. The header is still sent over HTTPS and is not weaker in transit, but it is usually a better choice for server-to-server calls. If you use token in the URL, treat logs and shared links as sensitive.

Missing or wrong key → 401 Unauthorized (response body indicates failure; do not rely on a specific JSON shape for errors).

Endpoint

GET /api/customer/{shopName}

shopName — Store hostname, e.g. my-store.myshopify.com. Use URL encoding in the path (e.g. if the name contains special characters).

Success (200) — JSON body wraps payload in a top-level envelope:

{
  "success": true,
  "data": {
    "shopName": "my-store.myshopify.com",
    "valueMessages": { },
    "auditChecks": [ ]
  }
}

`valueMessages`

Pre-written headline and body copy derived from monitoring’s ROI/value logic, plus related fields (e.g. notification text, email lines, optional “days to value” lines). Intended for display to merchants or internal users as-is.

If monitoring has not computed messaging for this store yet, valueMessages is null.
computedAt is an ISO 8601 timestamp when the copy was generated.

`auditChecks`

Array of current findings that need attention at info, warning, or error level only. Passed checks and “unknown / not enough data” outcomes are not listed.

Each item includes:

Field	Meaning
`check`	Stable identifier for the rule
`displayName`	Short human-readable label
`status`	Number from the shared `AuditStatus` wire enum: -1 UNKNOWN, 0 SUCCESS, 1 INFO, 2 WARNING, 3 ERROR. This endpoint only returns 1 / 2 / 3 (info, warning, error); SUCCESS and UNKNOWN rows are omitted here.
`destination`	Which integration area (e.g. analytics, ads, email platform)
`entityId`	Which connected resource the check applies to, when relevant
`eventName`	For rules scoped to a named event, when relevant
`updatedAt`, `resolvedAt`, `startedAt`	ISO 8601 timestamps when present

Not found (404) — No monitoring customer record exists for that shopName.

Server error (500) — Transient or unexpected failure; safe to retry with backoff.

Admin: customer health & contacts (separate auth)

The public CUSTOMER_API_KEY endpoint above is not used for these. They require a logged-in admin session (same as GET /customers).

Method	Path	Purpose
`GET`	`/customers`	Optional `?healthStage=Red\\|Yellow\\|Green`; includes health summary fields when present. Two consumers — see CIP_DASHBOARD_CONTRACT.md before narrowing its projection.
`GET`	`/customers/{shopName}`	Customer detail including `healthScore`, `healthStage`, `healthScoreChanges`, flags.
`GET`	`/customers/{shopName}/contacts`	Intercom contacts mirrored into the `contacts` collection.
`PUT`	`/customers/{shopName}/health-flags`	Body: `{ "hadRecentPositiveCall": boolean }` — CSM manual input for scoring.

See CUSTOMER_HEALTH.md for the scoring rules — what makes a customer Red, Yellow, or Green.

Example

Replace API_BASE, YOUR_KEY, and shop-name with real values.

Header (recommended):

curl -sS \
  -H "X-Api-Key: YOUR_KEY" \
  "https://API_BASE/api/customer/shop-name.myshopify.com"

Query parameter (when you cannot set headers):

curl -sS "https://API_BASE/api/customer/shop-name.myshopify.com?token=YOUR_KEY"

CORS

Cross-origin browser calls are constrained by the monitoring API’s allowed origins. Prefer server-to-server calls from your backend with the API key.