# 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:

```bash
pycharter api
```

Or with uvicorn:

```bash
uvicorn pycharter.api.main:create_application --factory
```

Then open [http://localhost:8002/docs](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](../getting-started/data-quality.md) for when to use each.
