# Introduction

Flashpoint.AI is a research data and insight platform. These docs cover everything you need to integrate Flashpoint.AI into your product or workflow.

## What's here

- **Quickstart** — get a key, make your first request, see data come back
- **Authentication** — API keys, scopes, rotation
- **API Reference** — every endpoint, request, response
- **Errors** — error codes and how to recover

## Design principles

The Flashpoint.AI API is designed around three commitments:

1. **REST over RPC.** Every resource has a stable URL. Verbs map to HTTP methods.
2. **Stable contracts.** Versions are pinned in the URL. Breaking changes get a new version, never a silent rewrite.
3. **Predictable errors.** Every failure mode has a documented code, an HTTP status, and a recovery path.

## For agents

Every page in these docs is available as raw markdown. Replace the path prefix with `/raw` to fetch the source:

```
GET https://docs.flashpoint.ai/quickstart       → rendered HTML
GET https://docs.flashpoint.ai/raw/quickstart   → raw markdown (text/markdown)
```

Or click **View as markdown** at the top of any page.

## Conventions

- Code samples default to `curl`. Tabs for language alternatives are coming.
- Field names in prose are wrapped in backticks: `client_id`, `Authorization`.
- Required parameters are flagged inline. Optional parameters note their default.


---

# Quickstart

Make your first authenticated request to the Flashpoint.AI API in under five minutes.

## 1. Get an API key

Sign in to the [dashboard](https://app.flashpoint.ai) and create a key under **Settings → API Keys**. Copy it once — you won't be able to view it again.

## 2. Set your environment

```bash
export FLASHPOINT_API_KEY="fp_live_..."
```

## 3. Make a request

```bash
curl https://api.flashpoint.ai/v1/datasets \
  -H "Authorization: Bearer $FLASHPOINT_API_KEY"
```

You should receive a `200 OK` with a JSON list of datasets your key has access to.

## 4. Handle the response

```json
{
  "data": [
    {
      "id": "ds_a1b2c3",
      "name": "Example dataset",
      "created_at": "2026-04-15T12:00:00Z"
    }
  ],
  "has_more": false
}
```

## Next steps

- Learn how scopes work in [Authentication](/authentication)
- Browse every endpoint in the [API Reference](/api-reference)
- Map error codes to recovery in [Errors](/errors)


---

# Surveys

Flashpoint runs end-to-end survey research from a natural-language objective — design, recruit, field, analyze, deliver. The same surface serves human researchers and autonomous agents.

## What we do

Hand us a research objective in plain English. We plan a multi-step workflow, execute the steps, and return the artifacts: the questionnaire, the recruited panel, the response data, the analysis, the deck. No survey software to learn.

## How it works

A single objective decomposes into a typed plan. Steps execute in dependency order — some immediately (questionnaire design), others queued (synthetic fielding, deck generation). Outputs from one step flow into later steps by reference, so a panel created in step one is consumed by step two with its real ID. Artifacts stream back as steps complete. Destructive actions — publishing, sending an email blast, excluding responses — pause for explicit approval before they run.

## Design

Author questionnaires with twenty question types, grouped into ordered blocks (sections). Logic, randomization, quotas, translations, and versioning are first-class.

### Question types

| Type | What it captures |
|---|---|
| `single-select` | Pick one from a list |
| `multi-select` | Pick any number from a list |
| `ranking` | Drag to rank options by preference |
| `grid` | Matrix — one answer per row |
| `multi-grid` | Matrix — multiple answers per row |
| `text` | Free-form open response |
| `multi-text` | Multiple short text inputs in one question |
| `contact-form` | Structured contact fields (name, email, phone) |
| `number` | Numeric input with optional min/max |
| `currency` | Currency amount with currency code |
| `percentage` | Single 0–100 percentage |
| `multi-percentage` | Multiple percentage inputs |
| `percent-sum` | Allocate percentages that must total 100 |
| `year` | Year input |
| `zipcode` | Postal/ZIP with country-specific validation |
| `nps` | Net Promoter Score (0–10, pre-configured) |
| `maxdiff` | Best/worst scaling |
| `conjoint` | Choice-based conjoint with attributes and levels |
| `van-westendorp` | Price sensitivity meter (four price points) |
| `transition` | Display-only text or instructions, no answer collected |

### Logic and structure

- **Blocks** — Questions live inside ordered sections. Block order can be randomized.
- **Skip logic** — Branch to another question or section based on prior answers.
- **Disqualification** — Terminate a respondent on screener conditions.
- **Display logic** — Show or hide questions based on prior answers.
- **Option randomization** — Shuffle answer order; supports anchored options and per-group shuffling.
- **Option piping** — Carry answers from one question into another's options.
- **Quotas** — Sampling targets by respondent profile.
- **Translations** — Multi-language questionnaires.
- **Versioning** — Push a version, restore an earlier one.

## Recruit

- **Synthetic personas** — AI-generated respondents with demographics and psychographics. Configurable size and profile.
- **Prolific** — real respondents recruited via the Prolific panel.
- **Email lists** — distribute to your own list with editable email drafts.
- **Dynata, Veridata** — coming soon.

## Field

Synthetic and real respondents complete the questionnaire end to end. Quotas are enforced during fielding. Responses are captured with timing and source metadata.

## Analyze

- **Descriptives** — frequencies, means, distributions
- **NPS** — promoter/passive/detractor breakdowns
- **Crosstabs** — pivot any two questions
- **Conjoint** — utility scores from choice-based conjoint
- **MaxDiff** — best-worst utility scoring
- **Open-end themes** — clustering and theme extraction from free text

## Deliver

- **Tabular** — CSV, XLSX
- **Document** — PDF report
- **Presentation** — auto-generated, editable PowerPoint deck
- **Raw** — survey definition export (qsf, docx, xml)

## Manage

- **Lifecycle** — publish, pause, resume, complete, clone, delete
- **Versioning** — push a version, restore an earlier one
- **Responses** — exclude individual responses, relaunch panels
- **Email distribution** — send and resend to lists


---

# Authentication

The Flashpoint.AI API uses bearer-token authentication over HTTPS. There are no cookies, no signed requests, and no session state.

## API keys

Every request must include an `Authorization` header:

```
Authorization: Bearer fp_live_...
```

Keys are issued from the dashboard and are scoped to a single workspace. Treat them like passwords — never commit one to a repo or paste one into client-side code.

## Key prefixes

| Prefix      | Purpose                                  |
|-------------|------------------------------------------|
| `fp_live_`  | Production traffic                       |
| `fp_test_`  | Sandbox traffic — separate billing/data  |

## Scopes

Scopes restrict what a key can do. Set them at key creation time.

| Scope         | Allows                            |
|---------------|-----------------------------------|
| `read`        | `GET` on datasets and queries     |
| `write`       | `POST`, `PATCH`, `DELETE`         |
| `admin`       | Workspace and member management   |

A key with `read` cannot create or modify resources. Mint short-lived `write` keys for build pipelines and rotate them on a schedule.

## Rotating keys

```bash
curl -X POST https://api.flashpoint.ai/v1/keys/rotate \
  -H "Authorization: Bearer $FLASHPOINT_API_KEY"
```

The old key remains valid for 60 minutes after rotation to give deployments time to drain.

## Revoking keys

Revoke from the dashboard or via the API. Revocation is immediate; in-flight requests under the revoked key will return `401`.


---

# Errors

Every error response uses the same shape:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 12s.",
    "request_id": "req_01HXYZ..."
  }
}
```

Always log `request_id` — support can resolve issues an order of magnitude faster when you include it.

## Status codes

| Status | Meaning                                                     |
|--------|-------------------------------------------------------------|
| `400`  | Malformed request — missing or invalid parameter            |
| `401`  | Missing, invalid, or revoked API key                        |
| `403`  | Authenticated, but the key lacks the required scope         |
| `404`  | Resource does not exist or is not visible to this workspace |
| `409`  | State conflict — the resource changed under you             |
| `422`  | Validation failed on a syntactically valid request          |
| `429`  | Rate-limited — see `Retry-After` header                     |
| `5xx`  | Server-side. Safe to retry with backoff.                    |

## Error codes

| Code                 | When                                            |
|----------------------|-------------------------------------------------|
| `invalid_request`    | The body or query string failed parsing         |
| `invalid_api_key`    | Key not recognized                              |
| `insufficient_scope` | Key authenticated but missing the needed scope  |
| `not_found`          | Resource ID does not exist                      |
| `rate_limited`       | Quota exhausted for this minute or day          |
| `internal_error`     | Server-side fault — opens an internal incident  |

## Retry policy

Retry `429` and `5xx` with exponential backoff and full jitter. Cap retries at 5 attempts. Do not retry `4xx` other than `429` — the request will fail again.


---

# API Reference

Base URL:

```
https://api.flashpoint.ai/v1
```

All requests require a [bearer token](/authentication). All responses are JSON unless explicitly noted.

## Datasets

### List datasets

```
GET /datasets
```

**Query parameters**

| Name       | Type    | Default | Description                                  |
|------------|---------|---------|----------------------------------------------|
| `limit`    | integer | `20`    | Max items per page. Range: 1–100.            |
| `cursor`   | string  | —       | Opaque cursor returned in the previous page. |

**Response**

```json
{
  "data": [
    {
      "id": "ds_a1b2c3",
      "name": "Example dataset",
      "created_at": "2026-04-15T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### Retrieve a dataset

```
GET /datasets/{id}
```

Returns a single dataset. `404` if the ID is unknown or not visible to the calling workspace.

## Queries

### Run a query

```
POST /queries
```

**Body**

```json
{
  "dataset_id": "ds_a1b2c3",
  "query": "SELECT count(*) FROM rows WHERE created_at > '2026-01-01'"
}
```

**Response — 200**

```json
{
  "id": "qry_xyz",
  "status": "succeeded",
  "rows": [{ "count": 42 }]
}
```

**Response — 422**

Validation failed. The body is valid JSON, but `query` could not be planned. See [Errors](/errors).

## Pagination

Cursor-based. Pass the `next_cursor` from the previous response back in as `cursor` to fetch the next page. Cursors are opaque — do not parse them.

## Rate limits

- **Production keys** — 600 requests / minute / workspace
- **Sandbox keys** — 60 requests / minute / workspace

Limit headers are returned on every response:

```
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 583
X-RateLimit-Reset: 1746230400
```