v2.0.1

REST Control Plane

This tutorial walks through the full REST API surface: health checks, provider discovery, evaluation submission, governance comparison and drift analysis, experiment creation, and job lifecycle management.

Overview

The REST control plane exposes versioned HTTP endpoints for every governance operation. This tutorial demonstrates the complete flow: starting with health checks, submitting evaluations, comparing results, analyzing drift, creating experiments, and managing jobs.

Health and metadata

Check service readiness and API version:

bash

curl http://localhost:8000/health
# => {"status": "ok"}

curl http://localhost:8000/ready
# => {"status": "ready"}

curl http://localhost:8000/api/v1
# => {"version": "1.1.0", ...}

Provider discovery

List available evaluation providers:

bash

curl http://localhost:8000/api/v1/providers
# => [{"name": "mock", ...}, {"name": "trulens", ...}]

Submitting evaluations

Submit a synchronous evaluation with the mock provider:

bash

curl -X POST http://localhost:8000/api/v1/evaluations \
  -H "content-type: application/json" \
  -d '{
    "provider_name": "mock",
    "workflow_id": "claim-validation",
    "workflow_name": "Claim Validation",
    "execution_id": "exec-1",
    "input": {"question": "Was the claim valid?"},
    "final_state": {"answer": "The claim appears valid."},
    "metric_specs": [{"name": "answer_relevance"}]
  }'

Comparison and drift

Compare two evaluations and detect drift:

bash

# Compare two evaluations
curl -X POST http://localhost:8000/api/v1/governance/compare \
  -H "content-type: application/json" \
  -d '{
    "baseline_evaluation_id": "eval-a",
    "candidate_evaluation_id": "eval-b"
  }'

# Analyze drift between evaluations
curl -X POST http://localhost:8000/api/v1/governance/drift \
  -H "content-type: application/json" \
  -d '{
    "baseline_evaluation_id": "eval-a",
    "candidate_evaluation_id": "eval-b"
  }'

Experiment creation

Create an experiment to track multiple candidates:

bash

curl -X POST http://localhost:8000/api/v1/experiments \
  -H "content-type: application/json" \
  -d '{
    "name": "smoke-experiment",
    "description": "Smoke-test experiment creation.",
    "metadata": {"owner": "smoke-test"}
  }'

Job lifecycle

Submit, list, cancel, and retry governance jobs:

bash

# Submit a drift analysis job
curl -X POST http://localhost:8000/api/v1/jobs \
  -H "content-type: application/json" \
  -d '{
    "job_type": "DRIFT_ANALYSIS",
    "input_refs": {
      "baseline_evaluation_id": "eval-a",
      "candidate_evaluation_id": "eval-b"
    },
    "idempotency_key": "job-key-1",
    "submitted_by": "smoke-test"
  }'

# List jobs
curl http://localhost:8000/api/v1/jobs

# Cancel a job
curl -X POST http://localhost:8000/api/v1/jobs/{job_id}/cancel

# Retry a failed job
curl -X POST http://localhost:8000/api/v1/jobs/{job_id}/retry