From a project to a governed review
Your coding agent does the reasoning. i2x defines bounded work, records its results, and keeps agent reports separate from independent verification.
Use the origin supplied by your i2x installation. Sign in to i2x and select a configured project and its current inspection run. The application handles browser authentication; integrations use an i2x session token. Never put a provider login, subscription token or model API key in these requests.
Using your subscription: Codex or Claude runs through the configured customer-local client. HTTP calls to i2x do not turn your subscription into a remotely shared model credential. Local execution endpoints require a configured local i2x instance; hosted verification requires its own available capacity.
Start with the next project action
Read GET /api/projects/{projectId}/onboarding to see the current project stage, selected connection and existing work order. The response distinguishes an agent report from independent verification. If a specialist is needed, an owner or maintainer sends its exact onboardingDigest and a stable idempotencyKey to POST /api/projects/{projectId}/onboarding-commission.
When you change the coding-agent connection
An existing assignment remains pinned to its original connection. If the next action is REPLACE_CONNECTOR_WORK_ORDER, review the old assignment and explicitly confirm replacement. Send the current onboardingDigest, commission.receiptId as commissionId, commission.taskId as expectedTaskId, and commission.taskInputDigest as expectedTaskInputDigest to POST /api/projects/{projectId}/onboarding-connector-replacement. Include a 20–500 character diagnosis, a stable idempotencyKey, and acknowledgement: "REVOKE_OLD_ASSIGNMENT_AND_CREATE_NEW_WORK_ORDER".
This requires an owner or maintainer with fresh identity verification. i2x selects the current connector itself, preserves the source and protection scope, revokes the old queued or active assignment and creates a separate work-order generation in one transaction. Read onboarding again to see the new task. Retry a lost response with the identical request and idempotency key; refresh a stale confirmation instead of overwriting it.
Revoking an i2x assignment does not prove that an external CLI process stopped. Replacement does not run the agent, validate its output, or authorize a release. Stop or review the old external process separately before allowing conflicting work.
Review CI results
Open your project and choose CI results. Expand a receipt to see the reported check outcomes, source and plan digests, and full receipt digest. Results from earlier plans remain visible with their original bindings. A receipt that matches the accepted plan may still refer to older source. The receipt details compare its source digest with the latest observed source when available.
Sign in as a project member to retrieve the same receipts through these project configuration endpoints. Each response includes configurations and evidenceReceipts. The latter contains up to 50 recent receipts for that provider, newest first, and can be empty.
GET /api/projects/{projectId}/ci-github-configurationsGET /api/projects/{projectId}/ci-gitlab-configurationsGET /api/projects/{projectId}/ci-generic-configurations
The short-lived CI token submits evidence. Your i2x project access lets you read the retained receipt after that token expires. Receipts identify the bound source and accepted plan and show outcomes reported by the CI runner. Independent verification and release or recovery approval require separate evidence and decisions.
1. Queue the Project Lead
A project-understanding run starts from a completed project inspection. An owner or maintainer queues its Lead with POST /api/runs/{runId}/project-lead-task and an empty JSON object. Keep the returned taskId. Repeating this request returns the latest Lead task; it does not silently retry failed work.
The connected agent can discover work using task.list and claim it using task.claim. The claim supplies the required output contract and allowed operations. The customer-local execution controls can run that work through the selected official coding client.
If the latest Lead task failed or was cancelled, send its ID as previousTaskId to POST /api/runs/{runId}/project-lead-task/retry. This preserves the original source-bound input and obeys the approved attempt limit. It cannot replace active or successfully completed work. Repeating the same retry request returns the same retry task.
GET /api/runs/{runId}/specialist-tasks exposes requiresProjectLead and projectLeadTask, so your interface does not have to infer which Lead task is current.
Start repair analysis from a finding
A human owner or maintainer can send sourceDigest and a 16?128 character idempotencyKey to POST /api/projects/{projectId}/findings/{findingId}/repair-run. Use the latest observed project digest. An accepted open finding is required.
The response contains the new runId and coverageReviewRequired: true. This prepares analysis only: no specialist task, source edit, verification, hold clearance or release is authorized. Reuse the same request key after an uncertain response; changed input under that key is rejected.
For the returned run, preview coverage with changeAreas: ["failure_repair"]. Show the returned repair context, including original failed-run references, findings, protected behaviors and accepted checks. Its digest is bound to the preview; changed requirements require a fresh review. Accept the preview separately to queue repair and Chief QA. Retries preserve the reviewed context and refuse changed requirements. Source reading and agent reports alone do not prove a repair succeeded.
2. Preview and accept the team
Send changeAreas and, when applicable, protectedBehaviorKinds to POST /api/runs/{runId}/coverage-preview. For a project-understanding run, finish the Lead first. Omit additionalRoles to discover its recommendations. An explicit list must match the recommendation.
{
"changeAreas": ["project_structure"],
"protectedBehaviorKinds": []
}
Show the returned minimumRoles, additionalRoles and effectiveRoles to the customer. Previewing creates no specialist tasks. Keep the exact previewDigest.
Only after the customer reviews the team, send the same inputs, the returned additionalRoles and previewDigest to POST /api/runs/{runId}/coverage-plan. The accepted plan and all its tasks are committed together. A changed preview is refused; fetch a new preview instead of weakening the plan.
// Call this from the customer's acceptance action, not on preview load.
async function acceptReviewedCoverage(api, runId, input, preview) {
return api(`/api/runs/${runId}/coverage-plan`, {
method: "POST",
body: JSON.stringify({
...input,
additionalRoles: preview.additionalRoles,
previewDigest: preview.previewDigest
})
});
}
Accepted coverage cannot be reduced by a later retry. POST /api/runs/{runId}/specialist-tasks accepts a role for a bounded retry already covered by the plan. Availability depends on active tasks, reconciliation state and remaining attempts.
3. Execute one bounded task at a time
The operation list returns verificationBindings, each containing an operationId and its verification. Match that ID to the displayed operation. The separate verifications list is retained for compatibility; its position does not identify an operation. A result from earlier work must never upgrade the displayed result of newer work.
On a configured customer-local installation, a freshly verified owner or maintainer sends projectId to POST /api/local/customer-task-operations. It starts one eligible task, not the whole queue. The server chooses the eligible assignment and configured account; the request cannot supply a model, prompt or task ID.
Keep operation.operationId and poll GET /api/local/customer-task-operations/{operationId}. List retained operations with GET /api/local/customer-task-operations with its required projectId query parameter. If the response to a start request is lost, inspect that list before sending another start request.
A baseline is optional. When needed, it is a separate absolute folder on the customer machine, its exact sourceDigest, and confirmation: "APPROVE_BASELINE_FOR_TASK". Send it only to your local instance. Do not send server-owned approval fields or a provider credential.
An operation's completed state means its bounded execution and report submission completed. Inspect the task outcome and assurance separately: an accepted report can describe a failed check.
4. Read the review honestly
Read GET /api/runs/{runId}/specialist-tasks for task progress and the review projection. Chief QA waits for its topic tasks, then reconciles failed, cancelled and completed-but-unverified work.
| Review status | What the interface should show |
|---|---|
pending | No summary yet. Topic work or reconciliation is still needed. |
available | The retained summary and explicit gaps for the currently observed source. |
historical | The summary with a clear warning that the source changed or is not currently observed. |
unavailable | No summary text. The stored record could not be safely linked and checked. |
Render summaries as plain text. Preserve assurance, independentVerification, reasonCodes and the report/source digests. A reviewed agent report does not establish independent verification and never authorizes release or recovery effects.
5. Recover or close incomplete work
Use POST /api/local/customer-task-operations/{operationId}/cancel with projectId and confirmation: "CANCEL_CUSTOMER_FUNDED_TASK" when cancellation is available. Wait for host restoration; a cancellation request alone is not a completed recovery.
If the operation reports recovery_required, use POST /api/local/customer-task-operations/{operationId}/recover with projectId. Recovery uses the existing operation ID. It does not replay ambiguous model work.
After a confirmed pre-handoff interruption, a new explicit start can resume the same task only when its full retained history, ownership and scope allow that retry. Other incomplete work must be reviewed rather than blindly repeated.
If you choose to stop the incomplete task, first read GET /api/local/customer-task-operations/{operationId}/close-task. When its preview permits closure, send projectId, the returned runtimeRecordDigest, and confirmation: "CLOSE_INCOMPLETE_TASK_WITHOUT_SUCCESS" to the same path with POST.
This requires fresh verification by the original requesting customer, current ownership permission, terminal recovery and the restored local host. It records the task as cancelled, not successful. Chief QA can then report the cancellation as an evidence gap. Retrying a lost closure response returns the original receipt.
Review the next specialist before starting
In the local app, choose Review next specialist task. i2x shows the specialist, task and pinned skill/input identities. Previewing does not claim the task, read source content or invoke your coding account. Choose Run this specialist task to confirm subscription use.
API clients can call POST /api/local/customer-task-preview with projectId, then pass the returned taskPreview unchanged to the local task-start endpoint. If the selected task, inputs, skill or connection changes before claiming, the operation fails with CUSTOMER_TASK_PREVIEW_CHANGED. Refresh and review again. Existing clients may omit this optional selection binding. A preview is not verification that the project works.
Read each specialist's findings
Open Specialists for the run, then expand Read [specialist] report. You can read structured findings, inspect the complete retained JSON and choose Download this report. The readable view may shorten large reports; the full report remains in the JSON view and download.
The report identifies completed or failed outcomes and checks its retained input,skill,output and policy-completion bindings. A historical label means its source does not match the latest recorded inventory,or no matching inventory is available. A matching inventory is not a new filesystem observation. Pending work has no terminal report;invalid bindings produce an unavailable state.
API clients use GET /api/runs/{runId}/task-reports/{taskId} with project-view permission. The response excludes task inputs and credential configuration. The report body is the specialist's own submitted output. Viewing or downloading it invokes no model,performs no independent checks and grants no release,recovery or repository-write authority.
Run an accepted specialist team
After accepting project-understanding coverage on a customer-local instance, use Start reviewed team. Review the displayed roles and confirm use of your selected subscription. The control schedules at most 20 existing queued tasks from that reviewed list;it does not commission extra roles or retry failed tasks.
Every task still uses the existing fresh-identity,scope,preview and claim checks. The coordinator stops on a new failed or inconclusive outcome,unexpected task,input/skill change,provider/connector/access change or required identity verification. Between tasks,the next host identity must match restoration recorded in the completed operation's checked journal. Request includeHostRestoration=true on the operation status GET to expose hostRestoration for this handoff;it describes a past restoration,not present OS process liveness or independent verification.
Stop after current task prevents later starts while allowing current work to finish. Leaving this view or closing the page prevents later starts but does not cancel a task already requested. Inspect local task controls to cancel that task. This browser coordination is not a durable background team job;after interruption,refresh and review the remaining work again. A timeout or uncertain response never triggers automatic start retries.
Scheduling has a 30-minute client limit and bounded requests. Reaching the limit does not cancel active work or establish its outcome. Earlier failed reports remain visible. Recorded reports,including a complete Chief QA report,do not themselves prove the software works;choose independent checks separately.
Run a source-reading specialist with your API account
On a customer-controlled i2x instance with a configured provider and a run bound to that choice, open Specialists. Select a queued or active task, enter a repository-relative file path and line range, and preview the excerpt. The preview reads the exact run source and records a source observation. It makes no provider request.
Review the excerpt and select Approve excerpt and run to send it to the named provider. A fresh owner or maintainer session is required. The provider bills your API account. Open the resulting specialist report to read its findings. Independent verification is separate.
- Send
projectId,sourceDigest,action: "read",path,startLine, andlineCounttoPOST /api/tasks/{taskId}/{provider}-api-execution/source-preview. Useopenai,anthropic, orxaifor the configured provider. - Send the same request object as
requesttoPOST /api/tasks/{taskId}/provider-source-approval. IncludesourceReceiptIdfromevidence.receiptId,expectedResultDigestfromevidence.resultDigest,provider,idempotencyKey, andacknowledgement: "SEND_THIS_EXCERPT_TO_SELECTED_PROVIDER". - Send
sourceDisclosurewith the returneddisclosureDigest, the samerequest, and the preview response asexcerptwith itsevidencefield removed. Post it to/api/tasks/{taskId}/{provider}-api-executionfrom the same session. i2x records use of the approval before transport. If execution status is uncertain, use GET on that endpoint to inspect the retained result.
Draft verification checks with your API account
On a configured customer-controlled instance, inspect the project, confirm its scope, and define the protected behaviors. In onboarding, choose Queue verification draft. The task uses the inspected source and the accepted behaviors. Queueing makes no provider request.
- Read
GET /api/projects/{projectId}/onboarding. WhennextAction.codeisQUEUE_API_VERIFICATION_DRAFT, send the exactonboardingDigesttoPOST /api/projects/{projectId}/onboarding-api-verification-draft. Store the returnedtaskIdandrunId. Repeating the same request reuses the existing draft. - Preview an excerpt and approve sending it to the selected provider using the source-reading workflow. The draft must cover every required behavior case and include a negative case that tests invalid input or denied access.
- When the draft task completes, send an empty JSON object to
POST /api/tasks/{taskId}/submit-verification-draft. Open the pending proposal identified byproposalIdunder Agent proposals and review the exact commands and assertions before accepting. - Choose Run locally or call
POST /api/projects/{projectId}/verifywith an empty JSON object after accepting. Local results are labeled locally reported. Independent verification requires a separately configured verification path. - For hosted D3 verification, review the source snapshot and approved plan before allowing i2x to store a source package. Send the exact approved
expectedPlanDigestand optionallymaxSeconds(1 to 900) toPOST /api/projects/{projectId}/verify-hosted. If the API returnsHOSTED_PLAN_CHANGED, reopen the current plan for review. A202response is a queued run with verification pending. The response reports the storage mode insourceCustody. Projects with an access selection require encrypted storage and return the source expiry insourceExpiresAtEpochSeconds. Use the run ID to follow its evidence in the project.
If a terminal draft failed or produced unusable checks, request one retry with the current onboardingDigest and the original retryTaskId on the queue endpoint. The replacement requires its own excerpt review and explicit approval. If the source, protected behaviors, or project access changes after drafting, refresh the workflow and review a draft for the current scope.
6. Ask for independent checks separately
Starting without a test suite? Choose one behavior you want to protect and write down the expected result. For a booking app, you might expect it to refuse a reservation when all seats are taken. Ask your connected Codex or Claude agent to draft a runnable check for that behavior, then review its command, inputs and expected result before accepting the plan. Run the accepted check separately.
Until the check runs, the draft is a proposal. A passing run supports the behavior over the inputs it actually checked. Keep other behaviors open until their own checks run.
Where the installation has accepted checks and configured verification capacity, use POST /api/local/customer-task-operations/{operationId}/verify. The operation itself must have completed; an earlier interrupted operation cannot borrow a later retry's result.
Provide projectId, coverage (contextual or complete), a 20–500 character coverageReason, maxSeconds from 1 to 900, an idempotencyKey, and confirmation: "I_ACKNOWLEDGE_VERIFICATION_COVERAGE". Complete coverage is appropriate only when every material claim maps to the accepted checks.
Poll the operation's verification status. When evidence is available, GET /api/local/customer-task-operations/{operationId}/verification-evidence returns the authenticated bundle. Use the independently pinned verification material and current trust checks; the presence of a digest or a green task label alone is not proof.
Handle refusals without bypassing them
| HTTP status | Next action |
|---|---|
| 400 | Correct the request shape or confirmation value. |
| 401 / 403 | Sign in, verify identity again where required, or use a session with the correct project role. |
| 404 | Check that the run or operation belongs to the signed-in customer and project. |
| 409 | Read the error code and refresh current state. Do not override stale coverage, active work, attempt limits or unsafe recovery. |
| 503 | A required runtime or evidence service is unavailable. Keep the incomplete state visible. |
Download the full OpenAPI contract · Source-read permission · Separate storage permission