Skip to main content

Assurance Runs API

One API for the full pipeline: submit an AI system for source scanning and evidence collection, let the orchestrator run the qualified engines, and receive a persisted assurance evaluation with links to its summary, report, and passport.

Authentication

All endpoints accept an organization API key. The organization is derived from the key itself — a caller-supplied organizationId is ignored. Authorization is scope-based: scan:createtriggers runs, scan:read polls status,report:read retrieves artifacts, andsystem:read/source:readcover discovery. The Assurance API / IDE key purpose carries the full set.

Authorization: Bearer haiec_live_your_key

Create keys at Dashboard → API Keys — choose the Assurance purpose for the full flow. Authorization is scope-based: run creation needs scan:create, run polling scan:read, evaluation artifacts report:read, discovery system:read/source:read. Missing/invalid keys return 401; missing scopes return 403.

Canonical production routes are under /api/v1. The unversioned/api/assurance/runs routes remain as compatibility aliases calling the same implementation. All responses use a machine-readable error envelope:{ "error": { "code", "message", "retryable" } }.

Start a run — POST /api/v1/assurance/runs

Creates and starts an audit-orchestrator run through the same services and gates as the dashboard evaluation flow. The run executes asynchronously; poll the returned URL.

curl -X POST https://www.haiec.com/api/v1/assurance/runs \
  -H "Authorization: Bearer haiec_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-123" \
  -d '{
    "aiSystemId": "sys_abc123",
    "engines": {
      "static": {
        "enabled": true,
        "executionMode": "api",
        "sourceAssetId": "asset_repo_456",
        "branch": "main"
      }
    }
  }'

// 202 Accepted
// {
//   "runId": "run_789",
//   "status": "CREATED",
//   "stage": null,
//   "evaluation": null,
//   "links": { "self": "/api/v1/assurance/runs/run_789", ... }
// }

aiSystemId — required. Must belong to the key's organization.

engines.static.executionMode — api (fresh scan of a bound source), ci-attached / reused (attach an existing scan via attachedScanId).

engines.static.sourceAssetId — preferred for fresh scans: a verified SOURCE_REPOSITORY asset bound to the AI system. A raw repositoryUrl must resolve to a bound asset — arbitrary URLs are rejected.

engines.runtime / engines.wizard — optional, same shape as the dashboard evaluation request.

Repository authorization for remote scans comes from the GitHub App: a private repository is eligible when its Source Asset is CONNECTED + VERIFIED and covered by an active organization-linked installation. The server mints a short-lived installation credential — no GitHub token is sent by the caller and no browser-user consent step is needed for the App-authorized path. Interactive/manual consent records still apply to non-App interactive scans; alternatively attach a CI-produced scan with ci-attached mode.

Poll status — GET /api/v1/assurance/runs/[runId]

curl https://www.haiec.com/api/v1/assurance/runs/run_789 \
  -H "Authorization: Bearer haiec_live_your_key"

// 200 OK
// {
//   "runId": "run_789",
//   "status": "COMPLETED",
//   "stage": null,
//   "failure": null,
//   "evaluation": {
//     "evaluationId": "eval_321",
//     "status": "COMPLETED",
//     "disposition": "REVIEW",
//     "methodologyVersion": "1.1"
//   },
//   "links": {
//     "summary":   "/api/v1/assurance/evaluations/eval_321/summary",
//     "report":    "/api/v1/assurance/evaluations/eval_321/report",
//     "passport":  "/api/v1/assurance/evaluations/eval_321/passport",
//     "dashboard": "/dashboard/assurance/evaluations/eval_321"
//   }
// }

When the pipeline completes, evaluation carries the persisted evaluation identity and links points at the canonical read surfaces. Until then, evaluation is null — that is pipeline progress, not a failure. The status field mirrors the orchestrator run status;stage names the current engine; a structuredfailure object appears on engine failure.

The linked artifact routes accept the same Bearer key (scope report:read) — summary, report, and passport are served from the exact persisted evaluation, not recomputed. PDF is also available through GET /api/v1/assurance/evaluations/{evaluationId}/report/pdfwith report:read; it supports executive, technical, and auditor presentation profiles.

What the evaluation means

  • disposition is the canonical ALLOW / REVIEW / BLOCK from the Assurance Decision Engine — scoped to evaluated scope and available evidence.
  • UNKNOWN is never PASS; absent runtime evidence is never presented as non-occurrence.
  • The full report, receipt, and passport are rendered by the canonical report surfaces linked from the run status.
Back to API Platform AI Security scan API reference