Skip to main content

Assurance API Quickstart

Two paths into the same canonical pipeline. Option B — Connected GitHub is the recommended path for full remote static-analysis coverage: a GitHub-App-verified repository scanned by HAIEC's remote infrastructure. Option A runs bounded local analysis (preview) when you want source to stay on your machine.

What you need

Connected GitHub RECOMMENDED

HAIEC_BASE_URL=https://www.haiec.com
HAIEC_API_KEY=haiec_live_xxx
HAIEC_AI_SYSTEM_ID=SYSTEM_ID
HAIEC_SOURCE_ASSET_ID=VERIFIED_SOURCE_ID

A repository connected to the AI System through the HAIEC GitHub App — verified under AI System → Connected Assets. The server resolves the GitHub App installation; no GitHub token is ever sent.

Local project PREVIEW

HAIEC_BASE_URL=https://www.haiec.com
HAIEC_API_KEY=haiec_live_xxx
HAIEC_AI_SYSTEM_ID=SYSTEM_ID
# plus the local workspace

Run the local scanner → submit qualified evidence → start the same Assurance Run. Bounded analyzer coverage; no GitHub connection or sourceAssetId.

The flow

# Connected GitHub — verified Source Asset (recommended)
curl -X POST "$HAIEC_BASE_URL/api/v1/assurance/runs" \
  -H "Authorization: Bearer $HAIEC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-run-001" \
  -d "{
    \"aiSystemId\": \"$HAIEC_AI_SYSTEM_ID\",
    \"engines\": { \"static\": { \"enabled\": true,
        \"executionMode\": \"api\",
        \"sourceAssetId\": \"$HAIEC_SOURCE_ASSET_ID\",
        \"branch\": \"main\" } }
  }"

# Local workspace alternative (preview — bounded coverage)
npx tsx scripts/haiec-scan.ts --repo . --submit \
  --system "$HAIEC_AI_SYSTEM_ID" --json
# → POST /api/v1/scans → POST /api/v1/assurance/runs

# Poll either run until evaluation.evaluationId appears
curl -H "Authorization: Bearer $HAIEC_API_KEY" \
  "$HAIEC_BASE_URL/api/v1/assurance/runs/RUN_ID"

# Retrieve the same artifacts for either path
curl -H "Authorization: Bearer $HAIEC_API_KEY" \
  "$HAIEC_BASE_URL/api/v1/assurance/evaluations/EVAL_ID/summary"
curl -H "Authorization: Bearer $HAIEC_API_KEY" \
  "$HAIEC_BASE_URL/api/v1/assurance/evaluations/EVAL_ID/report"
curl -H "Authorization: Bearer $HAIEC_API_KEY" \
  "$HAIEC_BASE_URL/api/v1/assurance/evaluations/EVAL_ID/passport"

What to expect

  • run.status is the orchestrator run status; stage names the current engine.
  • evaluation.disposition is ALLOW / REVIEW / BLOCK — bounded to evaluated scope and available evidence, not a certification.
  • Errors arrive as {"error":{"code","message","retryable"}} — e.g. SOURCE_NOT_VERIFIED, CONSENT_REQUIRED, INSUFFICIENT_SCOPE.
  • Retrying the same Idempotency-Key with the same payload returns the original run — it never starts a second scan.
  • Private connected repositories are authorized by the verified Source Asset's active organization-linked GitHub App installation — the server mints short-lived installation credentials. No caller GitHub token and no browser-user consent step is required for this path.
  • The completed evaluation also opens in the dashboard at links.dashboard on the run envelope — same persisted Evaluation as a dashboard-initiated run.
  • Environment values are server-side only: keep them in .env.local (gitignored) or a secret manager — never NEXT_PUBLIC_*.
Full API guide API Platform