API overview

The eCommerce Insights API is in early access. It exposes catalogue data, scores, recommendations, Prompt Runs sessions, alerts, and run history. Authentication is bearer-token; rate limits are per-workspace; pagination is cursor-based.

Status

Early access. To get a key, email [email protected] with your workspace ID and a one-sentence use case. We approve manually during early access.

Base URL

https://api.ecommerceinsights.ai/v1

Authentication

Bearer token in the Authorization header.

curl https://api.ecommerceinsights.ai/v1/catalog \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate limits

120 requests per minute per workspace, with burst capacity of 300. Heavy-read workloads (BI dashboards, data warehousing) can request elevation through support. Rate-limit headers are present on every response:

X-RateLimit-Limit:     120
X-RateLimit-Remaining: 87
X-RateLimit-Reset:     1716636000

On rate-limit exceeded, the API returns 429 with a Retry-After header.

Pagination

Cursor-based. Pass limit (max 200) and cursor (opaque string from the previous response).

{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "eyJsYXN0X2lkIjoiMTIzNCJ9",
    "has_more": true
  }
}

Error model

HTTP status plus a JSON body with code (machine-readable string) and message (human-readable). Example:

{
  "error": {
    "code": "sku_not_found",
    "message": "The SKU 'VRN-AC1' was not found in workspace 'ws_abc123'.",
    "details": { "sku": "VRN-AC1", "workspace": "ws_abc123" }
  }
}

Available resources

/catalog

List, get, and update products. Bulk import via CSV upload also via API.

/scores

Current and historical PDP / Rufus scores per SKU. Includes bucket and criterion detail.

/recommendations

Open and applied Listing rewrite capsules.

/prompt-runs

Sessions, individual responses, and triggering new sessions.

/alerts

Alert rules (CRUD) and fire history.

/personas

Persona clusters and per-review assignments.

/jobs

Async job status for audits and Prompt Runs sessions.

See the endpoint reference for detailed schemas.

Common questions