API and personal access tokens

The hosted API origin is https://app.reflow.io. Sign-in is open, but app access and test execution are limited to approved teams during the closed beta. Use the connection and permissions for your approved team. The local CLI and MCP workflow also provides device execution, knowledge and review tools; this page describes the separate HTTP flow/run contract.

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 inline or registered flows.
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 dashboard-owned flow from a name and full markdown content.
PUT	/v1/flows/{slug}/content	Save a content-addressed version, optionally with 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.

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.