Runs

Start a durable QA run, inspect its evidence and reports, or consume its Workflow event stream.

Create a run

POST /api/runs

bash

curl "$PROOF_URL/api/runs" \
  --request POST \
  --header "Authorization: Bearer $PROOF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "repositoryId": "repo_storefront",
  "naturalLanguageTask": "Complete checkout with a declined card and confirm no order is created",
  "baseUrl": "https://storefront.example.com",
  "networkAllowlist": ["api.stripe.com"],
  "trigger": "cli",
  "channelContext": {}
}'

A request returns 202 Accepted and a durable run identifier. Executable intent also returns identifiers for the Vercel Workflow run and resolved scenario.

json

{
  "runId": "run_abc123",
  "workflowRunId": "wrun_xyz789",
  "scenarioId": "scenario_declined_card"
}

Ambiguous intent stops before browser execution

When missing scope, credentials, permissions, or side-effect authority changes the meaning or safety of a task, Proof returns a terminal review_required run with explicit questions. No Workflow or browser sandbox is started.

json

{
  "runId": "run_needs_context",
  "status": "review_required",
  "resolution": {
    "kind": "needs_clarification",
    "assumptions": [],
    "questions": ["May Proof place a test order, and what spending limit applies?"],
    "ambiguities": ["Completing checkout might place a real order."]
  }
}

Request body

The API key determines the organization. Provide exactly one of scenarioId or naturalLanguageTask.

Field	Type	Presence	Description
`repositoryId`	string	Required	Connected repository to inspect or replay.
`scenarioId`	string	Conditional	Existing scenario to replay.
`naturalLanguageTask`	string	Conditional	Customer task for semantic interpretation.
`commitSha`	string	Optional	Repository revision, at least seven characters.
`baseUrl`	URL	Required	Browser target for the product.
`networkAllowlist`	string[]	Optional	Additional hosts the browser and deterministic test may contact.
`trigger`	enum	Required	web, github, slack, cli, schedule, or system.
`channelContext`	object	Optional	Opaque delivery context returned to the originating channel.

Answer clarification

POST /api/runs/:runId/clarifications

Send one answer for every question on a review_required run. Proof preserves the original run and creates a correlated child run whose task contains the explicit answers.

bash

curl "$PROOF_URL/api/runs/run_needs_context/clarifications" \
  --request POST \
  --header "Authorization: Bearer $PROOF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"answers":["Use test mode only; do not place a real order."]}'

The CLI equivalent is proof answer run_needs_context --answer "Use test mode only; do not place a real order.". Repeat --answer in question order when the run asks more than one question.

Get a run

GET /api/runs/:runId

Returns the durable run record, ordered event history, safe artifact metadata, and reports. Private Blob URLs are not included.

bash

curl "$PROOF_URL/api/runs/run_abc123" --header "Authorization: Bearer $PROOF_API_KEY"

Stream progress

GET /api/runs/:runId/events

Returns newline-delimited JSON from the durable Workflow stream with content type application/x-ndjson. Pass ?after=12 to resume at a known event index.

bash

curl --no-buffer "$PROOF_URL/api/runs/run_abc123/events?after=0" --header "Authorization: Bearer $PROOF_API_KEY"

Do not poll when you can stream

The CLI uses this endpoint so one long-lived response replaces repeated status invocations. Always set a finite client timeout.

Errors

Status	When returned
400	Request validation fails.
401	Machine authentication fails.
404	Run or Workflow stream is unavailable.
503	Live execution or required AI execution is paused.