API Reference¶
Pantry Raider exposes a REST API used by the UI, Home Assistant, and any external integrations.
Interactive docs (Swagger UI) are available at /docs when the app is running.
Authentication¶
A browser signs in with the password and gets a session cookie. Everything
else, such as Home Assistant, a Bandit, a Bandit Cub, an ESP panel or your own
script, sends a key in the X-API-Key header:
curl -H "X-API-Key: YOUR_KEY" http://192.0.2.10:9284/expiring/summary
Keys are created in Settings, Security, Create a key, and each one is limited to one job. A new key is shown once, so copy it then.
| What it can do (as Settings shows it) | Scope | Reaches |
|---|---|---|
| A second screen (satellite) | satellite |
Every kitchen route, including Grocy and Mealie through /api/proxy/, but no Settings or admin routes |
| The Home Assistant integration | ha |
The /ha/ routes the integration uses and the /events/ notification routes |
| Home Assistant sensors, buttons and ESPHome panels | ha_rest |
Reading kitchen data (any GET outside Settings and admin), timers, /pending/scan, the scanner mode, /events/, and /gadgets/esp-action |
| A Bandit Cub or other small display | display |
/cub/summary, the Cub firmware, timers, /gadgets/esp-action and /gadgets/esp-screen |
| Everything, including Settings | admin |
Every route, including /setup/, /admin/ and backups |
| Everything except Settings (an older key) | legacy |
Keys from before 0.21: every route except Settings and admin routes |
- Settings (
/setup/...) and the/admin/routes take a signed-in owner or an admin key. Any other key gets403with a message saying so. An admin key can only be created on an install that has a password, needs that password to create, and expires after 90 days. - On an install with no password, any device on the home network can create a key without a password, and requests from the home network work without a key unless that kind of device is set to need one (Settings, Security, Require a key). Requests through a proxy or a tunnel are refused there.
GET /api/credentialslists the keys (never their values) with what each can do, when it was last used and where from.POST /api/credentialscreates one ({"name": ..., "scope": ..., "password": ...}) and returns the key once.POST /api/credentials/{id}/revokerevokes one andPOST /api/credentials/{id}/scopechanges what it can do. These take a signed-in owner or an admin key.- Pairing lets a device ask for its own key instead of you copying one:
POST /api/pairing/requestwith{"hostname": ..., "kind": ...}(a kind ofsatellite,ha,ha_restordisplay) returns a short code shown on the device, the owner approves the matching code on the kitchen screen or in Settings, Bandit Remotes, and the device collects its key fromGET /api/pairing/status/{request_id}. Pairing answers only the local network, and only while Settings, Security, Device pairing is on. POST /api/credentials/exchangelets a device that still holds an older full-access key swap it for a key of its own kind (today, the Home Assistant integration), from the home network only.
UI Routes¶
| Endpoint | Description |
|---|---|
GET /setup |
Web setup wizard |
GET /ui/ |
Inventory dashboard |
GET /ui/expiring |
Expiring items view |
GET /ui/add |
Manage (add, consume, shopping list, audit; barcode, photo, manual) |
GET /ui/pending |
Review: scanned and photographed items waiting for confirmation |
GET /ui/audit |
Pantry audit (stock count; scanning never writes back, corrections are opt-in) |
GET /ui/journal |
Stock journal (recent Grocy transactions) |
GET /ui/defaults |
Expiry defaults editor |
GET /ui/cook |
Recipe suggestions ranked by inventory |
GET /ui/recipes |
Browse and import recipes |
GET /ui/current-recipe |
On the Line: active recipe view with timers |
GET /ui/mealplan |
Week meal plan |
GET /ui/shopping |
Shopping list (kept in Grocy; Mealie where one is still in use) |
GET /ui/nutrition |
Nutrition / food-intake tracker |
GET /ui/camera |
Live camera feeds (shown when a camera is configured) |
GET /ui/weather |
Full forecast page for the kiosk |
GET /ui/convert |
Unit converter and measurement cheat sheet |
GET /ui/kitchen-guide |
Kitchen reference guide |
GET /ui/timers |
Time & Temp: shared kitchen timers and thermometer readings (?view=timers or ?view=thermometers for one or the other) |
GET /ui/start |
The home screen: the Glance grid by default, or the custom Start Page launcher |
GET /ui/about |
About and credits |
API Endpoints¶
| Endpoint | Description |
|---|---|
GET /health |
Connectivity and service status (the Grocy and AI checks are reused for up to 30 seconds) |
GET /expiring/summary |
Urgency counts for Home Assistant sensors |
GET /inventory/dashboard |
Full stock grouped by storage location |
GET /admin/version |
Running version string |
GET /admin/check-update |
Compare running version against the latest GitHub release |
GET /admin/backup |
Download app data as a zip archive |
POST /admin/restore |
Restore app data from an uploaded backup zip |
POST /admin/backup/remote |
Push backup to configured rclone remote |
POST /admin/backup/test-remote |
Test that rclone can reach the configured remote |
GET /admin/logging |
Report whether debug logging is on |
POST /admin/logging |
Turn debug logging on or off |
GET /admin/logs/download |
Download the debug log bundle with secret values redacted |
Current Recipe and Timers¶
The active recipe and timers live in server memory so every surface (web UI, Stream Deck, satellites) shares one state. On a Pi Remote the timer endpoints forward to the main server, so a timer started at any screen or deck shows up, can be extended, and can be cancelled everywhere.
| Endpoint | Description |
|---|---|
GET /current-recipe |
Return the active recipe (or null) |
POST /current-recipe |
Replace the active recipe |
DELETE /current-recipe |
Clear the active recipe |
POST /current-recipe/scale |
Set the servings-scale multiplier |
GET /current-recipe/timer-suggestions |
Timer suggestions parsed from the recipe's step durations |
POST /current-recipe/timers/start |
Start a real timer from a suggestion |
POST /current-recipe/from-mealie |
Load a Mealie recipe (by slug) as the active recipe |
GET /timers |
List every timer with fresh remaining/state |
POST /timers |
Create and start a timer for seconds |
GET /timers/{id} |
Return one timer's current state |
POST /timers/{id}/extend |
Add seconds to a running timer (the +1 min button; an expired timer cannot be extended) |
DELETE /timers/{id} |
Cancel and remove a timer |
DELETE /timers |
Clear every timer at once (the Clear all button) |
Barcode Scanning and Scanner Mode¶
A single physical scanner can mean different things depending on what the user is doing. The mode is shared by every screen and device and survives an app restart, so the scanner comes back in the mode it was left in. The Manage page's four mode tiles (Stock up, Use stock, Shopping list, Audit stock) are this same mode.
| Endpoint | Description |
|---|---|
POST /pending/scan |
Submit a scanned barcode; routed by the active scanner mode (inventory, consume, shopping, or audit) |
POST /pending/consume-link |
Link a barcode to a product, then use one up. A consume scan of an unlinked barcode replies with a suggested product and the body to send here once you confirm (barcode, product_id, quantity) |
GET /pending/scanner-mode |
Return the current scanner mode and its label |
POST /pending/scanner-mode |
Set the scanner mode |
POST /pending/scanner-mode/cycle |
Advance to the next mode (inventory then consume then shopping then audit, wrapping) |
Pantry Audit¶
A stock count. Scans are recorded against the active session and compared to
Grocy's stock for the chosen scope (all areas by default, or one storage
location); scanning never writes to Grocy. The one deliberate write is
POST /audit/apply, run only from the page's Apply corrections button after
a confirmation. On a satellite these forward to the main server.
| Endpoint | Description |
|---|---|
GET /audit/locations |
List storage locations to pick from |
POST /audit/start |
Begin an audit session (all areas, or locked to one location) |
POST /audit/scan |
Record a scanned item as seen for the session |
GET /audit/status |
Expected vs scanned, with missing and unexpected items (polled by the page) |
POST /audit/apply |
Opt-in corrections: set each counted item's stock to the scanned amount; items never scanned are left as they were |
POST /audit/stop |
End the session |
Nutrition / Food Intake¶
Logs what was eaten with calories and macros so the Nutrition page can show totals.
| Endpoint | Description |
|---|---|
POST /nutrition/log |
Record an intake entry (name, servings, calories, protein, carbs, fat) |
GET /nutrition/today |
Today's entries and totals |
GET /nutrition/recent?days=N |
Recent days with per-day totals |
DELETE /nutrition/{id} |
Delete an entry |
POST /nutrition/estimate |
Ask the AI provider to estimate macros for a food name (needs a provider) |
Weather¶
| Endpoint | Description |
|---|---|
GET /ui/weather/data |
Server-side forecast for the kiosk weather page (Open-Meteo, with wttr.in as a fallback); ?location= overrides the saved location |
Home Assistant On-Screen Events¶
Turned on by ha_events_enabled. Automations push toasts and camera pop-ups to
the device screen; the kiosk polls for them.
| Endpoint | Description |
|---|---|
POST /events/notify |
Show a notification toast on the screen |
POST /events/camera-popup |
Pop a named camera up full-screen for a few seconds |
POST /events/navigate |
Navigate the kiosk to a page: {"path": "ui/cook"} or a page name such as "expiring"; anything that is not a page is refused with a 400 |
POST /events/test |
Send a test notification |
GET /events/poll |
Long-poll for queued on-screen events (used by the kiosk) |
Recipe Import¶
| Endpoint | Description |
|---|---|
POST /mealie/recipes/import-url |
Import a recipe from a webpage (structured-data scraper, then LLM fallback) |
POST /mealie/recipes/import-file |
Import from a generic JSON / schema.org JSON-LD / Mealie export file |
POST /mealie/recipes/import-external |
Save an external-source recipe into the library |
POST /mealie/recipes/extract-photo |
Vision-LLM extraction from a photographed recipe |
POST /mealie/recipes/generate |
Ask the LLM to write a full recipe for a dish name |
Grocy Locations¶
The buttons on the two Grocy location items in the Pending inbox. Both are
Settings routes, so they take a signed-in owner or an admin key, and both
answer 403 on a Bandit, whose Grocy is the main server's. Each reads Grocy
again and does only what is still needed, so calling it twice is safe.
| Endpoint | Description |
|---|---|
POST /setup/grocy/merge-fridges |
Move everything in Grocy's Fridge to Refrigerator, point products at Refrigerator, then hide Fridge (never deleted) |
POST /setup/grocy/mark-freezer |
Mark the Freezer location as a freezer in Grocy |
Both answer {"ok": true, "message": ...} when done. A merge that could not
hide Fridge yet (stock Grocy would not move) answers 409, and one Grocy
refused answers 502; both carry the reason in error.
Appliance (Pi-only)¶
These call the host bridge on a Pi appliance and return a clear error elsewhere.
| Endpoint | Description |
|---|---|
POST /setup/restore |
Full Grocy + Mealie + app snapshot restore via the host bridge |
POST /setup/restore is distinct from POST /admin/restore: the former restores
the whole stack (Grocy, Mealie, app data) from a snapshot already on the device
(an absolute .tar.gz path or rclone:<remote-path>), while /admin/restore
rewrites only this app's data directory from an uploaded zip. The host bridge
itself exposes a POST /restore it proxies to, but this file documents the app API.
Query Parameters¶
GET /ui/expiring?days=N: show items expiring within N days (default 7).
GET /admin/backup?include_secrets=true: include API keys and passwords in the backup zip (omit for a safe-to-store redacted copy).
GET /inventory/dashboard returns JSON matching the Grocy stock structure, grouped by storage category. This is the endpoint the Home Assistant Lovelace dashboard polls.
GET /inventory/dashboard?dates=breakdown: the Inventory page's own reading of the same rows. A row whose stock in that place has more than one best-by date also carries best_by_dates, a list of {"best_before_date", "amount"} with the earliest date first and undated stock (null) last. Each row's amount, amount_opened and best_before_date then come from that place's own stock entries, and a product with no stock of its own (a parent product whose stock all sits in its sub-products) is left out. Without dates, or with any other value, the reply is unchanged.
GET /inventory/dashboard?dates=split: a place that holds more than one best-by date for a product gets a row for each date instead. Such a row carries "by_date": true, its own amount, amount_opened, best_before_date, days_remaining, urgency and added_date, and stock_entry_id, the Grocy stock entry a label printed from the row points at; product_amount stays the product's total. A place with a single date, and stock with no location, keep one row without these keys, as in breakdown. dates=auto, which the Inventory page sends, reads like split while One row per best-by date (Settings, Inventory) is on, the default, and like breakdown when it is off.
The buttons on a by_date row name its place and date, so they touch only that stock: POST /inventory/consume/{id}?amount=N&location_id=L&best_before_date=D, POST /inventory/open/{id}?location_id=L&best_before_date=D, PATCH /inventory/edit/{id} with from_location_id and from_best_before_date in the body (the new date stays in best_before_date, and a category still applies to the whole product), and POST /inventory/move/{id} with from_best_before_date next to from_location_id. The date D is YYYY-MM-DD, or none for the stock with no best-by date, and always comes with a location; a malformed date, or one without a location, answers 422. When Grocy cannot act on exactly that stock, for example because it would use an opened item or an earlier date first, the call answers 409 with the reason in detail (such as "Grocy would use an opened one first, so nothing was used.") and changes nothing; when the row's stock is gone it answers 404. A consume answers how much was consumed of the requested amount, with complete false when Grocy stopped partway; an open answers the new_best_by of the opened item, and a move what was left_behind. The page's Edit window also sends from_location_id and from_best_before_date for a plain row whose place holds one best-by date, so a changed date reaches only that place's stock. POST /inventory/move/{id} also takes an optional amount next to from_location_id, with or without from_best_before_date, and then moves only that much: the stock Grocy would use first goes first, only the part that moves gets a new best-by date, and left_behind counts only what was asked for and did not move. An amount of at least what is there moves all of it, and one of 0 or less, or one sent without from_location_id, answers 422. Without these parameters every call works as before.
GET /expiring/summary returns urgency bucket counts:
{
"expired": 2,
"today": 0,
"3d": 3,
"ok": 14
}
See the live /docs page for full request/response schemas.