REST API - PyCharter
Description: Data Contract Management, ETL Pipelines, and Quality Assurance for Python

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.

## 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 an ETL pipeline (`POST /api/v1/etl/run`) with `quality_checks` in the load config, 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/runs`, 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.