Documentation
The Inventori API
A plain JSON HTTP API over your own inventory. Everything is scoped to the account that owns the token: there is no endpoint that lets you read somebody else's items.
Machine-readable schema: /api/v1/openapi.json (public, no account data).
Base URL
https://staging.inventori.cloud/api/v1
All paths below are relative to that. The deployment answers on HTTPS only; plain HTTP requests are redirected.
Authentication
- Sign in at https://staging.inventori.cloud/login.
- Open /app/api-tokens and create a token.
- Copy the token — it is shown exactly once, then only its SHA-256 digest is kept.
- Send it on every request:
Authorization: Bearer inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Tokens do not expire, but they can be revoked at any time from that same page, and revocation is immediate. A browser session token is also accepted on the same header; that is what the web app and the mobile app use, and it expires after 30 days.
Rate limit
60 requests per minute per token. Over the limit the API answers 429 Too Many Requests with a Retry-After header, in seconds. The window is rolling, so a slow, steady client never hits it.
Errors
Every error is JSON with one human-readable detail string:
{"detail": "item not found"}
400— the sticker code is not an official Inventori code, or unknown.401— no token, an unknown token, or a revoked token.{"detail": "sign in required"}402— the order is not paid yet.403— the object belongs to another account.404— no such item, container or order in your account.409— conflict, e.g. that sticker already has an item, or the container name exists.422— the body failed validation (field missing, name empty, bad container name).429— rate limited; honourRetry-After.
Endpoints
Account
- GET /meYour account: id, username, email, name, sign-in provider, whether a password is set (
has_password), MFA state, free-sheet state. - GET /account/exportDownload a zip of your whole account:
account.json,items.json,containers.json,codes.json,orders.json,photos.jsonand your photo files. Same archive as/app/account/exportin the browser. - POST /account/deleteDelete the account and every row and photo file attached to it. An account with a password sends
{"password"}(403when the password is missing or wrong, nothing is deleted). An account without one sends{"confirm": "delete my account"}instead (400when the text does not match). Answers{"status": "deleted", "before": {...}, "after": {...}, "photos_deleted": n}.
Items
- GET /itemsList your items, most recently updated first. Optional
?q=filters on name, note, container or sticker code. Returns{"items": [...]}. - GET /items/{id}One item:
id,code_id,name,note,container,photo_key,photo_url. - POST /itemsCreate an item on a blank official sticker. Body:
{"code_id", "name", "note", "container"}.201. - PATCH /items/{id}Change
name,noteorcontainer. Omitted fields are untouched. - POST /items/{id}/photoAttach a photo as
multipart/form-datafieldfile(JPEG/PNG/WebP, 10 MB max). - GET /items/{id}/photoThe stored photo bytes (or a redirect to object storage).
- DELETE /items/{id}/photoRemove the photo. Also available as
POST /items/{id}/photo/clear.
Containers
- GET /containersList containers by name. Returns
{"containers": [{"id", "name"}]}. - POST /containersCreate one. Body
{"name"}.201,409if the name exists. - GET /containers/{id}One container.
- PATCH /containers/{id}Rename. Items that used the old name move with it.
- DELETE /containers/{id}Delete the container. Items keep their name and container string.
Sticker codes
- GET /codes/{code_id}Resolve a 16-character official code id (the uppercase code printed under the QR). Returns
{"code_id", "official", "status": "blank"|"item", "item"}. - POST /scanResolve a full scanned QR payload URL instead of a bare code id. Body
{"payload"}. Unsigned or foreign codes answer400.
Orders and sheets
- GET /ordersYour orders, newest first, with the paid code ids.
- GET /orders/{public_id}One order by its public id.
- GET /orders/{public_id}/pdfThe printable 30-up 1 in x 2-5/8 in PDF sheet, once the order is paid (
402before that). - POST /checkoutStart checkout for a SKU. Body
{"sku"}; returns a Stripecheckout_url, or a dev-mode pay link when DEV_MODE is on. - GET /productsPublic price list and sheet sizes. No auth needed.
A first request
List what is in a container called Garage:
curl -s \
-H "Authorization: Bearer $INVENTORI_TOKEN" \
"https://staging.inventori.cloud/api/v1/items?q=garage"
Create an item on a blank sticker, then resolve that sticker by its code id:
curl -s -X POST \
-H "Authorization: Bearer $INVENTORI_TOKEN" \
-H "Content-Type: application/json" \
-d '{"code_id":"ABCD2345EFGH6789","name":"Camping stove","container":"Garage"}' \
"https://staging.inventori.cloud/api/v1/items"
curl -s -H "Authorization: Bearer $INVENTORI_TOKEN" \
"https://staging.inventori.cloud/api/v1/codes/ABCD2345EFGH6789"
A successful create answers 201 with the item JSON. A sticker that already has an item answers 409; a code that was not printed by us answers 400 not an official Inventori sticker.