# Flowformance Agent API

The Flowformance Agent API gives your own agents and scripts keyed, read-only access to a workspace’s published SOPs — the same documents your team reads, served as clean markdown, structured steps, or cited answers. Everything under `/v1` needs a paid plan and a Bearer key. Team-visibility docs are included for the key holder; drafts never are.

Base URL: `https://flowformance.com/v1`

## Authentication

- Mint a key from **Settings → API keys** (owner only). Keys look like `ff_live_` followed by 32 characters. The secret is shown once at creation — store it somewhere safe; we only keep a hash.
- Send it as a Bearer token on every request: `Authorization: Bearer ff_live_…`.
- Each key is limited to 120 requests per minute, and a workspace to 360 requests per minute across all of its keys. Limits are counted in one-minute windows and are approximate. A failed auth never costs you quota.
- `/v1/answer` has a tighter limit: 20 answers per minute for the workspace — all of its keys together — within 60 AI requests per minute for the workspace as a whole, which in-app Ask and Assist count toward too.
- A workspace can hold up to 25 live keys; minting another returns `409 conflict` until you revoke one.
- Revoke a key any time from the same screen; revoked keys stop working immediately.
- A key also stops working when the owner who created it leaves the workspace or stops being an owner, or when the workspace is deleted — have a current owner mint a new one.

## Endpoints

### GET /v1/docs

List published docs (team + public) as JSON summaries.

Parameters:

- `query` — Case-insensitive substring over title + summary.
- `collection` — Limit to one collection id.
- `type` — `overview` or `process`.

Returns: `{ docs: [{ id, slug, title, type, summary, verified_at, url }] }`. `url` is the markdown endpoint for that doc.

```
curl -H "Authorization: Bearer ff_live_…" \
  "https://flowformance.com/v1/docs?query=refund&type=process"
```

### GET /v1/docs/{slug}

Fetch one published doc as markdown (default) or structured steps.

Parameters:

- `format` — `md` (default) returns raw markdown + frontmatter; `steps` returns deterministic steps JSON.

Returns: `md`: `text/markdown`. `steps`: `{ id, title, type, version, verified_at, intro, steps:[{ n, title, body_md, image_url? }], callouts:[{ n, text }] }` — a pure parse of the markdown, no AI, so it is stable across calls. Image links (in the markdown and `image_url`) are temporary signed links that work without your key for 1–2 hours — fetch the doc again for fresh ones.

```
curl -H "Authorization: Bearer ff_live_…" \
  "https://flowformance.com/v1/docs/handle-a-refund?format=steps"
```

### GET /v1/answer

Ask a question and get a cited answer drawn only from published docs.

Parameters:

- `q` (required) — The question (max 1000 characters).

Returns: `{ answer_md, citations:[{ slug, heading }] }`. Fetch each cited `slug` via `/v1/docs/{slug}` for the full source. Limited to 20 answers per minute across the workspace’s keys (see Authentication).

```
curl -H "Authorization: Bearer ff_live_…" \
  "https://flowformance.com/v1/answer?q=How%20do%20I%20issue%20a%20refund%3F"
```

### GET /v1/llms.txt

A keyed llms.txt index of the workspace, including team docs.

Returns: `text/plain` — a curated index linking to each doc’s markdown endpoint.

```
curl -H "Authorization: Bearer ff_live_…" \
  "https://flowformance.com/v1/llms.txt"
```

### GET /v1/captures

List the leads your email-capture forms collected, newest first.

Parameters:

- `since` — Only leads captured at or after this time (epoch milliseconds).
- `cursor` — The `next_cursor` from the previous page.
- `limit` — Page size, 1–200 (default 50).

Returns: `{ captures:[{ id, email, first_name, doc_slug, doc_title, video_title, source, confirmed, created_at }], next_cursor }`. `next_cursor` is `null` on the last page. `created_at` is ISO 8601.

```
curl -H "Authorization: Bearer ff_live_…" \
  "https://flowformance.com/v1/captures?limit=50"
```

## Errors

Every error is `{ "error": { "code", "message" } }` with the matching HTTP status.

- `401 unauthorized` — Missing, malformed, or revoked key, or one whose creator is no longer an owner.
- `403 forbidden` — The workspace is not on a plan that includes the API — or, on `/v1/answer`, this month’s answer limit is reached (it resets next month).
- `404 not_found` — No published doc with that slug, or unknown route.
- `400 bad_request` — An unsupported format or a missing question.
- `429 rate_limited` — Over 120 requests in the current minute on this key, or over 360 across all of the workspace’s keys — or, on `/v1/answer`, over 20 answers this minute across the workspace’s keys, or over 60 AI requests this minute for the whole workspace. Wait for the next minute.