Conformance API

List this application's conformance runs

GET /conformance/runs

Newest first. Page with nextCursor. Requires a sandbox key.

• limit integer
• cursor string: Opaque cursor. Pass nextCursor back to the endpoint that returned it, for the same subject and category; meta.changeCursor starts the change feed. Don't construct or edit it.

Start a conformance run

POST /conformance/runs

Requires a sandbox key (ck_test_...); a live key (ck_live_...) receives 403 sandbox_only, and a suspended application 403 app_suspended. An application whose status is not sandbox receives 409 app_not_sandbox: an application has one webhook URL and signing secret across environments, and a run sends deliberately corrupted webhook probes, so run conformance on a separate sandbox application. One run can be open per application (409 run_in_progress). A run cancelled or expired before its creation finished answers 409 run_not_open, and its key is revoked without being shown. The response carries run_key, a sandbox key whose requests are attributed to the run, shown only in this response and revoked when the run ends. Configure the application with it and create a Connect session; FinchNode completes the session as the patient with the run's scenario, then forces up to two rate limits (retry each forced 429 no sooner than Retry-After), revokes consent, and sends webhook probes. A run that never gets a session expires 60 minutes after creation. A body field other than scenario and sync_mode, an unknown sync_mode, or a continuous run on an application whose sync mode is one-time returns 400 invalid_request; a scenario that is not a record scenario returns 400 invalid_scenario.

Retrieve a conformance run

GET /conformance/runs/{runId}

The live phase, each check with its evidence (counts, timings, and status codes), and, once the run ends, its verdict. Run and session polls are never forced and never graded. Requires a sandbox key.

• runId string (required)

Stop waiting in the current phase

POST /conformance/runs/{runId}/advance

Takes no body. The current phase is graded now with what was observed and the run moves to the next phase, so advancing early can leave its checks inconclusive. The session phase ends only when the run's Connect session completes, and a probes phase cannot be advanced while its probes are being sent (409 phase_not_advanceable); a run that has ended returns 409 run_not_open. Requires a sandbox key.

• runId string (required)

Cancel a conformance run

POST /conformance/runs/{runId}/cancel

Takes no body. Ends an open run as cancelled and revokes its run key; a run that has ended returns 409 run_not_open. Requires a sandbox key.

• runId string (required)

Read a conformance report

GET /conformance/reports/{token}

Public JSON behind the report's token (links.report on the run): no key, Cache-Control no-store, readable from any origin without credentials, and limited per network address. The report names the application only by its name and carries no subject, session, key, or record. Reports are kept for 90 days.

• token string (required)