> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platinur.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Control-plane API documentation generated from FastAPI OpenAPI.

The API reference is generated from the Platinur control-plane FastAPI app. The published OpenAPI file includes `/api/*` routes only, so UI routes, login pages, and form compatibility endpoints are not presented as public API documentation.

Every workspace binds one ClickHouse analytical database. Connect workspaces bind a
customer-owned service; Managed workspaces receive a dedicated service selected from the
server-controlled capacity profiles during paid signup. Managed provisioning is a platform
lifecycle operation, not a customer-facing portal API, so those internal routes are intentionally
excluded from the published schema.

## Authentication

Portal APIs authenticate with the **session cookie** issued at login — the same session the
portal uses. Two special-purpose token headers exist outside the portal session: worker ↔
control-plane calls carry a per-workspace shared token, and the platform's usage endpoint
(`GET /api/platform/usage`) requires `X-Platinur-Platform-Token`.

## Key endpoints

* `GET /api/environments`, `POST /api/environments/activate` — environment state.
* `GET /api/status?env=staging&view=…` — the status summary that powers the portal.
* `GET|POST /api/integrations`, `POST /api/integrations/{id}/test|scan|run` — sources.
* `GET /api/model-catalog?env=…`, `GET /api/model-lineage?env=…` — the dbt catalog.
* `POST /api/assistant/tasks` — assistant requests; `POST /api/dbt/runs`; `POST /api/evidence/rebuild?env=…`.
* `GET /api/promotions/current`, `POST /api/promotions/release-plan`,
  `POST /api/promotions/release-preflight`, `POST /api/promotions/release-copy`,
  `POST /api/promotions/publish`, and `GET /api/promotions/publish/status` — resolve a
  dependency-closed selection, validate the release and reconstructed Staging states, then publish
  it using `release_plan_id`, `title`, and optional `description`. The older
  `GET /api/promotions/release-preview` cutoff endpoint is compatibility-only.
* `POST /api/account/delete` — asynchronous Owner-only permanent workspace deletion with exact
  workspace-name acknowledgment and current-password verification.

<Warning>
  `POST /api/promotions/deploy-prod` is legacy and returns **410 Gone** — do not build on it.
  Production releases go through Publish (`/api/promotions/publish`).
</Warning>

<Warning>
  `POST /api/account/reset` and `POST /api/models/reset` are retired and return **410 Gone**.
  V1 starts over through permanent account deletion, not partial state resets or warehouse unbinding.
</Warning>

## Regenerate the spec

From the repository root:

```bash theme={null}
uv run --with-requirements apps/control-plane/requirements.txt python scripts/platinur/export-docs-openapi.py
```

This writes the control-plane OpenAPI document to `docs-site/api/openapi.json`.

## Local preview

```bash theme={null}
cd docs-site
mint dev
```

Mintlify will render this overview page and the generated Control Plane API section from the OpenAPI file.