Docs

GovAI Functions 2.0

GovAI Functions 2.0

[!summary] Read-only flight-recorder APIs that package decision intelligence for operators, counsel, and executives — without replacing the immutable ledger verdict from compliance-summary.

Summary#

GovAI Functions 2.0 extends the append-only AI decision flight recorder (Postgres-backed trace events with hash-chain integrity) with richer event_type values, a structured govai_functions_v2 rollup inside trace export, and HTTP read APIs for packaged decision intelligence.

Compliance verdict flow

Prerequisites that must be satisfied before VALID is returned.

HTTP route catalog

Core audit API surface — normative shapes in OpenAPI.

API

Metadata & readiness

3
  • GET /healthLiveness after successful startup.GET
  • GET /readyPostgres, migrations, ledger writability (503 when not ready).GET
  • GET /statusPolicy version, environment, runtime diagnostics.GET

Ledger & compliance

4
  • POST /evidenceAppend hash-chained evidence event.POST
  • GET /compliance-summaryAuthoritative VALID / INVALID / BLOCKED verdict.GET
  • GET /bundle-hashCI digest gate: events_content_sha256.GET
  • GET /api/export/:run_idMachine-readable audit export.GET

Preview runtime

1
  • POST /v1/runtime/evaluatePreview policy evaluation (does not replace compliance-summary).POST

API endpoints#

GET/api/functions/v2/{run_id}/flight-packAPI

Flight pack

Full operational picture — base trace export plus governance operating system rollup.

Auth Bearer session or enterprise JWT; permission ai_decision_trace_read

GET/api/functions/v2/{run_id}/executive-summaryAPI

Executive summary

Short leadership view — model, compliance-summary ref, integrity, optional executive brief.

Auth Bearer session or enterprise JWT; permission ai_decision_trace_read

GET/api/functions/v2/{run_id}/legal-evidence-manifestAPI

Legal evidence manifest

Indexed legal evidence references for counsel or regulatory packs.

Auth Bearer session or enterprise JWT; permission ai_decision_trace_read

GET/api/functions/v2/{run_id}/governance-scorecardAPI

Governance scorecard

Deterministic readiness score from telemetry (not a substitute for compliance-summary).

Auth Bearer session or enterprise JWT; permission ai_decision_trace_read

Authentication and permissions#

[!summary] Enterprise read routes use session or enterprise JWT — separate from audit API keys used for evidence ingestion and compliance-summary.

Enterprise read routes require:

  • Authorization: Bearer <token> — dashboard session bearer or compatible enterprise JWT
  • Optional x-govai-team-id when your deployment uses team scope
  • Permission ai_decision_trace_read

These routes are separate from audit API keys used for POST /evidence and GET /compliance-summary with GOVAI_API_KEY.

Try this locally#

GovAI try console
local
Try thisCopy and run in your environment

Validate and gate Functions 2.0 packs

Run the offline pack validator and the repo gate before promoting schema or sample packs.

Command
python3 scripts/validate_govai_functions_v2_pack.py --strict examples/govai-functions-2/sample-flight-pack.v1.json
Expected output
validate_govai_functions_v2_pack: OK

Next stepContinue

Example API request#

Try API requestExample request (not a live call)
GET/api/functions/v2/{run_id}/executive-summaryAPIEnterprise

Fetch executive summary for a run

Leadership-facing rollup with compliance-summary reference and integrity status.

Auth Bearer session or enterprise JWT; ai_decision_trace_read

Request example
|
  export GOVAI_AUDIT_BASE_URL=https://audit.example.com
  export GOVAI_BEARER_TOKEN=your_session_bearer
  export GOVAI_RUN_ID=your_run_id

  curl -sS "$GOVAI_AUDIT_BASE_URL/api/functions/v2/$GOVAI_RUN_ID/executive-summary" \
    -H "Authorization: Bearer $GOVAI_BEARER_TOKEN" \
    -H "Accept: application/json"
Example response
|
  {
    "run_id": "01J...",
    "compliance_summary_ref": { "verdict": "VALID" },
    "integrity": { "chain_ok": true },
    "executive_brief": { "headline": "...", "risk_level": "low" }
  }

Error handling#

StatusMeaning
401 / 403Missing bearer, invalid token, or insufficient permission
404Unknown run_id or no trace data for the team scope
400Invalid path or query (Rust service returns stable JSON body)

Event ingestion uses POST /api/ai-decision-traces/{run_id}/events. Invalid payloads return 400 with a stable error body from the Rust service.

Best practices#

  1. Always gate releases with GET /compliance-summary for the authoritative verdict (VALID, INVALID, or BLOCKED).
  2. Use flight-pack for deep dives; use executive-summary for stakeholder updates.
  3. Bind ledger tenant to team before writing traces on hosted deployments.
  4. Validate offline packs with scripts/validate_govai_functions_v2_pack.py before CI promotion.

Clients#

  • OpenAPI: api/govai-http-v1.openapi.yaml (enterprise tier)
  • Python: GovAIClient.get_functions_v2_* in python/govai/client.py
  • TypeScript: @govai/functions-sdk in typescript-sdk/ (GovaiFunctionsV2Client for v2 routes)

Hosted platform#

On govbase.dev, the same routes are available on the GovAI audit origin when enterprise authentication is configured.

← Back to home