# 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](/openapi.json) and an interactive explorer is at [/docs](/docs).

All endpoints below except sign-up and sign-in need `Authorization: Bearer <token>`. See
[Authentication](/help/auth) 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.
