# Documentation

- [Flambe API](/docs): Import, digitize and manage recipes programmatically. Everything the Flambe apps do, over HTTP.
- [Quickstart](/docs/quickstart): Authenticate, import a recipe from a URL, and read the result back.
- [How this reference stays true](/docs/how-the-spec-stays-true): Why the OpenAPI document can be trusted, what it guarantees, and the two things it still cannot tell you.

- **Guides**
- Guides
  - [Authentication](/docs/guides/authentication): How to obtain a bearer token, what it scopes, and how server-to-server access works.
  - [Imports](/docs/guides/imports): Turn a URL, a photograph of a cookbook page, or pasted text into a structured recipe.
  - [Recipes](/docs/guides/recipes): The recipe model, and how to create, update and organize a library.
  - [Files](/docs/guides/files): Uploading images, resolving metadata in bulk, and using the CDN.
  - [Syncing](/docs/guides/syncing): Keep a local copy current with delta sync instead of refetching the library.
  - [Live events](/docs/guides/events): Subscribe to server-sent events for import progress instead of polling.
  - [Households](/docs/guides/households): Share a library with other people, and control exactly what is shared.
  - [Public share links](/docs/guides/sharing): Mint an unlisted URL for one recipe, and revoke it later.
  - [Errors and retries](/docs/guides/errors): The error envelope, what each status means, and what is safe to retry.

- **For agents**
- For agents
  - [Built for agents](/docs/agents): How to point an AI agent or coding assistant at the Flambe API.
  - [MCP server](/docs/agents/mcp): Connect an MCP client to the Flambe docs and search them as tools.
  - [Plain-text context](/docs/agents/context): llms.txt, llms-full.txt, and Markdown for every page.

- **Reference**
- API reference
  - [API reference](/docs/api-reference): Every public Flambe endpoint, generated from the OpenAPI spec and verified against the running server.
  - Ai
    - [Create a realtime assistant session](/docs/api-reference/ai/createAiSession): Mints a short-lived client secret for the hands-free cooking assistant,
so a client can open a realtime connection without ever holding a
long-lived provider key. Scope it to a recipe with `recipeId`.

The secret expires quickly — request one per session, at the moment the
user starts talking, rather than caching it.
    - [Embed a search query](/docs/api-reference/ai/embedQuery): Returns the embedding vector for a search string, using the same model
that indexed the recipes. Use it to run your own semantic search over
recipes you have synced locally — embedding the query client-side with a
different model would not produce comparable distances.
  - Auth
    - [Log in (legacy)](/docs/api-reference/auth/login): Legacy username/password login, retained for older clients. Use Clerk
instead.
    - [Register (legacy)](/docs/api-reference/auth/register): Legacy username/password registration, retained for older clients.
Authentication is handled by Clerk now — see the
[Authentication guide](https://docs.flambe.dev/docs/guides/authentication).
  - Books
    - [List cookbooks by author](/docs/api-reference/books/listBooksByAuthor)
    - [Search cookbooks](/docs/api-reference/books/searchBooks): Looks up cookbooks by title, for attributing a recipe to a book. Backed
by an external bibliographic catalogue.
  - Collections
    - [Add several recipes to a collection](/docs/api-reference/collections/addRecipesToCollectionBulk)
    - [Add a recipe to a collection](/docs/api-reference/collections/addRecipeToCollection)
    - [Create a collection](/docs/api-reference/collections/createCollection)
    - [Delete a collection](/docs/api-reference/collections/deleteCollection): Deletes the collection. The recipes in it are not deleted.
    - [Get a collection](/docs/api-reference/collections/getCollection)
    - [Leave a shared collection](/docs/api-reference/collections/leaveCollection): Removes the caller's access to a collection that was shared with them.
The owner's copy is untouched. Owners cannot leave their own collection
— delete it instead.
    - [List collections](/docs/api-reference/collections/listCollections)
    - [Remove a recipe from a collection](/docs/api-reference/collections/removeRecipeFromCollection)
    - [Update a collection](/docs/api-reference/collections/updateCollection)
  - Cook sessions
    - [Add a recipe to a session](/docs/api-reference/cook-sessions/addRecipeToCookSession)
    - [Start a cook session](/docs/api-reference/cook-sessions/createCookSession)
    - [Delete a cook session](/docs/api-reference/cook-sessions/deleteCookSession)
    - [End a cook session](/docs/api-reference/cook-sessions/endCookSession): Marks the session `ended` and stamps `ended_at`.
    - [Get the active session](/docs/api-reference/cook-sessions/getActiveCookSession): The session currently in progress, so a second device can join what is
already being cooked. Returns `null` when nothing is active.
    - [Get a cook session](/docs/api-reference/cook-sessions/getCookSession)
    - [List cook sessions](/docs/api-reference/cook-sessions/listCookSessions)
    - [Remove a recipe from a session](/docs/api-reference/cook-sessions/removeRecipeFromCookSession)
    - [Restore an ended session](/docs/api-reference/cook-sessions/restoreCookSession): Reopens a session that was ended — for when cooking was interrupted
rather than finished.
  - Creators
    - [Get a creator](/docs/api-reference/creators/getCreator)
    - [Get a creator profile](/docs/api-reference/creators/getCreatorProfile)
    - [List creator profiles](/docs/api-reference/creators/listAllCreatorProfiles)
    - [List a creator's profiles](/docs/api-reference/creators/listCreatorProfiles): The platform accounts belonging to one creator.
    - [List creators](/docs/api-reference/creators/listCreators)
    - [Rename a creator](/docs/api-reference/creators/updateCreator)
  - Events
    - [Subscribe to live events](/docs/api-reference/events/streamEvents): A [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events)
stream of changes to the caller's data — most usefully, import progress
and completion, which removes the need to poll `GET /api/imports/{id}`.

The connection is authenticated with the usual `Authorization: Bearer`
header. Note that the browser's built-in `EventSource` cannot set
headers, so on the web you need a fetch-based SSE client.

The server sends a comment line every few seconds as a keep-alive;
ignore lines beginning with `:`.
  - Files
    - [Get a file](/docs/api-reference/files/getFile): Returns the asset for a file the caller can read — their own, or one
shared through a household. Prefer the CDN `url` from the file's
metadata for anything user-facing; it is cached at the edge.
    - [Get file metadata](/docs/api-reference/files/getFileMetadata)
    - [List file metadata](/docs/api-reference/files/listFileMetadata): Every file readable by the caller, paginated.
    - [Resolve file metadata in bulk](/docs/api-reference/files/queryFileMetadata): Resolves many file ids in one call. Ids the caller cannot read are
omitted from the response rather than erroring, so a partial result is
normal.
    - [Stream file metadata](/docs/api-reference/files/streamFileMetadata): The same resolution as `/metadata/query`, delivered as newline-delimited
JSON (`application/x-ndjson`) so a client can render the first records
without waiting for the whole batch. One JSON object per line.
    - [Upload files](/docs/api-reference/files/uploadFiles): Uploads one or more binary assets as `multipart/form-data` under the
field name `files`. Images are stored, processed for width variants and
given a BlurHash.

This is the first half of a `media` import: upload the images here, then
pass the returned ids as `file_ids` to `POST /api/imports`.
  - Grocery lists
    - [Append items to a grocery list](/docs/api-reference/grocery-lists/addGroceryItems): Adds items without rewriting the list. Lines that match an existing item
are merged rather than duplicated.
    - [Create a grocery list](/docs/api-reference/grocery-lists/createGroceryList)
    - [Delete a grocery list](/docs/api-reference/grocery-lists/deleteGroceryList)
    - [Get a grocery list](/docs/api-reference/grocery-lists/getGroceryList)
    - [Leave a shared grocery list](/docs/api-reference/grocery-lists/leaveGroceryList)
    - [List grocery lists](/docs/api-reference/grocery-lists/listGroceryLists)
    - [Update a grocery list](/docs/api-reference/grocery-lists/updateGroceryList): Supplying `items` replaces the whole item list — this is how a client
persists check-offs and edits in one call.
  - Households
    - [Accept an invite](/docs/api-reference/households/acceptHouseholdInvite): Redeems an invite token and joins the caller to the household. Requires
authentication — the invite is bound to whoever accepts it.
    - [Replace the grants for a resource type](/docs/api-reference/households/bulkGrantHouseholdResources): Sets the complete set of grants for one resource type in a single call.
Anything the caller had shared that is absent from `grants` is revoked,
which is what makes this safe to drive from a checkbox list.
    - [Create a household](/docs/api-reference/households/createHousehold): The caller becomes the owner.
    - [Invite someone to a household](/docs/api-reference/households/createHouseholdInvite): Invite by `recipient_email` for someone who may not have an account
yet, or by `recipient_user_id` for an existing Flambe user.
    - [Delete a household](/docs/api-reference/households/deleteHousehold): Owner only. Dissolves the household and revokes every share made
through it; members keep their own libraries.
    - [Get a household](/docs/api-reference/households/getHousehold)
    - [List the shared library](/docs/api-reference/households/getHouseholdLibrary): Every resource shared into the household, by any member.
    - [Get sharing preferences](/docs/api-reference/households/getHouseholdSharingPreferences): The caller's defaults for this household — for example, whether newly
created recipes are shared automatically.
    - [Share a resource into a household](/docs/api-reference/households/grantHouseholdResource)
    - [Leave a shared collection](/docs/api-reference/households/leaveCollection): Removes the caller's access to a collection that was shared with them.
The owner's copy is untouched. Owners cannot leave their own collection
— delete it instead.
    - [Leave a shared grocery list](/docs/api-reference/households/leaveGroceryList)
    - [Leave a household](/docs/api-reference/households/leaveHousehold): Removes the caller and revokes the resources they had shared into it.
An owner must transfer ownership or delete the household instead.
    - [List my shareable resources](/docs/api-reference/households/listMyHouseholdResources): The caller's own resources of one type, each annotated with whether it
is currently shared into this household — the data behind a share
picker.
    - [List my households](/docs/api-reference/households/listMyHouseholds)
    - [Remove a member](/docs/api-reference/households/removeHouseholdMember): Owner or admin only.
    - [Revoke an invite](/docs/api-reference/households/revokeHouseholdInvite)
    - [Unshare a resource](/docs/api-reference/households/revokeHouseholdResource)
    - [Set sharing preferences](/docs/api-reference/households/setHouseholdSharingPreferences)
    - [Rename a household](/docs/api-reference/households/updateHousehold)
  - Imports
    - [Cancel an import](/docs/api-reference/imports/cancelImport): Cancel an import that has not finished. A worker already mid-extraction
observes the cancellation at its next checkpoint, so the job may run a
little longer before it stops.
    - [Start an import](/docs/api-reference/imports/createImport): Creates an import job and enqueues it. Returns `201` immediately with a
record whose `status` is `pending` — extraction happens asynchronously
on a worker, and takes anywhere from a few seconds to a couple of
minutes depending on the source.

Which fields are required depends on `type`:

| `type` | Required | Notes |
| --- | --- | --- |
| `web` | `url` | Must be `https`. Recipe sites, Instagram, YouTube, TikTok. |
| `media` | `file_ids` | Upload images first with `POST /api/files`. |
| `text` | `text` or `text_file_id` | `text` must be at least 3 characters. |
| `image_batch` | `file_ids` | Fans out into one child import per image. |

Track the job by polling `GET /api/imports/{id}` or by subscribing to
`GET /api/events/stream`. When `status` becomes `completed`, `recipe_id`
points at the created recipe.
    - [Get an import](/docs/api-reference/imports/getImport): Fetch one import. Poll this to follow a job to completion; a one- to
two-second interval is plenty, and `/api/events/stream` avoids polling
altogether.
    - [List the import working set](/docs/api-reference/imports/getImportWorkingSet): The newest imports by `created_at`, intentionally not paginated — this
is the bounded window the apps' import screens render.

Ordering is by **creation**, not by recency of activity. An old import
that just failed or is being retried has a fresh `updated_at` but keeps
its original `created_at`, so it is *not* pulled into this window. Use
`/api/imports/v2` when you need the archive.

Batch parents of any child in the window are fetched and included even
when the parent itself falls outside it.
    - [List child imports](/docs/api-reference/imports/listImportChildren): For an `image_batch` parent, the per-image child imports it fanned out
into. Each child succeeds or fails independently, so a batch can be
partially complete.
    - [List imports (paginated)](/docs/api-reference/imports/listImports): The full import archive, newest first by `created_at`, cursor
paginated. Use this to page back through history; use
`/api/imports/working-set` for the bounded set a UI renders.
    - [Report a bad import](/docs/api-reference/imports/reportImport): Flag a completed import whose extraction was wrong. Reports feed triage
of the extraction pipeline. One report per import per user.
    - [Retry an import](/docs/api-reference/imports/retryImport): Re-enqueue a finished import, reusing the original source. The record is
reset to `pending` and `processing_started_at` is re-stamped, which
gives the attempt a full retry budget rather than inheriting the elapsed
time of the previous one.
    - [Attach provenance to an import](/docs/api-reference/imports/setImportSource): Tell the pipeline where this import came from — a cookbook, a website, a
creator — before or while it runs, so the resulting recipe is attributed
correctly.
  - Meal plans
    - [Add a meal to a plan](/docs/api-reference/meal-plans/addMeal): Adds a recurring slot. `days_of_week` makes the slot repeat — `[1,3,5]`
is Monday, Wednesday and Friday.
    - [Create a meal plan](/docs/api-reference/meal-plans/createMealPlan)
    - [Remove a meal](/docs/api-reference/meal-plans/deleteMeal)
    - [Delete a meal plan](/docs/api-reference/meal-plans/deleteMealPlan)
    - [Export a meal plan](/docs/api-reference/meal-plans/exportMealPlan): Renders the plan for use outside Flambe.
    - [Get a meal plan](/docs/api-reference/meal-plans/getMealPlan)
    - [List meal plans](/docs/api-reference/meal-plans/listMealPlans)
    - [Update a meal](/docs/api-reference/meal-plans/updateMeal)
    - [Update a meal plan](/docs/api-reference/meal-plans/updateMealPlan)
  - Notifications
    - [Create a notification](/docs/api-reference/notifications/createNotification): Writes a notification to the caller's own feed. Most notifications are
produced by the platform — import completions and household invites —
so this is mainly for a client that wants to surface something locally.
    - [Get the unread count](/docs/api-reference/notifications/getUnreadNotificationCount): Cheap enough to poll for a badge.
    - [List notifications](/docs/api-reference/notifications/listNotifications)
    - [Mark all notifications read](/docs/api-reference/notifications/markAllNotificationsRead): Pass `before` to only clear notifications older than that instant, which
avoids swallowing something that arrived while the user was reading.
    - [Mark a notification read](/docs/api-reference/notifications/markNotificationRead)
    - [Mark a notification unread](/docs/api-reference/notifications/markNotificationUnread)
  - Push tokens
    - [Unregister a device](/docs/api-reference/push-tokens/deletePushToken): Call this on sign-out so the device stops receiving pushes.
    - [List my registered devices](/docs/api-reference/push-tokens/listMyPushTokens)
    - [Register a device for push](/docs/api-reference/push-tokens/registerPushToken): Registering the same `token` again updates the existing record rather
than creating a duplicate, so this is safe to call on every launch.
  - Recipes
    - [Attach a source](/docs/api-reference/recipes/attachRecipeSource): A recipe can cite more than one source — the cookbook it came from and
the creator's post about it, say. This attaches an additional one.
Pass `make_primary` to promote it to the headline attribution.
    - [Clear the primary source](/docs/api-reference/recipes/clearRecipeSourceV2)
    - [Compute nutrition](/docs/api-reference/recipes/computeRecipeNutrition): Estimates per-serving nutrition by matching each ingredient against USDA
FoodData Central and Open Food Facts, then stores the result on the
recipe. Values are estimates; ingredients that cannot be matched are
skipped rather than guessed.

The result is cached against a hash of the ingredient list, so calling
this again without editing ingredients returns the stored figures.
    - [Create a recipe](/docs/api-reference/recipes/createRecipe): Create a recipe directly, without going through an import. Only `title`
is required.
    - [Delete a recipe](/docs/api-reference/recipes/deleteRecipe): Permanently deletes the recipe and records a revocation so that syncing
clients remove their copies.
    - [Detach a source](/docs/api-reference/recipes/detachRecipeSource)
    - [Get a recipe](/docs/api-reference/recipes/getRecipe)
    - [Stream recipe change events](/docs/api-reference/recipes/listRecipeChanges): An append-only event log of changes to the user's recipes — the
lower-level primitive behind delta sync, useful when you need to know
*what* changed rather than just the current state.

`since` is a numeric sequence watermark, not a timestamp. Start at `0`
and carry forward the value the response returns.
    - [List recipes](/docs/api-reference/recipes/listRecipes): The authenticated user's recipe library, plus any recipes shared with
them through a household.

Supports two independent mechanisms:

- **Pagination** — `limit` (default 24, max 100) and `cursor`.
- **Delta sync** — pass `updated_since` to receive only recipes changed
  since that instant, along with `revoked_ids` for recipes that are no
  longer visible. Mirror `server_timestamp` back as the next
  `updated_since`.

Change history is retained for 30 days. A watermark older than 25 days
is refused with `full_sync_required: true` and an empty result — drop
your local state and re-sync without `updated_since`.
    - [Save a copy](/docs/api-reference/recipes/saveRecipeCopy): Copies a recipe that is visible to the caller — typically one shared
through a household — into their own library as an independent record.
Later edits to the original do not propagate.
    - [Set legacy source](/docs/api-reference/recipes/setRecipeSource): The v1 provenance model, kept for older clients. Use
`PUT /api/recipes/{id}/source-v2` or `POST /api/recipes/{id}/sources`.
    - [Set the primary source](/docs/api-reference/recipes/setRecipeSourceV2): Attaches the recipe to a shared `SourceV2` provenance record. Supply
either `source` to resolve or create one by descriptor, or
`source_v2_id` to point at an existing record.
    - [Update a recipe](/docs/api-reference/recipes/updateRecipe): Replaces the supplied fields. Omitted fields are left untouched, so this
behaves as a partial update despite being a `PUT`.
    - [Update a source attachment](/docs/api-reference/recipes/updateRecipeSourceAttachment)
  - Sharing
    - [Create a share link](/docs/api-reference/sharing/createShareLink): Mints an unlisted public URL for one resource. Anyone with the link can
view it without signing in, so treat the token as a secret. Share links
are deliberately excluded from `sitemap.xml` and disallowed in
`robots.txt`.
    - [Resolve a share link](/docs/api-reference/sharing/getSharedResource): Resolves a share token to the resource it points at. **Unauthenticated**
— this is what renders `https://flambe.dev/share/{token}` for a
recipient who has no Flambe account.
    - [Revoke a share link](/docs/api-reference/sharing/revokeShareLink): Revokes the link immediately. The URL stops resolving; any page already
open keeps whatever it has already loaded.
    - [Save a shared resource](/docs/api-reference/sharing/saveSharedResource): Copies a shared resource into the caller's own library. Unlike
resolving the link, this does require authentication.
  - Sources
    - [Attach a source](/docs/api-reference/sources/attachRecipeSource): A recipe can cite more than one source — the cookbook it came from and
the creator's post about it, say. This attaches an additional one.
Pass `make_primary` to promote it to the headline attribution.
    - [Clear the primary source](/docs/api-reference/sources/clearRecipeSourceV2)
    - [Detach a source](/docs/api-reference/sources/detachRecipeSource)
    - [Get a source](/docs/api-reference/sources/getSourceV2)
    - [Get a verified recipe](/docs/api-reference/sources/getVerifiedRecipe)
    - [List a source's recipes (v1)](/docs/api-reference/sources/listSourceRecipes)
    - [List sources (v1)](/docs/api-reference/sources/listSources): The v1 provenance model. Prefer `/api/v2/sources`.
    - [List sources](/docs/api-reference/sources/listSourcesV2): Sources referenced by recipes the caller can see.
    - [List a source's recipes](/docs/api-reference/sources/listSourceV2Recipes)
    - [List verified recipes](/docs/api-reference/sources/listVerifiedRecipes): Recipes whose extraction has been checked against the original source.
Useful as a trusted corpus.
    - [Attach provenance to an import](/docs/api-reference/sources/setImportSource): Tell the pipeline where this import came from — a cookbook, a website, a
creator — before or while it runs, so the resulting recipe is attributed
correctly.
    - [Set legacy source](/docs/api-reference/sources/setRecipeSource): The v1 provenance model, kept for older clients. Use
`PUT /api/recipes/{id}/source-v2` or `POST /api/recipes/{id}/sources`.
    - [Set the primary source](/docs/api-reference/sources/setRecipeSourceV2): Attaches the recipe to a shared `SourceV2` provenance record. Supply
either `source` to resolve or create one by descriptor, or
`source_v2_id` to point at an existing record.
    - [Update a source attachment](/docs/api-reference/sources/updateRecipeSourceAttachment)
    - [Update a source](/docs/api-reference/sources/updateSourceV2): Sources are shared across users, so corrections here — a fixed title, a
better cover — are visible to everyone citing the same source.
  - System
    - [Health check](/docs/api-reference/system/healthCheck): Liveness probe. Requires no authentication, and is what
[status.flambe.dev](https://status.flambe.dev) polls for the Web service
component.
  - Timers
    - [Acknowledge a fired timer](/docs/api-reference/timers/ackTimer): Confirms the user saw the alert, which stops further reminders for it.
    - [Cancel a timer](/docs/api-reference/timers/cancelTimer)
    - [Create a timer](/docs/api-reference/timers/createTimer): Schedules a timer to fire at `dueAt`. Because the schedule lives on the
server, it still fires if the app is backgrounded or the device
restarts.

Pass `idempotencyKey` to make retries safe — a second call with the same
key returns the original timer rather than creating a duplicate.

Note that timer fields are `camelCase`, unlike the rest of the API.
    - [Get a timer](/docs/api-reference/timers/getTimer)
    - [List timers](/docs/api-reference/timers/listTimers)
    - [Pause a timer](/docs/api-reference/timers/pauseTimer): Freezes the countdown and records `remainingMs`.
    - [Resume a paused timer](/docs/api-reference/timers/resumeTimer): Restarts the countdown from `remainingMs`. Pass `dueAt` to resume to an
explicit instant instead.
  - Users
    - [Get the current user](/docs/api-reference/users/getCurrentUser): Resolves the bearer token to a profile. The cheapest way to check that a
token is valid.
  - Wishlists
    - [Add an item to the default wishlist](/docs/api-reference/wishlists/addDefaultWishlistItem): Adds to the user's default wishlist, creating it if they have none. Use
this for a one-tap "save for later" that does not make the caller pick a
list first.
    - [Add an item to a wishlist](/docs/api-reference/wishlists/addWishlistItem)
    - [Create a wishlist](/docs/api-reference/wishlists/createWishlist)
    - [Delete a wishlist](/docs/api-reference/wishlists/deleteWishlist)
    - [Get a wishlist](/docs/api-reference/wishlists/getWishlist)
    - [List wishlists](/docs/api-reference/wishlists/listWishlists)
    - [Remove an item from a wishlist](/docs/api-reference/wishlists/removeWishlistItem)
    - [Update a wishlist](/docs/api-reference/wishlists/updateWishlist)