Public API documentation

Public API access requires an eligible plan and a key scoped to your inventory. Create and revoke keys in Settings. Send keys only over HTTPS and keep them out of browser code.

Authentication

Authorization: Bearer YOUR_API_KEY

Inventory tokens can have inventory:read and inventory:write. Custom customers can issue an owner token with agent:run for operational reviews.

Read the activity log

On Custom, the inventory owner can issue a key with audit:read for GET /api/v1/public/audit. Filter with from, to, or q. Send the returned nextCursor as after to read the next page.

Run an Agent review

POST /api/v1/public/agent/jobs
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_OPERATION_KEY

{"review":"stock-health","filter":"YOUR_SKU"}

Use the returned job ID with GET /api/v1/public/agent/jobs/JOB_ID and the same token to read its status and result. Reviews use the registered jobs in Agent reviews. To run a report you own, send {"review":"saved-report","reportId":"REPORT_ID","page":1}. Use the ID from the saved report’s URL. An optional signed agent.review.completed webhook contains the job ID.

Start an Agent job

POST /api/v1/public/agent/jobs
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_OPERATION_KEY

{"job":"plan-van-routes"}

On Custom, the same token starts agent work: plan-van-routes, take-slow-stock-steps, fix-product-data, sort-new-products, retire-discontinued-products, warn-before-expiry, add-landed-costs, book-repeat-pallet-pickups, prepare-export-papers, or run-playbook with "playbook":"PLAYBOOK_ID". Each job runs through its own settings, job mode and limits. Work that always needs a person, such as paying a supplier, refunds, price changes or write-offs, comes back as waiting_for_person and waits in Needs you. Pause, Watch only and the first 14 days hold the job. Resending the same Idempotency-Key returns the first result. A token can start 30 jobs an hour. Signed agent.job.completed, agent.job.held and agent.job.failed webhooks carry the job ID, its status and what waits.

Read stock

GET /api/v1/public/inventory?limit=200

The response contains data with skuId, code, name, locationId, location, and onHand. Request up to 500 positions per page. Pass the returned nextCursor as cursor until it is null. Preserve the cursor as returned; do not construct it.

Receive physical stock

POST /api/v1/public/commands/inventory/receive
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_OPERATION_KEY

{"skuId":"YOUR_SKU_ID","locationId":"YOUR_LOCATION_ID","quantity":5,"reference":"Delivery reference"}

Lot-tracked stock also needs its lot details; serialized stock needs the exact serials. A physical receipt alone does not establish purchase cost or create a supplier invoice. Use the purchasing workflow when recording a purchase.

Count physical stock

POST /api/v1/public/commands/inventory/adjust
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_OPERATION_KEY

{"skuId":"YOUR_SKU_ID","locationId":"YOUR_LOCATION_ID","countedQuantity":5,"reasonCode":"physical_count"}

The count command is for quantity-tracked products. Reducing fully costed stock also reduces its recorded value. Added units need purchase-cost evidence through the purchasing or opening-stock workflow; a count is not a supplier invoice.

Signed webhooks

Create endpoints in Settings → Connections → Developers. Supported events are stock.changed, purchase_order.received and order.created. The body contains id, type, workspaceId, occurredAt and data. Quantities in stock events are decimal strings.

Verify X-StockChief-Signature: v1=HEX against HMAC-SHA256 with your signing secret and the exact UTF-8 string X-StockChief-Timestamp + "." + raw_request_body. Compare signatures in constant time, reject timestamps more than five minutes old, and deduplicate by X-StockChief-Event-Id. Parse JSON only after signature verification. Return a 2xx response after durably accepting the event.

Delivery is at least once, with up to 12 automatic attempts. The event ID and body remain stable across retries; signatures use the current attempt timestamp. Endpoints require public HTTPS, redirects are not followed, and each request has a 10-second timeout. Up to 10 active endpoints are allowed per inventory. Delivery remains subject to API access and API-event allowance; failed attempts do not consume the reserved allowance. Revoking an endpoint stops queued deliveries; a request already in flight may finish.

Retries and errors

Write commands require an idempotency key. Reuse the same key and identical body after an uncertain response. A successful first write returns 201; replay returns 200. Error responses use {"error":{"code":"…","message":"…"}}. Invalid input, expired keys, insufficient scopes, and plan limits must be resolved before retrying.