Ingredient API

Authentication

Reads are public. Writes (POST, PATCH, PUT, DELETE) will require user auth later. Until then they check an optional API key so you can lock the catalog down without changing URLs.

• If API_WRITE_KEY is unset, writes succeed (local development).
• If it is set, send Authorization: Bearer <key> or X-API-Key: <key>.
• A missing or wrong key returns 401 with {"error":"unauthorized"}.

Search

Use q on the list endpoint, or GET /api/search which requires q. Matching covers name, scientific name, description, aliases, and a trigram similarity fallback. Results are ranked by similarity unless you pass sort.

GET /api/ingredients?q=tilapia
GET /api/search?q=crème+fraîche
GET /api/search/suggest?q=gou

Suggest needs at least two characters and returns up to ten {id, slug, name, category, energy_kcal} hits for typeahead.

How to filter

All filters are query parameters on GET /api/ingredients (and /api/search). Combine freely. Tags are AND; cuisines are OR. Nutrition values are per 100 g. form=fresh also matches stored raw.

GET /api/ingredients?category=fish&form=fresh&cuisine=ugandan
GET /api/ingredients?cuisines=dutch&cuisines=belgian&sort=name
GET /api/ingredients?tags=vegan&exclude_allergen=gluten&max_kcal=150
GET /api/ingredients?q=pepper&min_protein=15&order=desc&sort=protein

The list response is {page, per_page, pages, total, data[]}. Each card includes category, cuisines, tags, allergens, aliases, image URLs, and macros.

Ingredient CRUD

Look up by numeric id or slug. Names are unique ignoring case and surrounding space.

POST /api/ingredients
Content-Type: application/json

{
  "name": "Witlof",
  "category": "leafy-greens",
  "typical_form": "fresh",
  "description": "Belgian endive for stews and salads.",
  "cuisines": [{"slug": "belgian", "primary": true}, {"slug": "dutch"}],
  "tags": ["vegan", "fresh"],
  "allergens": [],
  "aliases": ["witloof", "Belgian endive"],
  "energy_kcal": 17,
  "protein_g": 0.9,
  "fat_g": 0.1,
  "carbs_g": 4.0,
  "sugars_g": 0.7,
  "fiber_g": 3.1,
  "sodium_mg": 2,
  "nutrition_estimated": true
}

category is a slug. cuisines, tags, allergens, and aliases replace the whole list when sent. PATCH only changes keys you include.

Reference data

Use these to populate filter chips. POST creates a row (same write-key rules). GET on a slug returns that row plus a page of ingredients.

GET  /api/categories
GET  /api/categories/fish
POST /api/categories          {"name":"Wild herbs","parent":"produce"}

GET  /api/cuisines
GET  /api/cuisines/dutch
POST /api/cuisines            {"name":"Dutch","region":"Europe"}

GET  /api/tags
POST /api/tags                {"name":"High iron","type":"nutrition"}

GET  /api/allergens
POST /api/allergens           {"name":"Lupin"}

GET  /api/forms
GET  /api/stats
GET  /api/health