API reference

Authentication

The ShelfReady API uses bearer API keys over HTTPS. All requests must be authenticated.

API keys

Create keys in Dashboard → Settings → API keys. Keys look like sr_ followed by 64 hex characters and are shown once at creation — only a hash is stored, so a lost key must be replaced, not recovered.

Treat keys like passwords. Never commit them or expose them in client-side code.

Authenticating requests

Pass the key as a bearer token in the Authorization header on every request.

bash

curl https://useshelfready.com/api/v1/products \
  -H "Authorization: Bearer $SHELFREADY_API_KEY"

Scopes

Every key carries one or both scopes: read (list products, syncs, feeds, audit results, webhooks) and write(push catalog items, trigger syncs, re-render feeds, run audits, manage webhooks). Each endpoint's reference page states the scope it requires.

Errors

All errors share one JSON shape:

error.json

{ "error": { "status": 403, "message": "this key lacks the \"write\" scope" } }

401 — missing, malformed, invalid, or revoked API key.
403 — the key lacks the required scope.
429 — rate limit exceeded.

Rate limits

Each key is limited to 60 requests per minute (sliding window). Exceeding the limit returns 429 Too Many Requests with a Retry-After header giving the seconds to wait.

OpenAPI spec

The full API is described by a machine-readable OpenAPI 3.1 document at /api/v1/openapi.json — use it to generate clients or import the API into your tooling.