Jobs

Start a QA Job, review its evidence and Findings, or follow its progress stream.

Create a Job

POST /api/jobs

bash

curl "$PROOF_URL/api/jobs" \
  --request POST \
  --header "Authorization: Bearer $PROOF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "projectId": "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 Job ID. A runnable request also returns the Workflow ID and the resolved Check ID.

json

{
  "jobId": "job_abc123",
  "workflowIdentity": "wrun_xyz789",
  "testId": "check_declined_card"
}

Unclear requests stop before browser work

When missing scope, access, permission, or side-effect approval could change a task, Proof returns a review_required Job with clear questions. It does not start the Workflow or browser session.

json

{
  "jobId": "job_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 testId or naturalLanguageTask.

Field	Type	Presence	Description
`projectId`	string	Required	Connected repository to inspect or replay.
`testId`	string	Conditional	Existing check 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/jobs/:jobId/clarifications

Send one answer for each question on a review_required Job. Proof keeps the original Job and creates a linked Job that includes your answers.

bash

curl "$PROOF_URL/api/jobs/job_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 command is proof answer job_needs_context --answer "Use test mode only; do not place a real order.". Repeat --answer in question order when the Job has more than one question.

Get a Job

GET /api/jobs/:jobId

Returns the Job record, event history, safe artifact details, and Findings. It does not include private storage URLs.

bash

curl "$PROOF_URL/api/jobs/job_abc123" --header "Authorization: Bearer $PROOF_API_KEY"

Follow progress

GET /api/jobs/:jobId/events

Returns newline-delimited JSON from the Workflow progress stream. Use content type application/x-ndjson. Pass ?after=12 to continue from a known event.

bash

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

Use the stream instead of polling

The CLI uses this endpoint so one response replaces repeated status requests. Always set a timeout.

Errors

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