BHANUJBHANUJ
v1.0.3

REST APIs

AI Governance Platform exposes a versioned FastAPI REST control plane for operational integrations. The REST layer is transport-only: routers use request/response DTOs, mapper classes, and API service facades.

Overview

Base path: /api/v1. Documentation endpoints are available at /openapi.json, /docs, and /redoc.

Tenant Context

Tenant-scoped requests send X-AI Governance Platform-Organization-Id, X-AI Governance Platform-Project-Id, X-Request-Id, and optionally X-Correlation-Id. X-AI Governance Platform-Actor-Id is accepted only with the development identity provider. Organization administration is available under /api/v1/organizations; the resolved scope, roles, and permissions are returned by /api/v1/context.

Health and Metadata

  • GET /health
  • GET /ready
  • GET /api/v1

Registry APIs

  • GET /api/v1/providers/{provider_name}
  • GET /api/v1/prompts
  • POST /api/v1/prompts
  • POST /api/v1/prompts/{prompt_id}/versions
  • GET /api/v1/prompts/{prompt_name}
  • POST /api/v1/prompts/observations
  • GET /api/v1/models
  • GET /api/v1/models/runtime-providers
  • POST /api/v1/models/runtime-capabilities/resolve
  • POST /api/v1/models
  • POST /api/v1/models/{model_id}/versions
  • POST /api/v1/models/{model_id}/activate
  • POST /api/v1/models/{model_id}/deprecate
  • POST /api/v1/models/{model_id}/archive
  • GET /api/v1/models/{model_id}
  • POST /api/v1/models/observations
  • GET /api/v1/datasets
  • GET /api/v1/datasets/{dataset_id}
  • POST /api/v1/datasets/upload
  • POST /api/v1/datasets/{dataset_id}/freeze
  • POST /api/v1/datasets/{dataset_id}/activate
  • POST /api/v1/datasets/{dataset_id}/deprecate
  • POST /api/v1/datasets/{dataset_id}/archive

Prompt and model observation endpoints record runtime/evaluation evidence as immutable Observed assets. Managed prompt and model endpoints create immutable draft versions; model lifecycle endpoints make activation, deprecation, and archival explicit. Producers provide a source system and optional source reference; prompt content may be withheld when a SHA-256 content hash is supplied. The same evidence is idempotent, while conflicting evidence for an existing logical version returns 409.

Dataset upload accepts UTF-8 CSV, JSONL, and NDJSON and returns a DRAFT registry version after validation, checksum calculation, and immutable S3-compatible object storage. Dataset lifecycle endpoints freeze, activate, deprecate, or archive a managed version without changing its historical bytes or checksum. See the Observed Asset Ingestion tutorial for producer examples.

Runtime Connection APIs

  • GET /api/v1/runtime-connections/providers
  • POST /api/v1/runtime-connections/validate
  • GET, POST /api/v1/runtime-connections
  • GET /api/v1/runtime-connections/{runtime_connection_id}
  • PATCH /api/v1/runtime-connections/{runtime_connection_id}
  • POST /api/v1/runtime-connections/{runtime_connection_id}/test
  • GET /api/v1/runtime-connections/{runtime_connection_id}/models

Runtime Connections hold tenant-scoped runtime configuration and secret references separately from immutable model definitions. Connection responses never return resolved credential values; validation and test operations record whether the configuration and references can be used.

Behavior Contract APIs

Enterprise Behavior Contract endpoints create, import, inspect, validate, release, and resolve canonical governed artifacts. Impact planning, simulation, and approval actions remain bound to the exact immutable contract fingerprint.

  • POST /api/v1/enterprise/behavior-contracts
  • GET /api/v1/enterprise/behavior-contracts
  • POST /api/v1/enterprise/behavior-contracts/import
  • GET /api/v1/enterprise/behavior-contracts/{contract_id}/versions
  • GET /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/yaml
  • GET /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/json
  • POST /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/validate
  • POST /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/impact-plan
  • POST /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/simulations
  • POST /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/submit-for-approval
  • POST /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/approve
  • GET /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/promotion-readiness
  • GET /api/v1/enterprise/behavior-contracts/{contract_id}/versions/{version}/resolve

Read AI Releases for the complete Studio, storage, evidence, and runtime workflow.

Evaluation APIs

  • POST /api/v1/evaluations
  • POST /api/v1/evaluations/jobs
  • GET /api/v1/evaluations/{evaluation_id}
  • GET /api/v1/evaluations/history/{execution_id}
  • GET /api/v1/evaluations/latest/{execution_id}

Experiment APIs

  • POST /api/v1/experiments
  • GET /api/v1/experiments
  • GET /api/v1/experiments/{experiment_id}
  • POST /api/v1/experiments/{experiment_id}/candidates
  • POST /api/v1/experiments/{experiment_id}/run
  • GET /api/v1/experiments/{experiment_id}/leaderboard

Experiment insight endpoints:

  • GET /api/v1/experiments/{experiment_id}/insights
  • GET /api/v1/experiments/{experiment_id}/candidates/{candidate_id}/insights
  • GET /api/v1/experiments/{experiment_id}/comparative-insights

Replay APIs

Replay Management reproduces a historical execution from frozen evidence; it is distinct from retrying an original execution. Source discovery is tenant-scoped and cursor-paginated. Replay creation and lifecycle actions are idempotent when clients provide a stable idempotency key.

  • GET /api/v1/replay-executions/search
  • GET /api/v1/replay-executions/{execution_id}
  • POST /api/v1/replays
  • GET /api/v1/replays
  • GET /api/v1/replays/{replay_id}
  • POST /api/v1/replays/{replay_id}/submit
  • POST /api/v1/replays/{replay_id}/evaluate
  • POST /api/v1/replays/{replay_id}/cancel
  • POST /api/v1/replays/{replay_id}/archive
  • GET /api/v1/replays/{replay_id}/result

See Replay Management for lifecycle, compatibility, worker, and production-search guidance.

Job APIs

  • POST /api/v1/jobs
  • GET /api/v1/jobs
  • GET /api/v1/jobs/{job_id}
  • POST /api/v1/jobs/{job_id}/cancel
  • POST /api/v1/jobs/{job_id}/retry
  • GET /api/v1/jobs/{job_id}/result

Ontology Synchronization APIs

  • GET /api/v1/ontology/synchronization/events
  • GET /api/v1/ontology/synchronization/events/metrics
  • GET /api/v1/ontology/synchronization/events/{event_id}
  • POST /api/v1/ontology/synchronization/events/{event_id}/retry
  • POST /api/v1/ontology/synchronization/events/{event_id}/cancel

Ontology Graph Query APIs

  • GET /api/v1/ontology/entities/{entity_type}/{entity_id}
  • GET /api/v1/ontology/relationships/{relationship_id}
  • GET /api/v1/ontology/entities/{entity_type}/{entity_id}/relationships
  • GET /api/v1/ontology/entities/{entity_type}/{entity_id}/neighbourhood
  • GET /api/v1/ontology/entities/{entity_type}/{entity_id}/upstream
  • GET /api/v1/ontology/entities/{entity_type}/{entity_id}/downstream
  • GET /api/v1/ontology/path

Governance APIs

  • POST /api/v1/governance/compare
  • POST /api/v1/governance/drift
  • GET /api/v1/governance/reports/{evaluation_id}
  • GET /api/v1/investigations/by-correlation/{correlation_id}
  • GET /api/v1/investigations/by-job/{job_id}
  • GET /api/v1/investigations/by-evaluation/{evaluation_id}
  • GET /api/v1/investigations/by-audit/{audit_id}

Policy APIs

  • GET /api/v1/policy-schema
  • GET, POST /api/v1/policies
  • GET /api/v1/policies/{policy_id}
  • POST /api/v1/policies/{policy_id}/versions
  • GET /api/v1/policies/{policy_id}/versions/{version}
  • PUT /api/v1/policies/{policy_id}/versions/{version}/draft
  • POST /api/v1/policies/{policy_id}/versions/{version}/activate
  • POST /api/v1/policies/{policy_id}/versions/{version}/archive
  • POST /api/v1/policies/{policy_id}/versions/{version}/simulate

Policy administration creates and evolves draft versions. The backend-owned schema advertises the available target types, evidence fields, operators, effects, categories, and severities. Simulation returns the deterministic rule result and condition trace without changing policy lifecycle state. Read the Policy Engine guide for the decision model and lifecycle.

Decision APIs

  • POST /api/v1/decisions/evaluate
  • GET /api/v1/decisions/{decision_id}
  • GET /api/v1/decisions/{decision_id}/detail
  • GET /api/v1/decisions
  • GET /api/v1/decisions/{decision_id}/evidence
  • GET /api/v1/decisions/{decision_id}/lineage
  • GET /api/v1/decisions/{decision_id}/explain

Settings Control Plane

  • GET /api/v1/settings
  • GET /api/v1/settings/{key}
  • PATCH /api/v1/settings/{key}
  • POST /api/v1/settings/validate
  • GET /api/v1/settings/categories
  • GET /api/v1/settings/audit

Report APIs

Generate governance evidence reports as JSON or Markdown using the format query parameter:

  • GET /api/v1/reports/experiments/{experiment_id}
  • GET /api/v1/reports/evaluations/{evaluation_id}
  • GET /api/v1/reports/drift/{drift_id}
  • GET /api/v1/reports/investigations/{correlation_id}
  • GET /api/v1/reports/mcp-audit/{audit_id}

Error Envelope

REST errors use a common envelope:

json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message.",
    "details": {}
  }
}

Important error codes include:

  • PROVIDER_NOT_FOUND, UNSUPPORTED_METRIC, EVALUATION_NOT_FOUND
  • EXPERIMENT_NOT_FOUND, CANDIDATE_NOT_FOUND, INVALID_EXPERIMENT_REQUEST
  • JOB_NOT_FOUND, IDEMPOTENCY_CONFLICT
  • DecisionNotFound, PolicyNotFound, PolicyValidationFailed
  • EvidenceUnavailable, validation_error, internal_server_error

Boundaries

REST routers must not import repository implementations, provider adapters, or provider SDKs. They depend on API models, API mappers, and dependency-injected API service facades. Sensitive metadata keys such as API keys, tokens, passwords, secrets, and authorization values are scrubbed from REST metadata responses.