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

  1. Sign in at https://staging.inventori.cloud/login.
  2. Open /app/api-tokens and create a token.
  3. Copy the token — it is shown exactly once, then only its SHA-256 digest is kept.
  4. 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; honour Retry-After.

Endpoints

Account

  • GET /me
    Your account: id, username, email, name, sign-in provider, whether a password is set (has_password), MFA state, free-sheet state.
  • GET /account/export
    Download a zip of your whole account: account.json, items.json, containers.json, codes.json, orders.json, photos.json and your photo files. Same archive as /app/account/export in the browser.
  • POST /account/delete
    Delete the account and every row and photo file attached to it. An account with a password sends {"password"} (403 when the password is missing or wrong, nothing is deleted). An account without one sends {"confirm": "delete my account"} instead (400 when the text does not match). Answers {"status": "deleted", "before": {...}, "after": {...}, "photos_deleted": n}.

Items

  • GET /items
    List 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 /items
    Create an item on a blank official sticker. Body: {"code_id", "name", "note", "container"}. 201.
  • PATCH /items/{id}
    Change name, note or container. Omitted fields are untouched.
  • POST /items/{id}/photo
    Attach a photo as multipart/form-data field file (JPEG/PNG/WebP, 10 MB max).
  • GET /items/{id}/photo
    The stored photo bytes (or a redirect to object storage).
  • DELETE /items/{id}/photo
    Remove the photo. Also available as POST /items/{id}/photo/clear.

Containers

  • GET /containers
    List containers by name. Returns {"containers": [{"id", "name"}]}.
  • POST /containers
    Create one. Body {"name"}. 201, 409 if 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 /scan
    Resolve a full scanned QR payload URL instead of a bare code id. Body {"payload"}. Unsigned or foreign codes answer 400.

Orders and sheets

  • GET /orders
    Your orders, newest first, with the paid code ids.
  • GET /orders/{public_id}
    One order by its public id.
  • GET /orders/{public_id}/pdf
    The printable 30-up 1 in x 2-5/8 in PDF sheet, once the order is paid (402 before that).
  • POST /checkout
    Start checkout for a SKU. Body {"sku"}; returns a Stripe checkout_url, or a dev-mode pay link when DEV_MODE is on.
  • GET /products
    Public 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.