DocsAgents and API
The FlowQA API
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 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:
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 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 |
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 |
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 |
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 |
The configuration and its revision; 404 when the project has no tests yet. |
PUT |
Replace the configuration: expected_revision and configuration. Admins only. |
Tests#
| Route | What it does |
|---|---|
GET |
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 |
One test: its summary, its complete definition, findings and its five most recent results. |
GET |
One published revision, with content_hash, created_by, origin, agent and created_at. |
POST |
Create or update 1 to 50 tests in one call (below). |
POST |
Delete tests at the revisions you read (below). |
POST |
Add, rename or remove modules, set suites, move tests and set their order, in one call. |
Drafts#
| Route | What it does |
|---|---|
GET |
Your open drafts, paged like the tests. |
POST |
Start a draft, or recover one, by idempotency_key. |
GET |
The draft and its last accepted sequence. |
PUT |
Save a checkpoint: the next sequence and the complete definition. |
POST |
Publish the reviewed checkpoint, expected_sequence, as the test's next revision. |
POST |
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 |
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 |
Recent runs. |
GET |
One run: status and, per test, its result, the failing step, artifacts, console_errors and network_failures. |
GET |
One screenshot from the run, as base64. |
POST |
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 |
What an exploration of journeys journeys would use, before you start it. |
POST |
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 |
Recent explorations. |
GET |
One exploration: its progress, the map and the proposed journeys. |
POST |
Generate tests for the chosen journeys (mode: "generate" with journeys), or keep only the map (mode: "hand_me_the_map"). |
POST |
Stop an exploration. |
GET |
Questions across the project's explorations, newest first; status is open (the default), answered, expired or all. |
GET |
One exploration's questions. |
GET |
The page the agent was looking at, as { data, content_type }. |
POST |
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 explains each kind of question and how the answer travels.
Repairs#
| Route | What it does |
|---|---|
POST |
Propose a repair for a failed run of the test: execution_id. Not with a personal access token. |
GET |
The latest 50 repairs, newest first; status and test_id filter. |
GET |
One repair, with its proposed change. |
POST |
Apply a proposed repair as the test's next revision; optional note. |
POST |
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 explains how a repair is found and proven.
Site notes#
| Route | What it does |
|---|---|
GET |
The index of the project's notes, without their bodies. |
GET |
Read one note. |
PUT |
Write one note: { body, title?, summary? }. |
DELETE |
Remove one note. |
Site notes explains what they hold and who writes them.
Schedules and CI triggers#
| Route | What it does |
|---|---|
GET |
The project's schedules. |
PATCH |
Change a schedule's name, cron, timezone, environment, test_ids, enabled or alerts. |
DELETE |
Remove a schedule. |
POST |
Run a schedule's tests now. |
GET |
The project's CI triggers, never their tokens. Each has allow_local. |
PATCH |
Turn allow_local on or off. Signed in as yourself. |
DELETE |
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 |
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 |
That run's status, done, ok, summary and results. |
POST |
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 has the pipeline recipe.
Writing tests#
Saving in one call#
POST /tests/save is how an agent or a script writes tests.
{
"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:
{
"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 ascheckout/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 has the details.