This page exists in one language only. Some pages here are English, some Swedish.

Public Intake API

Use this API to submit source data to Stockisto's ingestion pipeline. It is a separate credential class from the tenant read and write API, and every batch lands in a staging store before anything reaches live data.

Get the right key

A StockistoAdmin issues an intake key for one tenant. The key carries the isolated api:intake scope and travels in the X-API-Key header. A tenant Developers key with api:read or api:write cannot call this API, and an intake key cannot call the tenant read or write endpoints.

At issuance the StockistoAdmin binds the key to one source: scraper, delegated or crowd. The envelope's source and every record-level provenance.source must match that binding. The key is shown once; keep it in your server-side secret store. A key may carry an expiry date, and a revoked or expired key answers 401 like an unknown one.

Submit a batch

Use the v1 envelope. Replace only the angle-bracket placeholders. The example uses scraper; use the source bound to your own key.

curl -X POST https://api.test.stockisto.com/api/public/v1/intake/batches \
  -H "X-API-Key: <YOUR_INTAKE_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "contractVersion": "1.0",
    "source": "scraper",
    "idempotencyKey": "<UNIQUE_BATCH_KEY>",
    "records": [
      {
        "kind": "retailer-company",
        "naturalKey": "<UNIQUE_RETAILER_KEY>",
        "payload": { "name": "<RETAILER_NAME>" }
      }
    ]
  }'

A new batch returns 202 Accepted with the batch id and a status link. A retry with the same idempotencyKey from the same key returns 200 with the existing batch and stages nothing again.

Envelope fields

A record that fails validation is rejected on its own and listed under the batch's validationErrors. The rest of the batch continues. The whole batch is refused only when the envelope is invalid or every record fails.

Read a batch back

GET /api/public/v1/intake/batches/<BATCH_ID>

GET /api/public/v1/intake/batches lists the batches this key submitted. A batch submitted by another key is reported as unknown, even when it belongs to the same tenant.

Batch statuses: received, validated, staged, in_review, applied, partially_applied, rejected.

The review gate

Batches from scraper, delegated and crowd sources stop at in_review until a Stockisto operator approves them, unless the operator has granted your tenant and source an auto-apply trust flag. A batch whose changes would remove an unusually large share of live rows is always held for review. Read status, not the record count, to know whether a batch reached live data.

Optionally, the StockistoAdmin registers an https callback URL with your key. When a batch reaches applied, partially_applied or rejected, a signed import.completed delivery is sent there.

Operations

Limits

A rate-limit refusal returns 429 with Retry-After. A daily-quota refusal returns 429 with error: "intake_quota_exceeded" and a quota object that carries the limits, today's usage and resetAt. A retry of a batch you already submitted still answers 200, even when the quota is exhausted.

Diagnose a response