Built for agents

A large share of the traffic to these docs is not human. This section is the short version of everything an agent needs.

Three ways in

The fastest possible orientation

https://docs.flambe.dev/llms.txt        # index of every page
https://docs.flambe.dev/llms-full.txt   # the entire corpus, one file
https://docs.flambe.dev/openapi.yaml    # the API contract
https://docs.flambe.dev/openapi.json    # same, as JSON

Append .md to any docs URL for its Markdown source. The site also honours content negotiation — send Accept: text/markdown and you get Markdown back from the canonical URL.

curl -H 'Accept: text/markdown' https://docs.flambe.dev/docs/guides/imports
# or
curl https://docs.flambe.dev/docs/guides/imports.md

The eight things that actually trip agents up

Most integration failures against this API come from the same handful of assumptions. If you read nothing else:

1. Imports are asynchronous. POST /api/imports returns 201 with status: "pending" and no recipe. Poll the import or subscribe to the event stream. See Imports.
2. media and image_batch are different. media reads several images as one recipe; image_batch treats each image as its own. Picking wrong collapses unrelated photos into one garbled recipe.
3. The 401 message matters. Access token required means the header was never sent — refreshing cannot help and retrying loops forever. Invalid or expired token is the one worth a refresh. See Authentication.
4. Delta sync has a 25-day cliff. A watermark older than 25 days returns full_sync_required: true and an empty result. Ignore the flag and the client silently stops updating. See Syncing.
5. EventSource cannot authenticate. The browser API cannot set an Authorization header. Use a fetch-based SSE reader. See Live events.
6. Household bulk grants revoke omissions. PUT .../library/{type}/bulk replaces the entire grant set. A partial list un-shares everything missing from it. See Households.
7. CDN widths are a fixed list. Only 320, 480, 640, 800, 960, 1200, 1600 exist; any other width silently serves the full-resolution original. See Files.
8. /changes takes a sequence number, not a timestamp. Unlike updated_since, the since on /api/recipes/changes is numeric. An ISO string returns 400.

Writing code against this API

• Base URL is https://api.flambe.dev. There is no sandbox host — use a dedicated test user.
• Every endpoint except GET /health and GET /api/shared/{token} needs Authorization: Bearer <clerk session jwt>.
• Fields are snake_case. Timer fields are camelCase — the one exception.
• Retry 429 and 5xx with jittered backoff. Never retry other 4xx.
• Writes are not idempotent unless documented. POST /api/imports has no idempotency key, so a timed-out create must be reconciled against GET /api/imports/working-set rather than retried blindly. Timers do accept idempotencyKey. See Errors and retries.

Check status before debugging

If calls fail broadly, status.flambe.dev publishes live component health — the web service, the apps, and each import queue separately. https://status.flambe.dev/api/v1/status.json is the machine-readable form.