API Reference

🔌 API Reference

EverShelf exposes a single PHP endpoint: api/index.php. All actions are selected via the action query parameter.

Full OpenAPI 3.1 spec: docs/openapi.yaml

---

Base URL

https://your-server/api/index.php?action=ACTION_NAME

GET requests pass parameters as query params; POST requests send JSON in the body.

---

Rate Limits

Tier	Limit	Applies to
Standard	120 req/min	All general endpoints
AI	15 req/min	gemini_*, generate_recipe*
Strict	5 req/min	report_error

Exceeded limits return HTTP 429 with {"error": "rate_limit_exceeded"}.

---

Products

search_barcode — GET

Search for a product in the local database by barcode.

Param	Type	Description
barcode	string	EAN/UPC barcode

lookup_barcode — GET

Look up a barcode on Open Food Facts (external call).

Param	Type	Description
barcode	string	EAN/UPC barcode

product_save — POST

Create or update a product. Pass id to update.

{
  "id": 42,
  "name": "Pasta Barilla",
  "brand": "Barilla",
  "category": "pasta",
  "unit": "g",
  "default_quantity": 500,
  "barcode": "8076800105988"
}

product_get — GET

Get product details by id.

product_delete — POST

Delete a product by id.

products_list — GET

List all products.

products_search — GET

Search products by name (?q=pasta).

---

Inventory

inventory_list — GET

List all inventory items with product details, grouped.

Response:

{
  "inventory": [
    {
      "id": 1,
      "product_id": 42,
      "name": "Pasta Barilla",
      "quantity": 2,
      "unit": "pz",
      "location": "dispensa",
      "expiry_date": "2027-03-01",
      "opened_at": null,
      "vacuum_sealed": 0
    }
  ]
}

inventory_add — POST

Add a product to inventory.

{
  "product_id": 42,
  "quantity": 3,
  "location": "dispensa",
  "expiry_date": "2027-03-01",
  "vacuum_sealed": false
}

Locations: dispensa, frigo, freezer, altro

inventory_use — POST

Consume inventory. Set use_all: true to consume all stock at a location.

{
  "product_id": 42,
  "quantity": 1,
  "location": "dispensa"
}

{
  "product_id": 42,
  "use_all": true,
  "location": "__all__",
  "notes": "Buttato"
}

inventory_update — POST

Update an inventory entry by id.

inventory_delete — POST

Remove an inventory entry by id.

inventory_summary — GET

Returns item counts per location.

{
  "dispensa": 12,
  "frigo": 5,
  "freezer": 8
}

---

Transactions (Log)

transactions_list — GET

Returns the operation log.

Param	Type	Default	Description
limit	int	50	Results per page
offset	int	0	Pagination offset

transaction_undo — POST

Undo a transaction within 24 hours.

{ "id": 873 }

Response on success:

{ "success": true, "name": "Tonno all'olio d'oliva" }

Error cases:

{ "error": "...", "already_undone": true }
{ "error": "...", "too_old": true }

stats — GET

Returns waste and consumption statistics for the last 30 days.

---

AI / Gemini

All AI endpoints require GEMINI_API_KEY to be configured. Rate limit: 15 req/min.

gemini_expiry — POST

Read an expiry date from a product photo.

{ "image": "data:image/jpeg;base64,..." }

gemini_identify — POST

Identify a product from a photo.

{ "image": "data:image/jpeg;base64,..." }

gemini_chat — POST

Chat with the AI kitchen assistant.

{ "message": "Cosa posso fare con la pasta?", "history": [] }

generate_recipe — POST

Generate a recipe based on current inventory.

{ "persons": 2, "meal": "dinner", "preferences": {} }

generate_recipe_stream — POST

Same as generate_recipe but streams output via Server-Sent Events.

gemini_product_hint — POST

Get AI storage location + shelf-life hint for a new product.

gemini_shopping_enrich — POST

Enrich shopping suggestions with practical tips.

gemini_anomaly_explain — POST

Get a plain-language explanation for a specific inventory anomaly.

---

Shopping List (Bring!)

Requires BRING_EMAIL and BRING_PASSWORD in .env.

bring_list — GET

Get the current Bring! shopping list.

bring_add — POST

Add items to the Bring! list.

{ "items": ["Latte", "Pane"] }

bring_remove — POST

Remove an item from the Bring! list.

{ "name": "Latte" }

smart_shopping — GET

Get smart shopping predictions based on consumption history.

---

Settings

get_settings — GET

Returns current settings as boolean flags only (no raw key values):

{
  "gemini_key_set": true,
  "bring_configured": false,
  "tts_enabled": false,
  "scale_enabled": true,
  "demo_mode": false,
  "settings_token_set": true
}

save_settings — POST

Update server configuration. If SETTINGS_TOKEN is set, requires header:

X-Settings-Token: your_token

{
  "gemini_api_key": "...",
  "bring_email": "...",
  "scale_enabled": true,
  "scale_gateway_url": "ws://127.0.0.1:8765"
}

---

Error Reporting

report_error — POST

Submit an automatic error report (creates a GitHub Issue).

{
  "type": "uncaught-error",
  "message": "...",
  "stack": "...",
  "context": {}
}

Only creates an issue if:

• The client is running the latest released version
• The fingerprint hasn't been seen in the last 24 hours

---

Anomaly Detection

inventory_anomalies — GET

Returns inventory rows where stored quantity significantly differs from transaction history.

dismiss_anomaly — POST

Dismiss an anomaly banner without changing inventory.

---

Scale Integration

scale_relay (SSE) — GET

Relays BLE scale readings from the gateway to the browser via Server-Sent Events (avoids HTTPS→WS mixed-content issues).

scale_ping — GET

Check if the Scale Gateway is reachable.

scale_discover — GET

Scan the local LAN for a running Scale Gateway instance.