API

Food

Recipes, collections, the meal plan, shopping lists, the pantry, suggestions and importing.

See Food. Food is personal: these routes take no organization. The plan, shopping lists and pantry are the household's, so everyone in it reads and changes the same ones. A key needs food:read (and food:write to change things) and acts for the person who made it. Public recipe links and the plan's calendar feed answer without a sign-in, at /v1/hooks/food.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/hooks/food/r/:token`	A recipe by its public link (no sign-in): the recipe without its owner's notes or rating. 404 once the link is off.
`GET /v1/hooks/food/plan/:token`	A household's meal plan as an iCalendar feed (`<token>.ics`, no sign-in): two weeks back to eight ahead, at meal times.
`GET /v1/me/food/settings`	Your Food settings (measures, spoons, servings, diets, allergens, suggestions, Health logging, week start) and your household.
`PATCH /v1/me/food/settings`	Changes the person's Food settings (only the fields given; `null` clears one).
`GET /v1/me/food/home`	Your household: its name and members (made, yours alone, the first time).
`PATCH /v1/me/food/home`	Renames your household.
`POST /v1/me/food/home/invites`	An invitation link into your household, good for a week.
`GET /v1/me/food/home/invites/:code`	What an invitation is for: the household's name, who invited you and how many are in it.
`POST /v1/me/food/home/invites/:code/accept`	Joins the household (your own waits for you; refused while yours has others in it).
`POST /v1/me/food/home/leave`	Leaves the household, back to your own (its owner can't while others are in it).
`DELETE /v1/me/food/home/members/:userId`	Removes someone from your household (its owner only).
`GET /v1/me/food/recipes`	The person's recipes and their household's shared ones as cards, searched and filtered (`limit`: at most 1000, 200 by default).
`POST /v1/me/food/recipes`	Adds a recipe. Ingredients and steps may be text (one ingredient per line; steps by paragraph), which Food reads; `imageUrls` are copied in by the worker.
`GET /v1/me/food/recipes/:recipeId`	A recipe in full, with signed picture links, nutrition per serving, allergens, diets and your access (`owner`, `household`).
`PATCH /v1/me/food/recipes/:recipeId`	Changes a recipe of the person's (`version`: refused with 409 when it changed meanwhile).
`DELETE /v1/me/food/recipes/:recipeId`	Deletes a recipe of yours, its pictures (freeing their storage) and its public link.
`POST /v1/me/food/recipes/:recipeId/copy`	Copies a recipe your household shares into your own recipes (pictures copied into your storage).
`POST /v1/me/food/recipes/:recipeId/cook`	Logs that the person cooked it, with a rating and note; `logToHealth` logs a serving to Health's nutrition (when they turned it on).
`PUT /v1/me/food/recipes/:recipeId/link`	Turns the recipe's public link on (a new link each time) or off.
`POST /v1/me/food/recipes/:recipeId/notes`	Saves the recipe as a Notes page in one of the person's orgs (where they can write Notes).
`POST /v1/me/food/public/:token/copy`	Copies a recipe shared by public link into your own recipes.
`GET /v1/me/food/history`	What you've cooked, newest first, with ratings and notes (`limit`, 100 by default).
`POST /v1/me/food/images`	Keeps a picture (base64 JPEG, PNG, WebP or GIF, at most 8 MB) in the person's Food drive, metadata removed; use the answer in a recipe's `images`.
`GET /v1/me/food/collections`	Your collections, with their recipes in order and their groups.
`POST /v1/me/food/collections`	A new collection, optionally with recipes and named groups.
`PATCH /v1/me/food/collections/:collectionId`	Renames a collection or changes its recipes (`add`, `remove`, or the whole `recipeIds` in order).
`DELETE /v1/me/food/collections/:collectionId`	Deletes a collection (its recipes stay).
`GET /v1/me/food/plan`	The household's meals between two days (at most 92).
`POST /v1/me/food/plan`	Puts a meal on the household's plan: a recipe, or a note ("Leftovers").
`PATCH /v1/me/food/plan/:entryId`	Moves or changes a meal (`from`: the day it's on now, which saves a lookup).
`DELETE /v1/me/food/plan/:entryId`	Takes a meal off the plan (`day`: the day it's on, which saves a lookup).
`GET /v1/me/food/plan/feed`	The household's private calendar feed link (`url`, and `webcal` for calendar apps).
`POST /v1/me/food/plan/feed/rotate`	Replaces the calendar feed link; the old one stops working.
`POST /v1/me/food/plan/suggest`	Proposes (or with `apply`, plans) meals for the days ahead from the suggestions.
`POST /v1/me/food/plan/calendar`	Puts planned meals on a Mail calendar of the person's (events at meal times, linking back).
`GET /v1/me/food/lists`	The household's shopping lists, most recently changed first.
`POST /v1/me/food/lists`	A new list: empty, from the plan between two days, or from recipes at given servings (merged by ingredient, by aisle, without the pantry).
`GET /v1/me/food/lists/:listId`	A shopping list with its items (aisle, amount, ticked, the recipes they're for).
`PATCH /v1/me/food/lists/:listId`	Renames a list.
`DELETE /v1/me/food/lists/:listId`	Deletes a list.
`POST /v1/me/food/lists/:listId/items`	Adds items to a list (their aisle from the ingredient when not given).
`POST /v1/me/food/lists/:listId/recipes`	Adds recipes' ingredients to a list (merged with what's on it).
`PATCH /v1/me/food/lists/:listId/items/:itemId`	Ticks an item (`checked`) or changes it; two people ticking at once both land.
`POST /v1/me/food/lists/:listId/items/remove`	Removes items by id, or every ticked one (`{ "checked": true }`).
`GET /v1/me/food/pantry`	What the household has in, soonest use-by first.
`POST /v1/me/food/pantry`	Adds things to the household's pantry, fridge or freezer: placed by kind and given an estimated use-by unless given; merged into the same thing already there unless `merge` is false.
`GET /v1/me/food/pantry/use-soon`	What needs using soon (within `days`, 3 by default) and the recipes that use the most of it.
`GET /v1/me/food/pantry/barcodes/:code`	What a barcode is (the household's own answer, else Open Food Facts), as a pantry item to check; `found: false` when nobody knows it.
`PUT /v1/me/food/pantry/barcodes/:code`	The household's own answer for a barcode (one nobody knew, or a correction).
`POST /v1/me/food/pantry/scans`	Photos of a shelf, the fridge or a bench of shopping (base64, up to four), read by the model into items to check; poll the scan. Counts against the daily photo readings.
`GET /v1/me/food/pantry/scans/:scanId`	A pantry photo being read: `running`, then `done` with the items to check (placed, with estimated use-bys and what each would add to), or `failed`.
`PATCH /v1/me/food/pantry/:itemId`	Changes something in the pantry (`useBy: null` clears its date).
`POST /v1/me/food/pantry/remove`	Takes things out of the pantry (used up).
`GET /v1/me/food/cookable`	"What can I cook?": the person's and household's recipes by how much the pantry covers, with what's missing.
`GET /v1/me/food/receipts`	The household's grocery receipts, newest purchase first (`status`: new, added or dismissed).
`GET /v1/me/food/receipts/settings`	Receipts settings: the household's forwarding address (when made), whether receipts go straight in, Gmail's last confirmation, and the person's Cactive Mail link.
`PATCH /v1/me/food/receipts/settings`	Whether the household's new receipts go straight into the pantry (`autoAdd`) or wait for review.
`POST /v1/me/food/receipts/forwarding`	Makes the household's private forwarding address (or a new one with `rotate`: the old one stops working).
`PUT /v1/me/food/receipts/mail`	Turns on grocery receipts from one of the person's Cactive Mail mailboxes (they must be a member): Food then reads only mail from the stores' e-receipt senders there.
`DELETE /v1/me/food/receipts/mail`	Stops reading grocery receipts from the person's Cactive Mail; receipts already read stay.
`POST /v1/me/food/receipts/mail/backfill`	"Check the last 30 days" (once): the linked mailbox's mail from the stores' e-receipt senders, read for receipts.
`GET /v1/me/food/receipts/:receiptId`	One receipt (decrypted): the store, the day, the total and each line with its price, amount, place and estimated use-by.
`POST /v1/me/food/receipts/:receiptId/add`	Puts a receipt into the pantry: its food lines, or the `lines` as ticked and changed (merged into what's there).
`POST /v1/me/food/receipts/:receiptId/dismiss`	Leaves a receipt out of the pantry (it still counts in spending).
`DELETE /v1/me/food/receipts`	Deletes the household's receipts and prices (and the key they're sealed with).
`GET /v1/me/food/spending`	Grocery spending by month from the household's receipts (`months`: 1 to 24, 6 by default).
`POST /v1/me/food/delete-all`	Deletes all the person's Food data (call again while `done` is false): see docs/food/README.md → Privacy.
`GET /v1/me/food/suggestions`	Ideas from the person's recipes with why (ratings, history, the season, the pantry, the weather when turned on), within their diets and allergens.
`GET /v1/me/food/substitutes`	Substitutes for an ingredient from Food's kitchen notes, with amounts (none on file: an empty list and a note).
`GET /v1/me/food/widget`	The phone's widgets: tonight's dinner and the first list's next items.
`POST /v1/me/food/imports/url`	A web page's recipe as a draft to check (schema.org data, else its lists); a page without either is read by the model as an import.
`POST /v1/me/food/imports/text`	Recipes in pasted text as drafts to check (several when separated by a line of dashes).
`POST /v1/me/food/imports/photos`	Photos or screenshots of one recipe (base64, up to four), read by the model; poll the import for its draft.
`POST /v1/me/food/imports/files`	Starts importing another app's export: a link to PUT the file to, then `complete`.
`POST /v1/me/food/imports/:importId/complete`	The file has been sent: the worker reads it and saves its recipes (and Melt's cookbooks as collections).
`GET /v1/me/food/imports`	Your imports from the last two weeks: what they read, saved and skipped, or why they failed.
`GET /v1/me/food/imports/:importId`	One import: its status and, for one recipe read from photos or a page, the draft to check.
`GET /v1/me/food/export`	Everything of yours in Food as a file Food imports again (`format: cactive-food`): recipes, collections, settings and history. Pictures are links valid for an hour.
`GET /v1/me/food/exports`	Your ZIP exports from the last day, newest first, each with its status and, once ready, a download link per ZIP (an hour long).
`POST /v1/me/food/exports`	Starts a ZIP export: the export's JSON (`food-export.json`) with your recipes' pictures beside it, made in the background and kept a day. Check it until `ready`; a few a day.
`GET /v1/me/food/exports/:exportId`	One ZIP export: `queued`, `ready` (each ZIP's `url`) or `failed`.