Skip to content

REST API

The PyCharter REST API is documented and tryable in two places:

  • Swagger UI — When the API is running, open /docs (e.g. http://localhost:8002/docs) for interactive request/response documentation and "Try it out" for every endpoint.
  • In-app API Playground — From the PyCharter UI, open the API Playground (Documentation) page to call endpoints with a minimal request body editor.

Both use the same OpenAPI schema; Swagger is the single source of truth for endpoint paths, methods, request bodies, and responses.

Running the API

Start the API server:

pycharter api

Or with uvicorn:

uvicorn pycharter.api.main:create_application --factory

Then open http://localhost:8002/docs for the full REST API reference (default port 8002).

Quality

PyCharter exposes two kinds of quality checks; the API distinguishes them clearly.

  • Contract quality (row-based): POST /api/v1/quality/check — validate each record against a data contract; response includes quality_score, passed, violations. Use for record-level validation and metrics.
  • Pipeline quality (column/dataset-based): When running a pipeline (POST /api/v1/pipeline/run) with a canonical pipeline.yaml whose load step includes quality_checks, the response includes pipeline_quality_report (per-check results and overall passed). Use for run-level checks (row count, null rate, uniqueness, etc.).

Pipeline run history (GET /api/v1/pipeline/runs/legacy, etc.) returns:

  • contract_quality_score / contract_quality_passed — from contract quality checks (null if not run).
  • pipeline_quality_passed — from ETL pipeline quality_checks (null if not run).

See Data quality: contract vs pipeline for when to use each.

Observed field profiles (/api/v1/quality/profiles/runs/{run_id} and /api/v1/quality/profiles/fields/{contract_id}/{field_path}) report policy_gated: true when restriction provenance is true or unknown, or an observed population has 1–10 records or at most 10 distinct values. Exact counts, ranges, top values, and observation timestamps are then withheld as null or empty arrays. Existing rows without restriction provenance fail closed. Drift events with either source profile gated (or missing) withhold previous/current values and source profile IDs. Quality scores derived from gated profiles or drift events are null, with policy_gated: true.

Workers

PyCharter exposes worker queues through API control-plane endpoints. Workers share the same database as the API and should be started separately.

Validation worker:

  • POST /api/v1/quality/jobs — enqueue contract validation work.
  • GET /api/v1/quality/jobs — list validation jobs.
  • GET /api/v1/quality/jobs/stats — queue counts.
  • GET /api/v1/quality/jobs/health — queue health and counts.
  • GET /api/v1/quality/jobs/{job_id} — inspect a job.
  • POST /api/v1/quality/jobs/{job_id}/cancel — cancel pending/running work.

Pipeline worker:

  • POST /api/v1/pipeline/jobs — enqueue a durable pipeline execution job.
  • GET /api/v1/pipeline/jobs — list pipeline jobs.
  • GET /api/v1/pipeline/jobs/stats — pipeline queue counts.
  • POST /api/v1/pipeline/jobs/{run_id}/cancel — cancel queued/running pipeline work.
  • GET /api/v1/pipeline/runs/legacy and GET /api/v1/pipeline/runs/legacy/{run_id} — inspect durable pipeline lifecycle records.

Run pycharter worker --mode validation for validation jobs and pycharter worker --mode pipeline for pipeline jobs (or --mode all for both).

Vocabulary

The API exposes vocabulary endpoints under /api/v1/semantic/: concept schemes (GET /api/v1/semantic/schemes), concepts, relationships, semantic health, proposals, and configuration. Use Swagger UI at /docs for the full list.

Canonical product terms: Vocabulary (pillar), concept scheme, field binding. See Canonical Terminology.