API reference
The REST API lives under /api on the same host as the app. Requests and responses are JSON. The full, machine-readable description is at /openapi.json and an interactive explorer is at /docs.
All endpoints below except sign-up and sign-in need Authorization: Bearer <token>. See Authentication for how to get a token.
Recipes
| Method | Path | What it does |
|---|---|---|
| GET | /api/recipes?search=lentil&perPage=10 | Search your recipes. Returns items and total. |
| GET | /api/recipes/{slug} | One recipe with ingredients and instructions. |
| POST | /api/recipes/create/url | Import from a web page. Body {"url": "https://..."}. Returns the new slug. |
| POST | /api/recipes | Create an empty recipe. Body {"name": "Soup"}. Returns the slug. |
| DELETE | /api/recipes/{slug} | Delete a recipe. |
Example, importing a recipe:
curl -X POST https://kitchen.phineus.ai/api/recipes/create/url \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"url": "https://example.org/recipes/lentil-soup"}'
Shopping lists
| Method | Path | What it does |
|---|---|---|
| GET | /api/households/shopping/lists | Your shopping lists. |
| POST | /api/households/shopping/lists | Create a list. Body {"name": "Weekend"}. |
| POST | /api/households/shopping/items | Add an item. Body {"shoppingListId": "...", "note": "lemons", "quantity": 2}. |
| GET | /api/households/shopping/items?perPage=50 | All items across lists. |
Meal plans
| Method | Path | What it does |
|---|---|---|
| GET | /api/households/mealplans | Planned meals. |
| POST | /api/households/mealplans | Plan a meal. Body {"date": "2026-12-01", "entryType": "dinner", "recipeId": "..."}. |
Errors
Errors are JSON with an HTTP status: 401 for a missing or rejected token, 403 for something you may not do, 404 for something that does not exist and 422 for a request body that failed validation, with the offending fields listed in detail.
Limits
The Free plan has no request quota for individual use; please keep automated traffic polite.
Phineus Kitchen is a demo product run for testing. Nothing here is real or paid.