# The FlowQA API

> Authentication, the routes for projects, tests, drafts, runs, explorations, repairs and schedules, and the errors they answer, for scripts, CI and agents.

The FlowQA API is the HTTP API behind the FlowQA workbench, FlowQA Desktop and the TestFinch connector for coding agents.
Anything they do with tests, you can do from a script, a CI job or your own agent: read and write tests, run them on our browsers, start explorations, answer the agent's questions and review repairs.
This page is the reference for those routes.
For a coding agent, the [TestFinch connector](/docs/coding-agents/) wraps the same API in tools and is the quicker start.

## Base URL and format

Every route is under `https://api.testfinch.com`.
Requests and responses are JSON, with `Content-Type: application/json` on every request that has a body.
Field names are `snake_case`.
Ids are opaque strings; keep them as you receive them.

## Authentication

Send a token in the `Authorization` header on every request:

```http
GET /v1/qa/projects HTTP/1.1
Host: api.testfinch.com
Authorization: Bearer snag_pat_...
```

For scripts and CI, use a personal access token.
Create one in TestFinch under Settings, API tokens.
A token belongs to one workspace, acts as the person who created it, with that person's role, and can be limited to some of the workspace's projects.
It has one of two scopes:

| Scope | What it can do |
| --- | --- |
| `read` | Every read: projects, tests, revisions, runs, explorations, questions, repairs, schedules. |
| `read_write` | Reads, plus every change: saving and deleting tests, starting runs and explorations, answering questions, deciding repairs. |

A token is shown once, when you create it.
Store it as a secret, and revoke it in the same settings page when it is no longer needed.

Coding agents connected through the TestFinch connector sign in with OAuth instead, and act with the same permissions as the person who connected them.

### Signing in from the CLI

The [TestFinch CLI](https://testfinch.com/docs/testfinch-cli/) signs in with OAuth as the first-party client `cli_testfinch`, and every request it makes carries `X-Snag-Via: cli`, so what it does shows as done through the CLI.

| Route | What it does |
| --- | --- |
| `POST /oauth/device_authorization` | Starts a sign-in with a code, for a computer with no browser. Body: `client_id` and `scope`. The answer has `device_code`, `user_code`, `verification_uri`, `expires_in` and `interval`. The person opens `verification_uri` and types `user_code`. |
| `POST /oauth/token` | Exchanges the code, a device code or a refresh token for an access token. While the person has not approved, it answers `authorization_pending`, and `slow_down` if you ask too often. |
| `POST /oauth/revoke` | Ends a sign-in. Body: `client_id` and `token`. `testfinch logout` calls it. |

The scope `local_runs` lets the sign-in run tests on the person's own computer.
Only `cli_testfinch` can ask for it, and the person approves it on the sign-in page.
Personal access tokens, the connector and other OAuth clients never get it.

### What only a person can do

Some actions stay with the person, signed in to TestFinch or FlowQA Desktop.
A token or a connected app that asks for one of these gets `403 forbidden`, with a message that says where to do it instead:

- creating, archiving and deleting projects;
- inviting and managing members;
- creating schedules and CI triggers;
- running tests or explorations on your own machine, which FlowQA Desktop does, and running tests there with the TestFinch CLI, signed in as yourself;
- reading secret values, such as test account passwords;
- giving the agent a test account when an exploration asks for one.

One more is closed to personal access tokens only: proposing a repair.
A connected app such as the TestFinch connector, or a signed-in person, may propose one.

## The objects

A **project** is one application under test.
It holds its tests and its bugs, and belongs to a workspace.
Its **configuration** names the app, its **environments** (each a base URL and the hosts a test may visit, such as `preview` and `production`), its **modules** and its **suites**.

A **test** is a Flow definition: a named list of steps and assertions, with an id of the form `module/slug`.
Every save makes a new immutable **revision**, numbered from 1.
A test may be **reusable**, as an opening other tests start with (signing in, for example), through a `use` step.

A **draft** is a test being written or edited by one person, saved step by step, and published as the next revision when it is reviewed.

A **run** (an execution) runs chosen tests, each at a pinned revision, in one environment, on our browsers or on a desktop.
It records each test's result, the failing step, screenshots, console errors and failed network requests.

An **exploration** is a session of the AI agent on your site: it maps the pages, proposes journeys and generates a test for each journey you approve.
When it needs something only a person knows, it asks a **question**.

A **repair** is a proposed change to a test that failed on a changed page, proven by replaying it, and applied only when someone approves it.

A **schedule** runs a selection of tests on a cron expression; a **CI trigger** is a secret URL that runs them from a pipeline.

## Routes

`GET /v1/qa/projects` lists the projects with tests that you can see, each with its `project_id`, `name`, `workspace_id`, `workspace_name` and `app`.
Everything else about a project is under `/v1/projects/:projectId/qa`, which the tables below leave out: `/tests` is `/v1/projects/:projectId/qa/tests`.

### Configuration

| Route | What it does |
| --- | --- |
| `GET /configuration` | The configuration and its `revision`; 404 when the project has no tests yet. |
| `PUT /configuration` | Replace the configuration: `expected_revision` and `configuration`. Admins only. |

### Tests

| Route | What it does |
| --- | --- |
| `GET /tests` | Test summaries. `limit` 1 to 100 and the `after` cursor page through them; `module`, `suite_id` and `query` filter; `include` adds `definition`, `findings` or `last_result` (comma separated). |
| `GET /tests/:testId` | One test: its summary, its complete definition, `findings` and its five most recent results. |
| `GET /tests/:testId/revisions/:revision` | One published revision, with `content_hash`, `created_by`, `origin`, `agent` and `created_at`. |
| `POST /tests/save` | Create or update 1 to 50 tests in one call (below). |
| `POST /tests/delete` | Delete tests at the revisions you read (below). |
| `POST /organize` | Add, rename or remove modules, set suites, move tests and set their order, in one call. |

### Drafts

| Route | What it does |
| --- | --- |
| `GET /drafts` | Your open drafts, paged like the tests. |
| `POST /drafts` | Start a draft, or recover one, by `idempotency_key`. |
| `GET /drafts/:draftId` | The draft and its last accepted `sequence`. |
| `PUT /drafts/:draftId` | Save a checkpoint: the next `sequence` and the complete `definition`. |
| `POST /drafts/:draftId/save` | Publish the reviewed checkpoint, `expected_sequence`, as the test's next revision. |
| `POST /drafts/:draftId/discard` | Discard the draft; published tests are untouched. |

Drafts belong to the person who started them; nobody else can read or publish them.

### Runs

| Route | What it does |
| --- | --- |
| `POST /executions` | Start a run: `idempotency_key`, `target` (`cloud`, or `local` with the `local_runs` sign-in), `environment`, `tests` (1 to 100 of `{ test_id, revision }`), an optional `label` and an optional `base_url`. |
| `GET /executions` | Recent runs. |
| `GET /executions/:executionId` | One run: `status` and, per test, its result, the failing step, `artifacts`, `console_errors` and `network_failures`. |
| `GET /executions/:executionId/artifacts?path=` | One screenshot from the run, as base64. |
| `POST /executions/:executionId/cancel` | Cancel a run that has not finished. The person who started it, or an admin. |

A run's `origin` says who started it: `manual`, `mcp`, `cli`, `schedule` or `trigger`.

`base_url` points the environment at another address for this run only, such as `http://localhost:3000` or a preview:

- An address on this computer or a private network needs `target: "local"`. A cloud run to such an address is refused. A local run to it does not wait for, or block, the team's cloud runs of the environment.
- Any other address has to be the environment's own address or one of its allowed hosts, or the run is refused and names the host to add.
- A cloud run needs `https`.
- It cannot hold a user name or password.
- Site passwords and sign-ins are sent only to the environment's own address, so a test that needs one on another address stops and says so.

A person can start at most 600 local runs an hour.
After that, `POST /executions` answers `429 rate_limited` with `details.retry_after_seconds`, and the message says how many minutes to wait.

A local run is claimed and reported through `POST /executions/:executionId/{claim,heartbeat,baselines,artifacts,complete}` by whatever runs the tests, which is the CLI or FlowQA Desktop.
A run started by the CLI, or by a trigger on the CI machine, runs on the Chromium combinations only, and lists the others in `skipped_combinations`.

A run's `status` is `queued`, `running`, `completed`, `failed`, `cancelled` or `expired`.
A test's result is `pass`, `fail`, `blocked`, `flaky` or `skipped`.
Poll the run until it is no longer `queued` or `running`.
Screenshots are kept for your plan's retention; after that, the artifact route answers `410 gone`.
`GET /v1/qa/cloud/status` says how many cloud browsers are online and free, as `{ browsers: { total, available, busy }, explorations, updated_at }`.
`explorations` is `{ available, reason, message }`: `available: false` (with `reason` `model_key_invalid` or `model_key_missing`) while no cloud browser can explore on TestFinch's model key.
Meanwhile `POST /explorations` on a cloud browser answers `409` with the code `explorations_unavailable`; tests still run, and a workspace with its own model key can still explore.

### Explorations and questions

| Route | What it does |
| --- | --- |
| `GET /explorations/estimate` | What an exploration of `journeys` journeys would use, before you start it. |
| `POST /explorations` | Start an exploration of an `environment`; optional `journeys`, `map_budget`, `depth`, `max_steps`, `allow_destructive` and `context` (what you know that the site does not show, up to 20,000 characters). |
| `GET /explorations` | Recent explorations. |
| `GET /explorations/:id` | One exploration: its progress, the map and the proposed journeys. |
| `POST /explorations/:id/approve` | Generate tests for the chosen journeys (`mode: "generate"` with `journeys`), or keep only the map (`mode: "hand_me_the_map"`). |
| `POST /explorations/:id/cancel` | Stop an exploration. |
| `GET /questions` | Questions across the project's explorations, newest first; `status` is `open` (the default), `answered`, `expired` or `all`. |
| `GET /explorations/:id/questions` | One exploration's questions. |
| `GET /explorations/:id/questions/:questionId/screenshot` | The page the agent was looking at, as `{ data, content_type }`. |
| `POST /explorations/:id/questions/:questionId/answer` | Answer with the fields the question's kind needs: `choice`, `value` (with `secret: true` for a value to keep hidden), `allow`, `yes`, `note` or `give_up`; for a test account, `account: { username, password }` or `skip: true`, which only a signed-in person may send. `remember` (default `true`) keeps the answer for next time. |

[When the AI agent asks a person](/docs/flowqa-questions/) explains each kind of question and how the answer travels.

### Repairs

| Route | What it does |
| --- | --- |
| `POST /tests/:testId/repairs` | Propose a repair for a failed run of the test: `execution_id`. Not with a personal access token. |
| `GET /repairs` | The latest 50 repairs, newest first; `status` and `test_id` filter. |
| `GET /repairs/:id` | One repair, with its proposed change. |
| `POST /repairs/:id/approve` | Apply a `proposed` repair as the test's next revision; optional `note`. |
| `POST /repairs/:id/reject` | Reject it; optional `note`. |

A repair's `status` is `queued`, `running`, `proposed`, `accepted`, `rejected`, `failed` or `cancelled`; `proposed` is the one waiting for a decision.
[Repairs](/docs/flowqa-repairs/) explains how a repair is found and proven.

### Site notes

| Route | What it does |
| --- | --- |
| `GET /notes` | The index of the project's notes, without their bodies. |
| `GET /notes/:kind/:name` | Read one note. |
| `PUT /notes/:kind/:name` | Write one note: `{ body, title?, summary? }`. |
| `DELETE /notes/:kind/:name` | Remove one note. |

[Site notes](/docs/flowqa-site-notes/) explains what they hold and who writes them.

### Schedules and CI triggers

| Route | What it does |
| --- | --- |
| `GET /schedules` | The project's schedules. |
| `PATCH /schedules/:id` | Change a schedule's `name`, `cron`, `timezone`, `environment`, `test_ids`, `enabled` or alerts. |
| `DELETE /schedules/:id` | Remove a schedule. |
| `POST /schedules/:id/run` | Run a schedule's tests now. |
| `GET /triggers` | The project's CI triggers, never their tokens. Each has `allow_local`. |
| `PATCH /triggers/:id` | Turn `allow_local` on or off. Signed in as yourself. |
| `DELETE /triggers/:id` | Revoke a trigger. |

Schedules and triggers are created in TestFinch, signed in as yourself.
A trigger is created with `allow_local` off.
With it on, the trigger can run its tests on the CI machine, which then receives each test value, secret ones included.
A CI job runs a trigger's tests with routes of their own, which need no other credential: the trigger token, sent as `Authorization: Bearer <token>`, is the credential, and a wrong, revoked or missing one is a 404.

| Route | What it does |
| --- | --- |
| `POST /v1/qa/triggers/run` | Run the trigger's tests. Optional `environment`, `tests` (flow ids), `label`, such as the commit being deployed, `target` (`cloud`, the default, or `local`) and `base_url`. |
| `GET /v1/qa/triggers/executions/:id` | That run's `status`, `done`, `ok`, `summary` and `results`. |
| `POST /v1/qa/triggers/executions/:id/{claim,heartbeat,baselines,artifacts,complete,cancel}` | Six routes the CLI uses to run a `local` run on the CI machine and to cancel it. |

Deprecated: `POST /v1/qa/triggers/:token/run` and `GET /v1/qa/triggers/:token/executions/:id`, with the token in the path, still work for pipelines set up before the header, and answer with a `Deprecation: true` header.
Move the token into the header: a path is written down in access logs, a header is not.
The local run routes take the header only.

`target: "local"` on a trigger that has `allow_local` off answers `403 forbidden`, and the message says where to turn it on.
`base_url` follows the rules under Runs.

[Schedules and CI](/docs/flowqa-ci/) has the pipeline recipe.

## Writing tests

### Saving in one call

`POST /tests/save` is how an agent or a script writes tests.

```json
{
  "idempotency_key": "add-checkout-tests-2026-10-21",
  "tests": [
    {
      "definition": {
        "ir": 1,
        "app": "shop",
        "flow": "checkout/guest",
        "name": "Guest checkout",
        "platform": "web",
        "steps": [{ "do": "navigate", "url": "/" }]
      }
    }
  ]
}
```

Leave out `test_id` to create a test, which starts at revision 1.
To update one, send its `test_id` and `base_revision`, the revision you read; the save makes the next revision.
`create_modules: true` adds any module a flow id names that the project does not have yet.
`check_only: true` answers with the same findings and writes nothing.

The answer lists, per test, `test_id`, `flow_id`, `revision`, `status` (`created`, `updated` or `unchanged`) and `findings`.
The call is all or nothing: when any test is invalid, the answer is `422` with `details.tests[]`, naming each test's `index`, `flow_id` and `errors`, and nothing is written.
When a `base_revision` is no longer the latest, the answer is `409` with each test's current `revision`, so you can read it again and retry.

Findings are advice, not errors.
Each has a `code`, a `step_index` and a `message`; the codes are `no_assertion`, `weak_locator`, `css_only_locator`, `generated_id`, `literal_credential_like`, `duplicate_name`, `long_test`, `duplicate_opening`, `unknown_variable` and `production_only`.

### Deleting

`POST /tests/delete` takes an `idempotency_key` and `tests`, 1 to 100 of `{ test_id, revision }`.
It answers per test with `deleted`, `conflict` (with the current `revision`), `not_found`, or `refused` with `used_by` when another test still starts with it.
It deletes what it can and answers `200` either way.

### Drafts, step by step

A draft suits a recorder or an editor that saves as the person works.
Start one with an `idempotency_key`, `base_revision: 0` and a complete `definition`, or with the `test_id` and current `base_revision` of the test being edited.
The answer has the `draft_id`, `sequence: 0` and `status: "open"`.
Each checkpoint (`PUT`) sends the next `sequence` and the complete definition; a skipped or repeated sequence with a different body is a `409`.
Publish with `{ "expected_sequence": 3 }` once the person has reviewed checkpoint 3.
When the test has moved on since the draft began, publishing is a `409` and the draft stays open: read the latest revision, resolve the differences, and start a new draft from it.

### Telling us who wrote it

Every revision and every run records its `origin`, and the app shows it beside what was written and run.
A coding agent connected through the TestFinch connector is recorded as `mcp`, with the agent's name and version.
A script that brings tests in from elsewhere may send `X-TestFinch-Agent: import`, and its revisions read as imported.
Any other value is ignored, never refused.

## Retries and idempotency

Saving, deleting and organizing tests, starting a draft and starting a run each require an `idempotency_key` that you choose.
Sending the same key with the same body again returns the first result and does nothing twice, so a request that timed out is safe to retry.
The same key with a different body is a `409`.

## Errors

An error answers with an HTTP status and one envelope:

```json
{
  "error": {
    "code": "conflict",
    "message": "This repair is accepted; only a proposed one can be approved.",
    "details": {}
  }
}
```

`field_errors` names the fields that failed validation, and `details` carries anything else the error needs, such as the tests in a failed save.

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthorized` | No token, or a revoked one. |
| 402 | `plan_limit` | The workspace's plan does not cover it and no credits do; `details` names the limit. |
| 403 | `forbidden` | Your role, a `read` token, or something only a person can do. |
| 404 | `not_found` | It does not exist, or this token cannot see it. |
| 409 | `conflict` | A revision or sequence moved on, or an idempotency key was reused with a different body. |
| 410 | `gone` | The screenshot was removed after your plan's retention, or the project was removed. |
| 422 | `validation` | The body or the definition is invalid. |
| 426 | `client_outdated` | The TestFinch CLI making the request is older than the version the API supports. `details` has `min` and `latest`. |
| 429 | `rate_limited` | Too many requests; wait and retry. `details.reset_at` says when, where it applies. For local runs, `details.retry_after_seconds`. |
| 503 | `unavailable` | Busy for a moment, such as another change to the workspace's projects; retry after `Retry-After` seconds. |

A project in another workspace, or one the token is not limited to, is a `404`, never a `403`, so a token learns nothing about projects it cannot see.

## CLI versions

`GET /v1/meta/clients` needs no token and answers `{ "cli": { "min": "1.0.0", "latest": "1.2.0" } }`, where `latest` can be `null`.
The CLI reads it at most once a day.
The TestFinch CLI sends its version in its `User-Agent` (`testfinch-cli/<version> ...`), and a version below `min` gets `426 client_outdated` on every route except this one.

## Limits

- A definition is at most 1 MB of JSON and 2,000 steps.
- A project holds at most 5,000 tests.
- A save writes 1 to 50 tests; a delete takes 1 to 100; a run takes 1 to 100.
- One person saves at most 500 tests an hour in a project.
- One person starts at most 600 local runs an hour.
- Flow ids are segments separated by `/`, such as `checkout/guest`, of letters, digits, `_`, `-` and `.` (a segment does not start with `.`), up to 240 characters.
- Cloud runs, explorations and accepted generated tests count against the plan's allowances, and draw on credits beyond them; [Billing questions](/docs/billing/) has the details.
