Developers

API overview

The Customer API: base URL, bearer authentication, scopes, sandbox, versioning, pagination, idempotency, rate limits, and errors.

Base URL and reference

https://api.itemra.io

The interactive reference lives at api.itemra.io/scalar/v1, and the governed OpenAPI contract at api.itemra.io/openapi/v1.json. All routes are versioned under /v1; the contract is change-controlled, breaking changes require a new version, and deprecations are announced with standard deprecation headers well in advance.

Authentication

Requests authenticate with a bearer key from Settings → API keys:

curl -sS "https://api.itemra.io/v1/items?limit=10&sort=name" \
  -H "Authorization: Bearer $ITEMRA_API_KEY"

A key can only call endpoints its scopes allow (items:read, stock:write, …); tenant plan capabilities and per-key security (IP allowlists, expiry) still apply on top. Dev-environment keys (itemra_dev_…) operate against an isolated sandbox dataset, so integration development never touches live inventory.

Pagination, filtering, sorting

Collections return data plus cursor metadata under page. Send page.nextCursor back as cursor for the next page — cursors are opaque and tenant-bound; never construct or decode them. Filterable fields and sort keys are documented per endpoint in the reference.

Idempotency

Every mutating endpoint that documents it requires an Idempotency-Key header: a stable unique value per logical operation. Retry the exact same body with the same key after an ambiguous timeout; the same key with a different body is rejected. This is what makes retries safe.

Rate limits

Default: 1,200 requests per minute per key, with a stricter submission policy (20/min) on heavy endpoints such as import job creation. On 429, honor Retry-After. Per-key overrides can be configured with the key.

Errors

Errors are RFC 7807 problem documents with a stable machine code and a traceId:

{
  "status": 400,
  "detail": "Unsupported sort field.",
  "code": "validation.failed",
  "traceId": "f00d4b9b4b6d…",
  "params": { "field": "sort" }
}

Branch on code, not on detail text, and keep the traceId when contacting support.

Continue with the quickstart, the resource tour, the events feed, and webhook verification.