Developers

Quickstart

From a scoped key to your first request, paged results, a queued import, and receiving changes.

1. Create a scoped key

In Settings → API keys, create a key with only the scopes you need (start with items:read), copy the secret once, and store it in a secret manager — never in code, URLs, or browser JavaScript.

export ITEMRA_API_KEY="itemra_live_replace_me"

2. First request

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

Collections return data plus page; pass page.nextCursor as the next request's cursor until it's exhausted.

3. First write — with idempotency

curl -sS -X POST "https://api.itemra.io/v1/stock/adjustments" \
  -H "Authorization: Bearer $ITEMRA_API_KEY" \
  -H "Idempotency-Key: adj-2026-08-30-001" \
  -H "Content-Type: application/json" \
  -d '{ "sourceStockRecordId": "…", "direction": "down", "delta": 2, "reason": "damaged" }'

The Idempotency-Key is required on writes — pick a stable id per logical operation and reuse it only for exact retries.

4. Queue a CSV import

curl -sS "https://api.itemra.io/v1/imports/kinds" \
  -H "Authorization: Bearer $ITEMRA_API_KEY"

curl -sS -X POST "https://api.itemra.io/v1/imports/jobs" \
  -H "Authorization: Bearer $ITEMRA_API_KEY" \
  -H "Idempotency-Key: item-import-20260830-001" \
  -F "kind=items" -F "duplicateStrategy=create-only" \
  -F "file=@items.csv;type=text/csv"

Poll the Location URL from the response; the /errors child route returns stable row-level error codes after completion.

5. Receive changes

Prefer webhooks for push; where you can't receive, poll the events feed with events:read. For typed clients and Postman, grab the SDK kit. On 429, honor Retry-After; keep the traceId from any error you report.