Flambe docs
API referenceRecipes

List recipes

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`.

GET
/api/recipes

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.

Authorization

bearerAuth
AuthorizationBearer <token>

A Clerk session JWT. Obtain one with a Clerk frontend SDK (session.getToken()) or, for server-to-server use, with a Clerk machine token. The token's sub claim is the Flambe user id that scopes every request.

In: header

Query Parameters

updated_since?string

Delta-sync watermark, ISO 8601. Omit for a full list.

Formatdate-time
limit?integer
Range1 <= value <= 100
Default24
cursor?string

Opaque pagination cursor returned as next_cursor by the previous page. Base64-encoded DynamoDB ExclusiveStartKey; treat it as opaque.

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/recipes"
{  "recipes": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "user_id": "string",      "title": "Brown Butter Chocolate Chip Cookies",      "subtitle": "string",      "description": "string",      "notes": "",      "tags": [        "dessert",        "cookies"      ],      "ingredients": [        {          "name": "all-purpose flour",          "quantity": 2.5,          "unit": "cups",          "preparation": "sifted",          "isOptional": false        }      ],      "components": [        {          "title": "Brown butter frosting",          "description": "string",          "notes": "string",          "ingredients": [            {              "name": "all-purpose flour",              "quantity": 2.5,              "unit": "cups",              "preparation": "sifted",              "isOptional": false            }          ],          "instructions": [            "string"          ]        }      ],      "instructions": [        "string"      ],      "media": [        {          "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",          "url": "http://example.com",          "blur_hash": "string",          "width": 0,          "height": 0,          "kind": "image"        }      ],      "blur_hash": "string",      "prep_time": 20,      "cook_time": 12,      "servings": 24,      "difficulty": "easy",      "rating": 0,      "source_section": "string",      "nutrition": {        "calories": 0,        "protein_g": 0,        "fat_g": 0,        "carbs_g": 0,        "fiber_g": 0,        "sugar_g": 0,        "sodium_mg": 0,        "per": "serving",        "computed_at": "2019-08-24T14:15:22Z",        "ingredients_hash": "string"      },      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "revoked_ids": [    "e0e0dcb4-2924-4752-8089-806dabd7e102"  ],  "server_timestamp": "2019-08-24T14:15:22Z",  "full_sync_required": true,  "next_cursor": "string"}

Stream recipe change events GET

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.

Save a copy POST

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.