BHANUJBHANUJ
v1.2.2

REST APIs

AIGP provides a versioned REST API for integrations. This page explains the API shape and how requests and responses are handled.

Overview

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

Use the interactive API reference for the published public and operator contract, request examples, and in-browser testing.

Tenant Context

Tenant-scoped requests send X-AI-Governance-Organization-Id, X-AI-Governance-Project-Id, X-Request-Id, and optionally X-Correlation-Id. X-AI-Governance-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
  • 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.

Provider Installation APIs

A provider installation is the tenant-scoped configuration of an evaluator shipped with the deployment. It holds non-sensitive settings and secret references, not the resolved credential. Validation resolves references and initializes the provider without saving an installation or running an evaluation.

  • GET, POST /api/v1/provider-installations
  • POST /api/v1/provider-installations/validate
  • PATCH /api/v1/provider-installations/{installation_id}

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
  • GET /api/v1/experiments/{experiment_id}/run-plan
  • GET /api/v1/experiments/{experiment_id}/runs/{run_id}/evaluations
  • POST /api/v1/experiments/{experiment_id}/run
  • POST /api/v1/experiments/{experiment_id}/cancel
  • GET /api/v1/experiments/{experiment_id}/leaderboard
  • GET /api/v1/experiments/{experiment_id}/comparison

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

MCP Audit APIs

MCP audit endpoints expose privacy-safe records for controlled tool activity. They are inspection endpoints: they do not rerun a tool or expose protected inputs.

  • GET /api/v1/audit and /api/v1/audit/invocations
  • GET /api/v1/mcp/audit
  • GET /api/v1/mcp/audit/by-request/{request_id}
  • GET /api/v1/mcp/audit/by-correlation/{correlation_id}

Agents Runtime APIs

These endpoints record bounded facts from an external agent runtime and support review of its execution evidence. The runtime remains responsible for running the agent and retaining any protected content.

  • POST /api/v1/agent-executions
  • POST /api/v1/agent-executions/{execution_id}/events
  • POST /api/v1/agent-executions/{execution_id}/complete
  • GET /api/v1/agent-executions
  • GET /api/v1/agent-executions/agents
  • GET /api/v1/agent-executions/{execution_id}
  • GET /api/v1/agent-executions/{execution_id}/events
  • GET /api/v1/runtime-findings and /runtime-findings/{finding_id}
  • POST /api/v1/runtime-findings/detect and /runtime-findings/reconcile
  • GET, POST /api/v1/agents-runtime/causal-audits
  • GET /api/v1/agents-runtime/causal-audits/{audit_id}
  • GET /api/v1/agents-runtime/executions/{execution_id}/causal-audits
  • GET /api/v1/agents-runtime/executions/{execution_id}/causal-audit-eligibility
  • GET, POST /api/v1/agents-runtime/causal-audit/intervention-policies
  • POST /api/v1/agents-runtime/causal-audit/intervention-policies/{policy_id}/versions/{version}/validate, /preview, /activate, or /retire

See Agent Runtime Integration for the data contract, Runtime Findings for detector operations, and Causal Audit for eligibility and controlled-replay safety requirements.

Runtime Action Authorization

These endpoints govern one external operation immediately before the runtime invokes its protected tool. The delegation issuer and the runtime use separate authenticated identities; the PDP resolves the stored delegation and active applicable policies rather than trusting a caller-selected policy or agent-supplied purpose.

  • POST /api/v1/runtime-action-delegations
  • POST /api/v1/runtime-action-delegations/{delegation_id}/revoke
  • POST /api/v1/runtime-action-authorizations/authorize

Read Runtime Action Authorization for the trust boundary, delegation lifecycle, v2 request bindings, and runtime enforcement requirements.

Ontology Synchronization APIs

  • GET /api/v1/ontology/synchronization/events
  • GET /api/v1/ontology/synchronization/events/metrics
  • GET /api/v1/ontology/synchronization/events/{event_id}
  • GET /api/v1/ontology/synchronization/events/{event_id}/status
  • 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
  • POST /api/v1/ontology/demo/seed

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

Telemetry APIs

These read-only endpoints let an authorized operator inspect the privacy-preserving product telemetry policy and preview the exact sanitized snapshots. Previewing does not queue or transmit data.

  • GET /api/v1/telemetry/status
  • GET /api/v1/telemetry/preview

Read Telemetry & Privacy for the data boundary and disable controls.

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.