API and personal access tokens

The HTTP flow/run API is hosted at https://app.reflow.io. Sign-in is open; app access and test execution require an approved team during closed beta. Use that team’s connection and permissions. For device execution, knowledge and review tools, use the local CLI and MCP workflow.

Personal access tokens authenticate CI and scripts. The sidecar can retain a private profile after same-device browser sign-in; the remote HTTP MCP server uses its own OAuth connection.

Create a token

Open Settings → API tokens in the dashboard. Give the token only the scopes it needs: admin, run, or read. Tokens begin with rfl_pat_ and the full value is shown only once when it is created.

Send it as a bearer token:

export REFLOW_API=https://YOUR_API_ORIGIN/v1
export REFLOW_TOKEN=rfl_pat_...

Every authenticated request uses:

Authorization: Bearer <token>

Start and follow a run

Create a run from a registered flow and keep the returned run id:

curl --fail-with-body -X POST "$REFLOW_API/runs" \
  -H "Authorization: Bearer $REFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "target_url": "https://preview.example.com",
    "idempotency_key": "docs-homepage-1",
    "flows": [{"slug": "homepage-smoke", "tag": "main"}]
  }'

Poll the complete run record, long-poll new events, or request a step screenshot URL:

curl --fail-with-body \
  -H "Authorization: Bearer $REFLOW_TOKEN" \
  "$REFLOW_API/runs/$RUN_ID"

curl --fail-with-body \
  -H "Authorization: Bearer $REFLOW_TOKEN" \
  "$REFLOW_API/runs/$RUN_ID/events?wait=20"

curl --fail-with-body \
  -H "Authorization: Bearer $REFLOW_TOKEN" \
  "$REFLOW_API/runs/$RUN_ID/screenshot?step_idx=0"

GET /v1/runs/{run_id} is safe while a run is executing. The events route blocks for at most 20 seconds and returns the current status with new step events.

Endpoint tour

Method	Path	Purpose
POST	/v1/runs	Create one or more runs from exact saved application flow versions.
GET	/v1/runs/{run_id}	Read status and step evidence.
GET	/v1/runs/{run_id}/events	Long-poll the run timeline.
GET	/v1/runs/{run_id}/screenshot	Get a short-lived step screenshot URL.
GET	/v1/flows	List flows and active tags.
POST	/v1/flows	Create a knowledge-base test using current team-policy and selected-collection storage context.
PUT	/v1/flows/{slug}/content	Save full knowledge-base source; collection-scoped saves require source_revision and exact base_version_id.
POST	/v1/pr-runs	Create the idempotent PR rollup used by the GitHub Action.
GET	/v1/pr-runs/{pr_run_id}	Long-poll a PR rollup.
POST	/v1/tokens	Create a PAT with name and scopes; requires admin access.

Before authoring, refresh get_reflow_context, resolve the intended collection, and use manage_flows, reflow flows create or reflow flows save. Raw creation for storage-enabled teams requires current storage.collectionId, storage.policyRevision and storage.sourceKind: "knowledge_base"; do not guess them. Collection-scoped knowledge-base saves require the flow’s freshly read source_revision and exact base_version_id; on 409, read again and rebase. Legacy unscoped saves retain optional concurrency guards, and context-free legacy creation remains supported for storage-disabled teams. Repository-owned tests must be created and saved through the connected author device.

For example, an existing admin token can create a run-only token:

curl --fail-with-body -X POST "$REFLOW_API/tokens" \
  -H "Authorization: Bearer $REFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"CI","scopes":["run"]}'

The response contains the new plaintext token once. Store it immediately. For pull-request reporting and DAG selection, see the deployment and distribution limits in the GitHub Action over calling POST /v1/pr-runs directly.