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 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.