Recipe schema reference

The Recipe object

Fifteen top-level keys. Seven scalar identifiers, then seven nested structures and arrays. Every recipe returned by the API conforms to this shape exactly.

The seven scalar fields that identify and classify a recipe. Every recipe — from /dinner, /recipes/:id, or /generate — carries these. They are the keys you filter, sort, and cache on.

interface ApiRecipe {
  id: string;
  name: string;
  description: string;
  category: string;
  cuisine: string;
  difficulty: string;
  tags: string[];
  meta: ApiRecipeMeta;
  dietary: ApiDietary;
  storage: ApiStorage;
  equipment: ApiEquipment[];
  ingredients: ApiIngredientGroup[];
  instructions: ApiInstruction[];
  troubleshooting: ApiTroubleshooting[];
  chef_notes: string[];
  cultural_context: string | null;
  nutrition: ApiNutrition;
}

Timing and portioning. All durations are ISO 8601 — parse them (don't string-match), because PT2H and PT120M are equivalent. The numeric yield_count and serving_size_g exist so you can do portion math without parsing the human strings.

interface ApiRecipeMeta {
  active_time: string;            // ISO 8601 duration
  passive_time: string;           // ISO 8601 duration
  total_time: string;             // ISO 8601 duration
  overnight_required: boolean;
  yields: string;                 // human-readable
  yield_count: number;            // numeric, for calculations
  serving_size_g: number | null;  // grams per serving
}

ISO 8601 durations: PT#H#M#S for clock times (PT20M), P#D / P#M / P#Y for calendar spans used in storage. Example: PT2H = 2 hours; P4D = 4 days.

Two complementary lists: positive attributes a recipe satisfies (flags) and conditions it is not suitable for (allergens/warnings). Both are filterable on /recipes.

interface ApiDietary {
  flags: string[];            // e.g. ["Vegetarian", "Gluten-Free"]
  not_suitable_for: string[]; // e.g. ["Nut allergy"]
}

How long the cooked result keeps and how to bring it back. refrigerator and freezer are nullable objects — a null means that storage method is not recommended for this recipe.

interface ApiStorage {
  refrigerator: {
    duration: string;        // ISO 8601 duration, e.g. "P3D"
    notes: string;
  } | null;
  freezer: {
    duration: string | null; // ISO 8601, null if not recommended
    notes: string;
  } | null;
  reheating: string | null;
  does_not_keep: boolean;
}

An array of tools the recipe calls for. Each entry names the tool, whether it's mandatory, and — crucially for substitution UX — a workable alternative.

interface ApiEquipment {
  name: string;
  required: boolean;
  alternative: string | null;
}

Dinner recipe equipment: [ Blender → Food processor or mortar and pestle, Heavy skillet → Dutch oven or heavy-bottomed pot, Mixing bowl → null ].

The heart of the schema. Ingredients are grouped by component (dough, filling, sauce...). Every line item is linked to a stable ingredient UUID and a named nutrition source, so you can trace exactly where each macro came from. This traceability is what separates this API from plain recipe text.

interface ApiIngredientGroup {
  group_name: string;
  items: ApiIngredient[];
}

interface ApiIngredient {
  name: string;
  quantity: number | null;
  unit: string | null;
  preparation: string | null;        // e.g. "diced", "chopped"
  notes: string | null;
  substitutions: string[];
  ingredient_id: string | null;      // UUID from ingredients table
  nutrition_source: string | null;   // e.g. "USDA FoodData Central"
}

Worked example — stewing beef line: { name: "stewing beef", quantity: 910, unit: "g", preparation: "cut into 1.3cm (1/2 inch) cubes", notes: null, substitutions: [], ingredient_id: "09f2eef4-739a-4fca-8b63-97d697257990", nutrition_source: "USDA FoodData Central" }.

Ordered steps. Each carries human text plus an optional structured object that encodes the verb, temperature (in both units), duration, and doneness cues. The structured layer is what lets apps render smart timers, temperature targets, and 'is it done yet?' checks instead of a wall of prose.

interface ApiInstruction {
  step_number: number;
  phase: string;                  // prep | cook | assemble | finish
  text: string;
  structured: ApiStructuredStep | null;
  tips: string[];
}

interface ApiStructuredStep {
  action: string;                 // e.g. "ROAST", "SIMMER"
  temperature: {
    celsius: number;
    fahrenheit: number;
  } | null;
  duration: string | null;        // ISO 8601 duration
  doneness_cues: {
    visual: string | null;
    tactile: string | null;
  } | null;
}

A knowledge base of what goes wrong, why, and how to recover — structured for 'my X happened, now what?' lookup. Each entry is a complete symptom → cause → prevention → fix loop.

interface ApiTroubleshooting {
  symptom: string;
  likely_cause: string;
  prevention: string;
  fix: string;
}

An array of free-form technique notes from the recipe's chef — the 'why' behind the method. Not tied to a specific step; these are the principles that make the dish work.

chef_notes: string[];

Background on the dish's origin and tradition. Nullable — present where there's a meaningful story, null when the dish is generic.

cultural_context: string | null;

Per-serving nutrition computed from USDA FoodData Central ingredient data. per_serving carries all 32 tracked nutrients; every value is a nullable number — handle null per-nutrient, not per-recipe. sources names where the numbers came from.

interface ApiNutrition {
  per_serving: NutrientValues;
  sources: string[];   // e.g. ["USDA FoodData Central"]
}

All 32 per_serving values are number | null. alcohol_g and caffeine_mg are null on the dinner recipe (a non-alcoholic, decaf dish). Never assume a value is present — null-check each nutrient.

The same 32-key panel appears as per_serving on recipes and as per_100g on ingredient detail — identical keys, different basis. Every value is number | null. Values shown are the live dinner-recipe numbers per serving.

Response types & wrappers

How a Recipe is wrapped depending on the endpoint, plus the lighter list-item shape and the ingredient-detail shape that reuses the same nutrient panel.

Metered detail responses (single recipe, single ingredient, generate) are wrapped with data and an optional usage object. List/discovery responses add a meta object instead.

interface ApiResponse<T> {
  data: T;
  usage?: ApiUsage;
  meta?: {
    total?: number;
    page?: number;
    per_page?: number;
    total_capped?: boolean; // true if more exist beyond the discovery limit
  };
}

Returned by GET /api/v1/recipes. Carries identity, meta, dietary, and a 4-macro nutrition_summary — not the full 32 nutrients, ingredients, or instructions. Fetch the detail by id when you need those.

interface ApiRecipeListItem {
  id: string;
  name: string;
  description: string;
  category: string;
  cuisine: string;
  difficulty: string;
  tags: string[];
  meta: ApiRecipeMeta;
  dietary: ApiDietary;
  nutrition_summary: {
    calories: number | null;
    protein_g: number | null;
    carbohydrates_g: number | null;
    fat_g: number | null;
  };
}

Returned by GET /api/v1/ingredients/:id. Same 32 nutrient keys as recipe nutrition, but on a per-100g basis. Lets you compute macros for any quantity of any ingredient.

interface ApiIngredientDetail extends ApiIngredientItem {
  nutrition: ApiIngredientNutrition | null;
}

interface ApiIngredientNutrition {
  per_100g: NutrientValues;   // same 32 keys as per_serving
  sources: string[];
}

Every error uses one JSON envelope. Switch on the stable error.code, never the human message.

interface ApiError {
  error: {
    code: string;
    message: string;
  };
}