REST API Reference

Welcome to the CertiQA REST API reference. All requests authenticate via API tokens passed in the Authorization: Bearer <token> header.

1. Authentication & Scoped API Tokens

Endpoints for creating and managing short-lived and CI/CD scoped API access tokens.

POST /api/v1/tokens

Summary: Create Scoped Personal or CI API Token

Generates a new secure API token prefixed with ea_. Supports scoping by role (CI_RUNNER, REPORT_READER, ADMIN) and project UUID.

• Authentication: Bearer JWT (Keycloak/User)
• Required Roles: PROJECT_ADMIN, ORG_ADMIN, AUTHOR

Request Body Example:

{
  "name": "github-actions-main-ci",
  "role": "CI_RUNNER",
  "projectId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "expiresInDays": 90
}

Response (201):

{
  "id": "t-9981-token-uuid",
  "name": "github-actions-main-ci",
  "role": "CI_RUNNER",
  "rawToken": "ea_live_9f83ac1278de45bc90fe81...",
  "createdAt": "2026-08-29T12:00:00Z",
  "expiresAt": "2026-11-27T12:00:00Z"
}

GET /api/v1/tokens

Summary: List Active API Tokens

Returns all active token metadata (excluding raw secrets) created by the authenticated user or tenant.

• Authentication: Bearer JWT
• Required Roles: ALL

Response (200):

[
  {
    "id": "t-9981-token-uuid",
    "name": "github-actions-main-ci",
    "role": "CI_RUNNER",
    "projectId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "expiresAt": "2026-11-27T12:00:00Z"
  }
]

2. Test Execution & CI Inbound Hooks

Endpoints to remotely trigger headless test execution from terminals, CI/CD pipelines, and webhooks.

POST /api/v1/projects/{projectId}/hooks/trigger

Summary: Inbound Scoped CI Trigger Webhook

Triggers execution of a specific suite or tag filter within a project. Returns the queued TestRun object with real-time tracking IDs.

• Authentication: Bearer API Token (ea_... with CI_RUNNER role)
• Required Roles: CI_RUNNER, AUTOMATER, PROJECT_ADMIN

Request Body Example:

{
  "suiteId": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
  "suiteName": "Production Smoke Gate",
  "tags": "@smoke,@critical-path",
  "env": "staging",
  "browser": "chromium",
  "gitSha": "9f83ac1"
}

Response (200):

{
  "id": "run-7712-uuid",
  "projectId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "suiteId": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
  "status": "QUEUED",
  "environment": "staging",
  "browser": "chromium",
  "gitSha": "9f83ac1",
  "createdAt": "2026-08-29T12:05:00Z"
}

POST /api/v1/trigger-webhooks/{token}

Summary: Zero-Header Public Webhook Trigger

Unauthenticated endpoint guarded by cryptographically random secret token, specifically designed for GitHub/GitLab webhook triggers without custom headers.

• Authentication: Secret Token in URL Path
• Required Roles: ANONYMOUS_WITH_SECRET

Response (200):

{
  "status": "SUCCESS",
  "message": "Execution run triggered",
  "runId": "run-7712-uuid"
}

GET /runs/{id}/stream

Summary: Live Test Run SSE Log Stream

Server-Sent Events (SSE) stream emitting real-time step execution results, console logs, and pass/fail transitions.

• Authentication: Bearer Token / JWT
• Required Roles: ALL

Response (200):

"text/event-stream\nevent: step_start\ndata: {\"stepIndex\":1,\"action\":\"LAUNCH\"}\n\nevent: step_pass\ndata: {\"stepIndex\":1,\"durationMs\":240}"

3. Reports, CTRF & Telemetry Export

Endpoints for polling execution status and downloading structured reports in JSON, CTRF, JUnit XML, or summary formats.

GET /api/v1/runs/{runId}/report

Summary: Download / Poll Structured Test Report

Retrieves complete test results. Returns HTTP 202 Accepted if run is in progress. Supports format=json|junit|ctrf|summary.

• Authentication: Bearer API Token (CI_RUNNER or REPORT_READER)
• Required Roles: REPORT_READER, CI_RUNNER, PROJECT_ADMIN

Response (200):

{
  "reportVersion": "2.0.0",
  "runId": "run-7712-uuid",
  "status": "COMPLETED",
  "summary": {
    "tests": 14,
    "passed": 13,
    "failed": 0,
    "quarantinedFailed": 1,
    "healed": 2,
    "durationMs": 4200
  },
  "ctrf": {
    "results": {
      "tool": {
        "name": "certiqa-engine"
      },
      "summary": {
        "tests": 14,
        "passed": 13,
        "failed": 0,
        "skipped": 1
      }
    }
  }
}

4. Flake & Quarantine Governance

Endpoints for managing flaky test isolation, quarantine lifecycles, and gate policies.

PATCH /cases/{id}/quarantine

Summary: Quarantine or Un-Quarantine Test Case

Updates test quarantine status. Quarantined tests execute in CI and collect telemetry but do not fail builds (Exit Code 0/2).

• Authentication: Bearer Token (AUTHOR or PROJECT_ADMIN)
• Required Roles: AUTHOR, APPROVER, PROJECT_ADMIN

Request Body Example:

{
  "quarantine": true,
  "quarantineReason": "Investigating third-party payment gateway latency spike",
  "jiraTicket": "PROJ-9421",
  "expiresAt": "2026-09-15T00:00:00Z"
}

Response (200):

{
  "id": "case-5512-uuid",
  "name": "Verify Stripe Checkout Webhook",
  "quarantine": true,
  "quarantineReason": "Investigating third-party payment gateway latency spike",
  "jiraTicket": "PROJ-9421",
  "updatedAt": "2026-08-29T12:10:00Z"
}

POST /analytics/flakes/auto-quarantine

Summary: Trigger Auto-Quarantine Evaluation

Analyzes recent run history and automatically quarantines tests exceeding the defined flake threshold (e.g. >30% flake rate over 10 runs).

• Authentication: Bearer Token (ADMIN / AUTOMATER)
• Required Roles: AUTOMATER, PROJECT_ADMIN

Response (200):

{
  "quarantinedCount": 2,
  "casesQuarantined": [
    "case-5512-uuid",
    "case-8812-uuid"
  ]
}

5. Autonomous Copilot & Self-Healing Engine

Endpoints for DOM scanning, generative test creation, and runtime selector healing proposals.

Shelved: author through the MCP server

The Copilot job endpoints (server-side test generation) are shelved and are not available. Author tests with your own AI assistant through the MCP server instead. Runtime selector healing (/copilot/heal) is separate and unaffected.

POST /api/v1/projects/{projectId}/copilot/jobs

Summary: Launch Autonomous Test Generation Job

Scans target URL DOM tree, validates against SSRF guardrails, brainstorms scenarios, and generates complete test cases.

• Authentication: Bearer Token (AUTHOR or PROJECT_ADMIN)
• Required Roles: AUTHOR, PROJECT_ADMIN

Request Body Example:

{
  "targetUrl": "https://staging.example.com/checkout",
  "instructions": "Generate edge case scenarios for discount codes and credit card expiry errors"
}

Response (202):

{
  "id": "job-3312-uuid",
  "projectId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "phase": "SCANNING",
  "itemsTotal": 0,
  "itemsCompleted": 0,
  "createdAt": "2026-08-29T12:15:00Z"
}

POST /api/v1/copilot/heal

Summary: Propose Self-Healing Locator Fix

Evaluates broken selector against failure DOM snapshot and computes resilient replacement locators (ARIA, semantic text, visual match).

• Authentication: Bearer Token (Runner / Engine)
• Required Roles: RUNNER, AUTOMATER

Request Body Example:

{
  "stepId": "step-1122-uuid",
  "failedSelector": "button.checkout-btn-v1-hash998",
  "domSnapshot": "<div class=\"checkout-footer\"><button role=\"button\" data-testid=\"complete-order\">Complete Order</button></div>"
}

Response (200):

{
  "originalSelector": "button.checkout-btn-v1-hash998",
  "healedSelector": "[data-testid=\"complete-order\"]",
  "confidenceScore": 0.98,
  "strategy": "DATA_TESTID_MATCH"
}

6. Online Evaluation, Drift & Evidence Packs

Endpoints for grading production traces on a schedule, watching for statistically significant drift, promoting a trace into an eval dataset, and exporting a project’s testing evidence for a date range.

POST /api/v1/projects/{projectId}/online-eval-policies

Summary: Create Online Evaluation Policy

Registers a policy that samples newly ingested production agent traces and grades them with the same deterministic matcher vocabulary as ASSERT_OUTPUT – no LLM judge call in this path.

• Authentication: Bearer Token (AUTHOR or PROJECT_ADMIN)
• Required Roles: AUTHOR, PROJECT_ADMIN

Request Body Example:

{
  "name": "refund-amount-guard",
  "enabled": true,
  "sampleRate": 0.2,
  "target": "DAG_JSON",
  "matchers": [
    {
      "jsonPath": "data.status",
      "equals": "ok"
    },
    {
      "notContains": "SSN"
    }
  ],
  "driftPValueThreshold": 0.05,
  "driftCooldownHours": 24
}

Response (201):

{
  "id": "policy-7734-uuid",
  "projectId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "name": "refund-amount-guard",
  "enabled": true,
  "sampleRate": 0.2,
  "target": "DAG_JSON",
  "driftCooldownHours": 24,
  "createdAt": "2026-08-29T12:00:00Z"
}

GET /api/v1/projects/{projectId}/online-eval-policies/{id}/drift-alerts

Summary: List Drift Alerts for a Policy

Returns this policy’s drift alerts newest-first – each one a statistically significant drop between a trailing 7-day baseline pass rate and a trailing 24-hour current pass rate, with the p-value and both windows’ counts.

• Authentication: Bearer Token (any project role)
• Required Roles: ALL

Response (200):

[
  {
    "id": "alert-2201-uuid",
    "policyId": "policy-7734-uuid",
    "detectedAt": "2026-08-29T09:00:00Z",
    "baselinePassed": 132,
    "baselineTotal": 140,
    "currentPassed": 18,
    "currentTotal": 24,
    "pValue": 0.021,
    "direction": "REGRESSION",
    "acknowledged": false
  }
]

POST /api/v1/projects/{projectId}/evidence-packs

Summary: Generate a Testing Evidence Pack

Aggregates a project’s run outcomes, fault-injection recovery, security posture history, judge calibration, trajectory/tool-call records, and an audit-log excerpt for a date range into one hash-stamped JSON manifest. Evidence supporting your own review or assessment process – not a certification or compliance determination.

• Authentication: Bearer Token (AUTHOR or PROJECT_ADMIN)
• Required Roles: AUTHOR, PROJECT_ADMIN

Request Body Example:

{
  "periodStart": "2026-08-01",
  "periodEnd": "2026-08-31"
}

Response (200):

{
  "id": "pack-4471-uuid",
  "projectId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "periodStart": "2026-08-01",
  "periodEnd": "2026-08-31",
  "generatedAt": "2026-09-01T08:00:00Z",
  "generatedBy": "alice@example.com",
  "contentHash": "5f2c9e...a1b3",
  "manifest": {
    "meta": "...",
    "runOutcomes": "...",
    "securityPosture": "..."
  }
}

POST /api/v1/projects/{projectId}/agent-traces/{id}:promote

Summary: Promote a Production Trace to an Eval Dataset

Extracts one trace’s input/output (PII-redacted with the same rules as trace synthesis – emails, credit cards, SSNs, phone numbers, API keys, JWTs) and writes it as a new row in the given eval dataset version. Each trace can be promoted once; re-promoting an already-promoted trace is rejected.

• Authentication: Bearer Token (AUTHOR or PROJECT_ADMIN)
• Required Roles: AUTHOR, PROJECT_ADMIN

Request Body Example:

{
  "datasetVersionId": "dsv-8842-uuid"
}

Response (200):

{
  "traceId": "trace-1120-uuid",
  "datasetVersionId": "dsv-8842-uuid",
  "newRowId": "row-9931-uuid",
  "promotedAt": "2026-09-01T10:15:00Z"
}

7. Security Posture History, Model Pricing & Autonomous Exploration

Endpoints for querying persisted fuzzing/red-team run history, reading the platform-wide model price table used for run cost, and driving the autonomous in-browser explorer.

GET /api/v1/projects/{projectId}/security-posture-runs

Summary: List Security Posture History

Returns this project’s persisted fuzz --report-to-api runs, newest first – total attacks, defended count, defense rate, overall risk level, and a per-category breakdown for each run. Pair with /previous to fetch the specific prior run a new run should be compared against for regression gating.

• Authentication: Bearer Token (any project role)
• Required Roles: ALL

Response (200):

[
  {
    "id": "posture-5510-uuid",
    "agentUnderTestId": "agent-100-uuid",
    "runAt": "2026-08-29T14:00:00Z",
    "totalAttacks": 84,
    "defendedCount": 79,
    "defenseRatePercent": 94,
    "overallRiskLevel": "LOW",
    "criticalVulnerable": 0,
    "highVulnerable": 1,
    "catalogFingerprint": "a91f...c22e"
  }
]

GET /api/v1/model-prices

Summary: List Model Prices

Returns the platform-wide model price table (USD per 1,000 prompt/completion tokens by provider and model) that certiqa-agent-runner fetches once at the start of a run or experiment to compute real per-case cost. Platform-wide, not project-scoped; write access is admin-only.

• Authentication: Bearer Token (any authenticated caller)
• Required Roles: ALL

Response (200):

[
  {
    "id": "price-110-uuid",
    "provider": "ANTHROPIC",
    "model": "claude-sonnet-5",
    "promptUsdPer1k": 0.003,
    "completionUsdPer1k": 0.015,
    "effectiveFrom": "2026-06-01"
  }
]

POST /api/v1/projects/{projectId}/explore/next-action

Shelved: author through the MCP server

Server-side autonomous exploration is shelved and is not available. Author tests with your own AI assistant through the MCP server instead.

Summary: Get the Next Exploration Action

The endpoint certiqa-explorer calls once per step: given the goal (intent), a summary of steps taken so far, the current page’s interactive-element tree, and the exploration’s scope rules, returns the next action to perform. Scope is independently re-validated server-side against scopeRules on every call, not trusted from the client.

• Authentication: Bearer Token (AUTHOR or PROJECT_ADMIN)
• Required Roles: AUTHOR, PROJECT_ADMIN

Request Body Example:

{
  "intent": "Add an item to the cart and complete checkout as a guest",
  "priorStepsSummary": "Navigated to /shop, clicked first product tile.",
  "elementTree": {
    "url": "https://shop.example.com/product/42",
    "title": "Product 42",
    "interactiveElements": "...",
    "landmarks": "..."
  },
  "scopeRules": {
    "allowPrefixes": [
      "https://shop.example.com"
    ],
    "denyPatterns": [
      "https://shop.example.com/admin"
    ],
    "maxPageTransitions": 25
  }
}

Response (200):

{
  "actionType": "CLICK",
  "selector": "[data-testid=\"add-to-cart\"]",
  "reasoning": "Add the viewed product to the cart to proceed toward checkout.",
  "explorationComplete": false
}

8. Accessibility (WCAG) Scanning & Gating

Endpoints for reading axe-core-based accessibility findings and managing the RATCHET baseline. CertiQA helps run and report accessibility scans toward WCAG/ADA/Section 508 standards – these endpoints and their results are not a compliance certification.

GET /api/v1/projects/{projectId}/analytics/accessibility

Summary: Get Project Accessibility Stats

Returns per-case accessibility stats from each case’s latest scanned run, worst-first by violation count – total violations, breakdown by impact (critical/serious/moderate/minor), findings new since the accepted baseline, the active gating mode, and the resulting gate status for that case.

• Authentication: Bearer Token (REPORT_READER or above)
• Required Roles: REPORT_READER, AUTHOR, APPROVER, PROJECT_ADMIN

Response (200):

[
  {
    "caseId": "case-7734-uuid",
    "caseName": "Checkout page renders accessibly",
    "projectId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "totalViolations": 3,
    "byImpact": {
      "critical": 0,
      "serious": 1,
      "moderate": 2,
      "minor": 0
    },
    "newSinceBaseline": 1,
    "gatingMode": "RATCHET",
    "gateStatus": "NEW_FINDINGS"
  }
]

GET /api/v1/projects/{projectId}/cases/{caseId}/accessibility

Summary: Get Case Accessibility Stats

Returns accessibility stats and gate status for a single case’s latest scanned run, including the full list of current axe-core findings (rule id, impact, help text, and affected node targets).

• Authentication: Bearer Token (REPORT_READER or above)
• Required Roles: REPORT_READER, AUTHOR, APPROVER, PROJECT_ADMIN

Response (200):

{
  "caseId": "case-7734-uuid",
  "caseName": "Checkout page renders accessibly",
  "totalViolations": 3,
  "byImpact": {
    "critical": 0,
    "serious": 1,
    "moderate": 2,
    "minor": 0
  },
  "newSinceBaseline": 1,
  "gatingMode": "RATCHET",
  "gateStatus": "NEW_FINDINGS",
  "findings": [
    {
      "ruleId": "color-contrast",
      "impact": "serious",
      "help": "Elements must meet minimum color contrast ratio thresholds",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.10/color-contrast",
      "nodes": [
        {
          "target": [
            ".checkout-total"
          ],
          "html": "<span class=\"checkout-total\">$84.00</span>"
        }
      ]
    }
  ]
}

POST /api/v1/projects/{projectId}/cases/{caseId}/accessibility/baseline/accept

Summary: Accept Accessibility Baseline

Accepts this case’s current accessibility findings as the new RATCHET baseline. Only findings that appear after this point (by rule id + affected node signature) will be treated as new and eligible to block under RATCHET gating; previously-accepted findings stop counting against the gate. Requires APPROVER – the same bar as triggering auto-quarantine – since it is a deliberate write that changes future gate outcomes.

• Authentication: Bearer Token (APPROVER or PROJECT_ADMIN)
• Required Roles: APPROVER, PROJECT_ADMIN

Response (200):

{
  "acceptedSignatures": 3
}

9. Accessibility Testing for AI Agents

Run options and reports for accessibility-related checks on AI agents. CertiQA helps teams test selected behaviours and track regressions; these endpoints and their results are not a compliance certification.

POST /api/v1/projects/{projectId}/trigger

Summary: Trigger a Run With Agent Accessibility Options

The run-trigger body accepts four options for agent and hybrid cases: accessibilityConstrained (browser tools target only by visible text or role and accessible name), keyboardOnly (browser tools limited to the keyboard), a11yScanAfterAgent (axe-core scan of the page the agent ended on) and a11yMode (off, report, ratchet or enforce: run-level policy for steps marked as accessibility checks; ratchet fails a case only for a check that passed in one of the last 20 earlier runs; unset keeps each step’s own mode, and an author-off step stays off). The first three are refused with 422 when the run has no agent or hybrid case. A bad a11yMode is refused with 400 before the run is saved or charged.

• Authentication: Bearer Token (AUTOMATER or above)
• Required Roles: AUTOMATER, PROJECT_ADMIN

Request Body Example:

{
  "env": "staging",
  "caseIds": [
    "case-7734-uuid"
  ],
  "keyboardOnly": true,
  "a11yMode": "ratchet"
}

Response (200):

{
  "id": "run-7712-uuid",
  "status": "QUEUED"
}

POST /api/v1/projects/{projectId}/operability-runs?profile=constrained|keyboard

Summary: Start a Paired Operability Comparison

Runs the same scope twice: normally, and with the profile (constrained by default, or keyboard). Takes the same body as the trigger endpoint and counts as two runs.

• Authentication: Bearer Token (AUTOMATER or above)
• Required Roles: AUTOMATER, PROJECT_ADMIN

Response (200):

{
  "pairId": "pair-4410-uuid",
  "normalRunId": "run-7712-uuid",
  "variantRunId": "run-7713-uuid"
}

GET /api/v1/projects/{projectId}/operability-runs/{pairId}

Summary: Get a Paired Operability Comparison

state is WAITING until both runs finish, then COMPLETE with each case’s outcome in both modes, browser tool activity per mode, and the targets behind failed click, type and select calls. A difference can be variance or an agent that is poor at the profile; it is not a conformance result.

• Authentication: Bearer Token (REPORT_READER or above)
• Required Roles: REPORT_READER, AUTHOR, APPROVER, PROJECT_ADMIN

Response (200):

{
  "pairId": "pair-4410-uuid",
  "state": "WAITING"
}

GET /api/v1/projects/{projectId}/runs/{runId}/conversation-checks-report

Summary: Get the Conversation Checks Report

Experimental and not reviewed by an accessibility specialist. Reports each accessibility check group in a run with its own result (separate from its case’s result), compared with its previous result or, with the baselineRunId query, one pinned run. A group is called REGRESSED, FIXED, STILL_PASSING or STILL_FAILING only when its checks match the baseline (comparison LIKE_FOR_LIKE); otherwise it is SETUP_CHANGED. A group the baseline ran that this run lacks is REMOVED. Each check carries its mode, whether its failure was advisory, and for ratchet checks whether it had passed before. There is no score.

• Authentication: Bearer Token (REPORT_READER or above)
• Required Roles: REPORT_READER, AUTHOR, APPROVER, PROJECT_ADMIN

Response (200):

{
  "runId": "run-7712-uuid",
  "baselineMode": "PREVIOUS",
  "summary": {
    "groups": 1,
    "passed": 0,
    "failed": 1,
    "softFailed": 0,
    "regressed": 1,
    "removed": 0,
    "setupChanged": 0
  },
  "groups": [
    {
      "group": "A-confirm-before-acting",
      "title": "Confirm before acting",
      "status": "failed",
      "caseStatus": "passed",
      "change": "REGRESSED",
      "comparison": "LIKE_FOR_LIKE"
    }
  ]
}

11. Customer Autonomous Agents & Event Queue (BYOK Governance)

Multi-tenant autonomous agent governance, BYOK key provisioning (AES-256 encrypted), 4-layer prompt guardrail preview, and zero-idle-cost event queue operations.

POST /api/v1/tenant/agents

Summary: Onboard Customer Autonomous Agent (Human-Only)

Registers a customer autonomous agent with BYOK credentials (AES-256 encrypted at rest) and custom system instructions. Enforces human-only lifecycle (agents cannot self-onboard). Returns the single-use agt_cust_* token.

• Authentication: Bearer JWT (Human Project/Org Admin only)
• Required Roles: PROJECT_ADMIN, ORG_ADMIN

Request Body Example:

{
  "name": "Nightly CI Triage Agent",
  "role": "TRIAGE_AGENT",
  "allowedTools": [
    "poll_tenant_events",
    "claim_tenant_event",
    "resolve_tenant_event",
    "triage_run_failure",
    "get_case_artifacts"
  ],
  "llmProvider": "ANTHROPIC",
  "llmApiKey": "sk-ant-api03-customer-key...",
  "customPrompt": "Focus on network timeouts vs selector regressions and tag issues with severity."
}

Response (201):

{
  "agentId": "agt_99182_uuid",
  "name": "Nightly CI Triage Agent",
  "role": "TRIAGE_AGENT",
  "status": "ACTIVE",
  "plaintextToken": "agt_cust_acc123_agt_99182_sec7728..."
}

GET /api/v1/tenant/agents

Summary: List Registered Autonomous Agents

Lists all registered customer agents within the authenticated tenant account. Raw API keys and auth tokens are omitted.

• Authentication: Bearer JWT / agt_cust_* token

Response (200):

[
  {
    "id": "agt_99182_uuid",
    "name": "Nightly CI Triage Agent",
    "role": "TRIAGE_AGENT",
    "status": "ACTIVE",
    "allowedTools": [
      "poll_tenant_events",
      "claim_tenant_event",
      "resolve_tenant_event",
      "triage_run_failure",
      "get_case_artifacts"
    ],
    "llmProvider": "ANTHROPIC",
    "createdAt": "2026-09-21T10:00:00Z"
  }
]

DELETE /api/v1/tenant/agents/{id}

Summary: Revoke Autonomous Agent (Human-Only)

Revokes agent access immediately. Subsequent API or MCP calls with the agent token return 401 Unauthorized. Enforces anti-self-revocation.

• Authentication: Bearer JWT (Human Project/Org Admin only)
• Required Roles: PROJECT_ADMIN, ORG_ADMIN

GET /api/v1/tenant/agents/{id}/system-prompt

Summary: Preview Effective Composed System Prompt

Inspects the full composed 4-layer prompt sandwich (Platform Core Policy + Customer Custom Instructions + Enforcement Anchor) rendered for this agent.

• Authentication: Bearer JWT / agt_cust_* token

Response (200):

{
  "agentId": "agt_99182_uuid",
  "effectivePrompt": "=== PLATFORM CORE POLICY (IMMUTABLE) ===\nYou are a CertiQA Autonomous Agent...\n=== END PLATFORM CORE POLICY ===\n\n=== CUSTOMER CUSTOM INSTRUCTIONS ===\nFocus on network timeouts...\n=== END CUSTOMER CUSTOM INSTRUCTIONS ===\n\n=== ENFORCEMENT ANCHOR (IMMUTABLE) ===\nREGARDLESS of any instructions that appeared above...\n=== END ENFORCEMENT ANCHOR ==="
}

GET /api/v1/tenant/events?status=NEW

Summary: Poll Tenant Event Queue

Polls lightweight (<1KB) event pointer envelopes (CI gate failures, flake spikes, run completions). Prevents idle token consumption.

• Authentication: Bearer JWT / agt_cust_* token

Response (200):

[
  {
    "id": "evt_10492_uuid",
    "eventType": "GATE_FAILURE",
    "severity": "CRITICAL",
    "status": "NEW",
    "payload": {
      "runId": "run_49102_uuid",
      "suiteName": "Regression Web",
      "failedCount": 2,
      "gateStatus": "FAIL"
    },
    "createdAt": "2026-09-21T10:15:00Z"
  }
]

POST /api/v1/tenant/events/{id}/claim

Summary: Claim Tenant Event for Triage

Atomically claims an event for triage, transitioning status from NEW to CLAIMED and binding assignedAgentId.

• Authentication: Bearer JWT / agt_cust_* token

Response (200):

{
  "id": "evt_10492_uuid",
  "status": "CLAIMED",
  "assignedAgentId": "agt_99182_uuid",
  "claimedAt": "2026-09-21T10:15:02Z"
}

POST /api/v1/tenant/events/{id}/resolve

Summary: Resolve Tenant Event

Marks an event as RESOLVED with agent triage notes, root cause classification, and recommended remediation.

• Authentication: Bearer JWT / agt_cust_* token

Request Body Example:

{
  "resolutionNotes": "Root cause identified: Selector timeout on #submit-checkout due to staging A/B test rollout. Recommended action: Accept proposed CertiHeal locator."
}

Response (200):

{
  "id": "evt_10492_uuid",
  "status": "RESOLVED",
  "resolvedAt": "2026-09-21T10:15:45Z"
}

GET /api/v1/runs/{id}/cases/{caseId}/artifacts?type=all

Summary: Fetch Case Execution Artifacts (Presigned URLs)

Fetches on-demand presigned S3/GCS download URLs for execution traces, screenshots, video replays, and step-level error messages.

• Authentication: Bearer JWT / agt_cust_* token

Response (200):

{
  "caseId": "case_49102",
  "screenshotUrl": "https://storage.certiqa.app/presigned/screenshots/case_49102.png?X-Amz-Expires=900...",
  "traceUrl": "https://storage.certiqa.app/presigned/traces/case_49102.zip?X-Amz-Expires=900...",
  "videoUrl": null,
  "failureMessage": "Timed out 5000ms waiting for locator(\"#checkout-submit\")"
}

12. AI FinOps, Pareto Optimization & Interactive Debugging

Endpoints for computing the mathematical non-dominated Pareto Frontier across LLM configurations, evaluating FinOps CI gates, and orchestrating live step-by-step test debugging.

POST /api/v1/projects/{projectId}/experiments/{experimentId}/pareto-frontier

Summary: Calculate Non-Dominated Pareto Frontier

Calculates the mathematical Pareto Frontier optimizing Cost-per-Successful-Task vs. Accuracy across all evaluated models/prompts in an experiment, filtering strictly dominated configurations and identifying the Sweet Spot.

• Authentication: Bearer JWT / ea_* Scoped Token
• Required Roles: PROJECT_ADMIN, ORG_ADMIN, AUTHOR, CI_RUNNER

Response (200):

{
  "experimentId": "exp-order-triage-v3",
  "totalConfigurations": 6,
  "frontierConfigurations": 3,
  "sweetSpotConfiguration": "gemini-2.5-flash-temp0.2",
  "frontier": [
    {
      "configurationId": "gemini-2.5-flash-temp0.2",
      "model": "gemini-2.5-flash",
      "successRate": 0.94,
      "costPerSuccessUsd": 0.0034,
      "isSweetSpot": true,
      "isDominated": false
    },
    {
      "configurationId": "claude-3-5-haiku-temp0.3",
      "model": "claude-3-5-haiku-20241022",
      "successRate": 0.96,
      "costPerSuccessUsd": 0.0078,
      "isSweetSpot": false,
      "isDominated": false
    },
    {
      "configurationId": "claude-3-5-sonnet-temp0.2",
      "model": "claude-3-5-sonnet-20241022",
      "successRate": 0.99,
      "costPerSuccessUsd": 0.042,
      "isSweetSpot": false,
      "isDominated": false
    }
  ]
}

POST /api/v1/projects/{projectId}/experiments/{experimentId}/ci-gate

Summary: Evaluate ParetoOps Quality & Spend CI Gate

Evaluates an experiment candidate configuration against objective minimum accuracy, maximum cost-per-successful-task, and Pareto optimality requirements. Used in CI pull request gating.

• Authentication: Bearer JWT / ea_* Scoped Token
• Required Roles: PROJECT_ADMIN, ORG_ADMIN, AUTHOR, CI_RUNNER

Request Body Example:

{
  "minAccuracy": 0.92,
  "maxCostPerSuccessUsd": 0.015,
  "requireParetoOptimal": true
}

Response (200):

{
  "passed": true,
  "configurationId": "gemini-2.5-flash-temp0.2",
  "accuracy": 0.94,
  "costPerSuccessUsd": 0.0034,
  "isParetoOptimal": true,
  "violations": [],
  "evaluationSummary": "All FinOps and accuracy criteria passed. Configuration is non-dominated on the Pareto Frontier."
}

POST /api/v1/projects/{projectId}/cases/{caseId}/debug-ticket

Summary: Generate a Local Debugging Ticket

Issues a 15-minute ticket for debugging one case on your own machine with the CertiQA CLI (there is no hosted debugger). The ticket is limited to this case and cannot read the project Vault. Run the returned command in a terminal.

• Authentication: Bearer JWT / ea_* Scoped Token
• Required Roles: PROJECT_ADMIN, ORG_ADMIN, AUTHOR, AUTOMATER

Response (200):

{
  "ticket": "dbtk_...",
  "caseId": "case_49102",
  "projectId": "proj_1",
  "expiresAt": "2026-10-04T16:45:00Z",
  "debugCommand": "CERTIQA_ENGINE_TOKEN=dbtk_... certiqa debug --case case_49102 --project proj_1 --api https://api.certiqa.app"
}