API and personal access tokens

Personal access tokens are for CI and scripts. For coding agents, use the OAuth-based MCP connection instead.

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://app.reflow.io/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, prefer the supported GitHub Action over calling POST /v1/pr-runs directly.