# Flaunt Data API

> Programmatic, read-only access to your Flaunt data warehouse — for building live dashboards and agentic workflows. 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}/queries` — List a report's queries
- `GET /v1/data/queries` — List saved queries
- `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. Reuse proven queries: `GET /v1/data/reports?brandId=…` → `GET /v1/data/reports/{reportId}/queries?brandId=…`, or `GET /v1/data/queries` for standalone saved queries.
3. `POST /v1/data/query` — run a query: either `{ "sql": "…" }` or `{ "queryId": "…", "period": { "cadence": "MONTHLY" } }`.
4. 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` ``.
- `"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 } }`.