REST APIs

Overview

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

Tenant Context

Tenant-scoped requests send X-Kavach-Organization-Id, X-Kavach-Project-Id, X-Request-Id, and optionally X-Correlation-Id. X-Kavach-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/{prompt_name}
• GET /api/v1/models/{model_id}
• GET /api/v1/datasets/{dataset_id}

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}

Decision APIs

• POST /api/v1/decisions/evaluate
• GET /api/v1/decisions/{decision_id}
• 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:

{
  "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.