Jobs

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

This reference describes the earlier Job workflow. It does not start website mapping or operate on mapping tests. Use the dashboard for that workflow.

Prepare the Project first

Use a Project with an active repository, current approved context, and saved target settings from the earlier workflow. Mapping does not create those context approvals. A saved test must belong to that Project and use the current approved context. Request fields cannot override the saved test URL or network allowlist.

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": "project_storefront",
  "naturalLanguageTask": "Complete checkout with a declined card and confirm no order is created",
  "baseUrl": "https://storefront.example.com",
  "trigger": "cli",
  "channelContext": {}
}'

A request returns 202 Accepted and a Job ID. A runnable request also returns the Workflow ID and the resolved test ID.

json

{
  "jobId": "job_abc123",
  "workflowIdentity": "wrun_xyz789",
  "testId": "test_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

Each API key has an organization. Set a testId or naturalLanguageTask. If both are present, Proof uses the saved test.

Field	Type	Presence	Description
`projectId`	string	Required	Project used by the earlier Job workflow.
`environmentId`	string	Optional	Website environment ID. If omitted, this endpoint uses the first environment created for the Project.
`testId`	string	Conditional	Existing context-workflow test to replay.
`naturalLanguageTask`	string	Conditional	Customer task for semantic interpretation.
`commitSha`	string	Optional	Repository revision, at least seven characters.
`baseUrl`	URL	Required	Required by request validation. Execution uses the Project’s saved test URL.
`networkAllowlist`	string[]	Optional	Accepted, but replaced by the Project’s saved network allowlist.
`trigger`	enum	Required	web, github, slack, cli, schedule, or system.
`executionMode`	enum	Optional	auto, replay, or recompute. The default is auto. The safety stop blocks Function replay. Website context replay uses the browser path.
`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 start at stream index 12. This is a stream index, not a Job history event ID.

bash

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

A Job that stops for clarification before a Workflow starts has no progress stream. Use GET /api/jobs/:jobId to inspect it.

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.
409	Project test settings are missing or conflict with the request. Read the response code and correct the Project settings.
503	Live execution or required AI execution is paused, or the spending limit blocks new work.