formulation/docs/api-guide.md

Formulation REST API Guide

Formulation exposes HTTP JSON endpoints for external systems, webhooks, and programmatic integrations.

REST Web API Specification (/api/v1/)

All REST endpoints return standard JSON envelopes:

• Success: { "success": true, "data": ... }
• Error: { "success": false, "error": "Description" }

Recipes

List Recipes

GET /api/v1/recipes?q=biscotti&limit=10

Get Recipe Details & Dynamic Scaling

GET /api/v1/recipes/chocolate_biscotti?scale=2

Calculate Scaled Quantities

POST /api/v1/recipes/chocolate_biscotti/scale
Content-Type: application/json

{
  "target_yield": 100,
  "target_yield_unit": "each"
}

Itemized Cost Rollup

GET /api/v1/recipes/chocolate_biscotti/cost?currency=USD

Nutrition Facts Rollup

GET /api/v1/recipes/chocolate_biscotti/nutrition

Create Recipe

POST /api/v1/recipes
Content-Type: application/json

{
  "title": "Vanilla Glaze",
  "yield_quantity": 250,
  "yield_unit_id": "gram",
  "yield_servings": 10,
  "categories": ["sauce"],
  "components": [
    {
      "name": "Main",
      "items": [
        { "ingredient_id": "confectioners_sugar", "quantity": 200, "unit_id": "gram" },
        { "ingredient_id": "milk", "quantity": 45, "unit_id": "gram" },
        { "ingredient_id": "vanilla_extract", "quantity": 5, "unit_id": "gram" }
      ]
    }
  ],
  "steps": [
    { "instruction": "In a medium bowl, whisk confectioners sugar, milk, and vanilla extract until smooth." }
  ]
}

Update Recipe

PUT /api/v1/recipes/vanilla_glaze

Archive Recipe

DELETE /api/v1/recipes/vanilla_glaze

---

Ingredients

List Ingredients

GET /api/v1/ingredients?q=sugar&limit=10

Get Ingredient Details

GET /api/v1/ingredients/sugar

Create Ingredient

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

{
  "name": "Matcha Powder",
  "description": "Ceremonial Japanese green tea powder",
  "categories": ["tea", "flavoring"],
  "tags": ["japanese", "beverage"],
  "aliases": [{ "name": "Matcha" }],
  "density": {
    "mass_quantity": 60,
    "mass_unit_id": "gram",
    "volume_quantity": 0.25,
    "volume_unit_id": "cup_us"
  }
}

Update Ingredient

PUT /api/v1/ingredients/matcha_powder

Archive Ingredient

DELETE /api/v1/ingredients/matcha_powder

(Fails safely with HTTP 409 Conflict if ingredient is referenced by active recipes.)

---

Recipe Books / Collections

List Recipe Books

GET /api/v1/collections

Get Recipe Book

GET /api/v1/collections/baking_essentials

Create Recipe Book

POST /api/v1/collections
Content-Type: application/json

{
  "name": "Holiday Pastries",
  "description": "Seasonal baked goods collection",
  "recipe_ids": ["chocolate_biscotti", "cinnamon_sugar"]
}

Update Recipe Book

PUT /api/v1/collections/holiday_pastries

Archive Recipe Book

DELETE /api/v1/collections/holiday_pastries

---

Inventory Counts

List Counting Sessions

GET /api/v1/inventory/counts?status=all

Start New Count Session

POST /api/v1/inventory/counts
Content-Type: application/json

{
  "title": "August End-of-Month Count",
  "counted_at": "2026-08-31T18:00:00Z",
  "notes": "Full kitchen and pantry audit",
  "prepopulate": true
}

Get Count Sheet & Extended Valuation

GET /api/v1/inventory/counts/count_2026_08_week3

Save Count Items & Update Status

PUT /api/v1/inventory/counts/count_2026_08_week3
Content-Type: application/json

{
  "status": "completed",
  "items": [
    { "ingredient_id": "flour_all_purpose", "location_id": "loc_dry_storage", "quantity": 15000, "unit_id": "gram" },
    { "ingredient_id": "sugar", "location_id": "loc_dry_storage", "quantity": 25, "unit_id": "pound" }
  ]
}

---

Unit Conversions

POST /api/v1/convert
Content-Type: application/json

{
  "ingredient_id": "salt",
  "quantity": 2,
  "from_unit": "tbsp",
  "to_unit": "gram"
}

{
  "success": true,
  "data": {
    "from": { "quantity": 2, "unit_id": "tbsp" },
    "to": { "quantity": 36.52, "unit_id": "gram" },
    "ingredient_id": "salt",
    "method": "ingredient_measure_conversion"
  }
}

---

Database Backups

GET /api/app/backup/export
POST /api/app/backup/validate
POST /api/app/backup/import?mode=replace|merge