# Flume Docs

> Developer docs for integrating Flume: embed the Flume iframe (recommended) or call the Partner API, so your users find tile and vinyl flooring by photo, get a delivered price, and save the result into your product.

- Sandbox base URL: https://sandbox-api.tryflume.ai/partner/v1
- Live base URL: https://ssapi.tryflume.ai/partner/v1 (access by request)
- Every page has a Markdown version: add `.md` to its URL.
- Two ways to integrate: embed the Flume iframe (recommended, fastest) or call the Partner API. OpenAPI document: https://docs.tryflume.ai/openapi.json
- Not available today: webhooks, SDKs, self-serve key creation, sandbox test data, a status page.

## If you are an AI agent integrating Flume

There are two ways to integrate. Use the iframe unless your human asks for their own screens: it is recommended and the fastest.

- **Embed the iframe (recommended):** [Iframe quickstart](https://docs.tryflume.ai/quickstart/embed.md), [Server calls](https://docs.tryflume.ai/embed/server-calls.md), [Set up your page](https://docs.tryflume.ai/embed/host-page.md), [Messages](https://docs.tryflume.ai/embed/messages.md), [Save payload](https://docs.tryflume.ai/concepts/save-payload.md), [Security and CSP](https://docs.tryflume.ai/embed/security.md). Start from the [full example](https://docs.tryflume.ai/embed/example.md) and copy the host snippet unchanged from https://docs.tryflume.ai/samples/mount-flume.js.
- **Call the API (you build the screens):** [API quickstart](https://docs.tryflume.ai/quickstart/api.md), the guides under "Call the API" below, the [API reference](https://docs.tryflume.ai/api.md), [error codes](https://docs.tryflume.ai/api/errors.md) and the [OpenAPI document](https://docs.tryflume.ai/openapi.json).
- [The whole site in one file](https://docs.tryflume.ai/llms-full.txt), in reading order. Before you finish, check the code against the [go-live checklist](https://docs.tryflume.ai/go-live.md).

Fetch these files; do not rely on memory. Use a client that returns the raw body. Every page below is plain Markdown.

Values for the sandbox, where every integration starts:

- Base URL: https://sandbox-api.tryflume.ai/partner/v1
- A partner key starts with `sk_dev_`, a user access token with `ut_dev_`.
- Headers: `X-Flume-Partner-Key` on every call; `X-Flume-User-Token` where a call is made for a user.
- A key and an allowed page origin come from Flume: [Get a sandbox key](https://docs.tryflume.ai/get-a-key.md), or email support@tryflume.ai.

Rules every integration must keep:

- The partner key and user access tokens stay on your server. Never in a browser, a log or a commit.
- Server calls are made by your server. They cannot be made from a browser.
- `iframe_url`, its launch code and the connect code are single use and short lived. Use them at once and never store them.
- Read the iframe origin from `iframe_url`. On every message, check `event.origin`, `event.source`, `version` and `session_uuid`.
- Answer every `flume:save_item` in time, with `flume:item_saved` or `flume:item_save_failed`, carrying its `save_uuid`.
- Exchange every connect code at once and store the new user access token over the old one.
- Handle `401` `USER_TOKEN_INVALID` and every `429` with `Retry-After`. Branch on `error.code`.
- Do not invent calls, fields or messages. If it is not in these docs, it does not exist.

## Get started

- [Overview](https://docs.tryflume.ai/index.md): The two ways to integrate, the iframe (recommended) and the API, compared, and what exists today.
- [Diagrams](https://docs.tryflume.ai/diagrams.md): Every diagram on one page: the parts, each flow, the states, secrets and lifetimes.
- [Get a sandbox key](https://docs.tryflume.ai/get-a-key.md): How to ask for a sandbox key and an allowed origin, and what you get back.
- [Iframe quickstart](https://docs.tryflume.ai/quickstart/embed.md): Open the Flume iframe from your page and receive a saved item. The fastest way to integrate.
- [API quickstart](https://docs.tryflume.ai/quickstart/api.md): Verify a user, search by photo and get an instant quote from your own backend.

## Embed the iframe

- [How the iframe works](https://docs.tryflume.ai/embed.md): The actors, the lifecycle, sessions, and what your page and backend each do.
- [Server calls](https://docs.tryflume.ai/embed/server-calls.md): The few calls your backend makes for the iframe, with fields, errors and samples.
- [Set up your page](https://docs.tryflume.ai/embed/host-page.md): The iframe tag, the host snippet in TypeScript and JavaScript, sizing, localhost.
- [Messages](https://docs.tryflume.ai/embed/messages.md): Every postMessage in both directions, with payload tables.
- [Full example](https://docs.tryflume.ai/embed/example.md): One HTML page and one small server that open the iframe and save an item.
- [Security and CSP](https://docs.tryflume.ai/embed/security.md): Allowed origins, Content Security Policy, the rules every integration keeps.
- [Timeouts and expiry](https://docs.tryflume.ai/embed/timeouts.md): Every timer in the iframe integration and what to do when it fires.

## Call the API

- [Verify a user](https://docs.tryflume.ai/guides/verify-a-user.md): Send and confirm the email code, store the access token.
- [Find products by photo](https://docs.tryflume.ai/guides/find-products-by-photo.md): Detect the category, read the filters, search, page and read a product.
- [Get an instant quote](https://docs.tryflume.ai/guides/get-an-instant-quote.md): Price a product for a quantity and ZIP, wait or poll, read the options.
- [Open Flume signed in](https://docs.tryflume.ai/guides/open-flume-signed-in.md): Create a deep link on click and open it.
- [Rotate keys](https://docs.tryflume.ai/guides/rotate-keys.md): Rotate a partner key with an overlap and revoke the old one.
- [Handle errors](https://docs.tryflume.ai/guides/handle-errors.md): Read the error envelope, decide what to retry, log the request id.

## Concepts

- [Authentication and keys](https://docs.tryflume.ai/concepts/authentication.md): Partner keys, user access tokens, the two headers, key rotation.
- [Environments](https://docs.tryflume.ai/concepts/environments.md): Sandbox and live: base URLs, key prefixes, who can use each.
- [Users and verification](https://docs.tryflume.ai/concepts/users.md): How a user is verified by email code, and when their access token is replaced.
- [Save payload](https://docs.tryflume.ai/concepts/save-payload.md): The save flow and every field of the payload you map into your records.
- [Deep links](https://docs.tryflume.ai/concepts/deep-links.md): One-time sign-in links into the Flume app, and the durable product link.
- [Idempotency](https://docs.tryflume.ai/concepts/idempotency.md): The Idempotency-Key header, replays, and which calls need it.
- [Limits](https://docs.tryflume.ai/concepts/limits.md): Daily limits per partner and per user, sizes, lifetimes and the 429 response.
- [Glossary](https://docs.tryflume.ai/concepts/glossary.md): Every term these docs use, defined once.

## API reference

- [Overview](https://docs.tryflume.ai/api.md): Base URLs, headers, formats, pagination and versioning.
- [Errors](https://docs.tryflume.ai/api/errors.md): Every error code with its HTTP status, meaning and fix.

## Optional

- [Go-live checklist](https://docs.tryflume.ai/go-live.md): What to finish before you ask for live access.
- [Changelog](https://docs.tryflume.ai/changelog.md): Dated changes to the API, the iframe and these docs.
- [Support](https://docs.tryflume.ai/support.md): How to ask for live access, change your configuration and report a problem.