# Flaunt Data API

> Programmatic, read-only access to your brands' retention data warehouse, built for AI agents — email, SMS, e-commerce, subscription and customer service data in one place, plus the Flaunt and custom reports built on it. Use it to run existing reports, to investigate a question no report covers yet, or to power a custom dashboard or app — without stringing together separate platform APIs and reconciling them yourself. Authenticate with a Bearer API key scoped to either one organization (all its brands) or a single brand.

Base URL: `https://api.flaunt.xyz` · Read-only (a single SELECT/WITH statement). Send `Authorization: Bearer <key>`.

## Specification
- [OpenAPI 3.1 spec](https://api.flaunt.xyz/v1/data/openapi.json): the complete machine-readable contract — prefer this for codegen.
- MCP server: `https://api.flaunt.xyz/v1/data/mcp` — the same capabilities over the Model Context Protocol (Streamable HTTP, Bearer auth).
- [Interactive reference](https://developers.flaunt.xyz): human docs with a "try it" client.
- [Full text for LLMs](https://developers.flaunt.xyz/llms-full.txt): this guide with every endpoint description + the quickstart inlined.

## Endpoints
- `GET /v1/data/brands` — List brands
- `GET /v1/data/reports` — List reports
- `GET /v1/data/reports/{reportId}` — Get a report
- `GET /v1/data/reports/{reportId}/versions` — List a report's versions
- `GET /v1/data/reports/{reportId}/queries` — List a report's queries
- `GET /v1/data/queries` — List saved queries
- `POST /v1/data/memories/search` — Search Flaunt's memories for a brand
- `POST /v1/data/query` — Run a query
- `POST /v1/data/feedback` — Report a data issue

## Typical flow
1. `GET /v1/data/brands` — the brands your key can access (each with its `dataset`).
2. **Before writing SQL for anything non-trivial**: `POST /v1/data/memories/search` with a `{ "query": "…" }` phrased as a full question. This returns what Flaunt's own analyst reads first — what a table means, its grain and join keys, and the frameworks for interpreting subscription/retention/attribution data. `table_metadata` tells you a column exists; these tell you what it means, which is the difference between a correct number and a correct number you describe wrongly.
3. Reuse proven queries: `GET /v1/data/reports?brandId=…` → `GET /v1/data/reports/{reportId}/queries?brandId=…`, or `GET /v1/data/queries` for standalone saved queries.
4. `POST /v1/data/query` — run a query: either `{ "sql": "…" }` or `{ "queryId": "…", "period": { "cadence": "MONTHLY" } }`.
5. If the data looks wrong: `POST /v1/data/feedback` with a `{ "summary": "…" }` (+ optional `expected`/`observed`/`brandId`) to file it with the Flaunt data team — the key's recent queries are attached automatically.

## Conventions
- Read-only: a single `SELECT`/`WITH` statement. Reference tables as `` `flaunt-v1.<dataset>.<table>` `` using the `dataset` from `GET /v1/data/brands`.
- Discover tables (no schema endpoint): `` SELECT table_name, layer, data_source FROM `flaunt-v1.<dataset>.table_metadata` ``.
- Understand them: `POST /v1/data/memories/search`. Results are tagged by class — `["expertise"]` memories say how to run an analysis correctly (read before planning), `["forge","table-schema"]` memories say what a table's columns mean (read once you know which tables you need). Responses are large; `detail: "metadata"` surveys cheaply, then fetch bodies by `ids`.
- `"dryRun": true` estimates bytes scanned without running or billing.
- Each key has a rolling-24h usage limit (`429 USAGE_LIMIT_EXCEEDED`).
- Every response carries an `x-request-id` header; errors are `{ error: { code, message, requestId } }`.