Audience: developers. The public API requires a Pro plan or above (self-serve) or an AppSumo Tier 5+ license. Support agent: confirm the user's plan grants API access before giving API advice.
TL;DR: The current v2 spec is served as raw JSON at /openapi-public-v2.json (opens in a new tab) — pull it to generate a typed client. The hosted Swagger UI /docs (opens in a new tab) and Redoc /redoc (opens in a new tab) currently render the legacy v1 surface (/openapi-public.json), not v2. There is no hosted interactive UI for v2 yet; load the raw v2 JSON into your own viewer to explore it.
OpenAPI Specification
Cleanlist's API is built with FastAPI, which auto-generates an OpenAPI 3.x document. The v2 spec is filtered to the supported public surface — only /api/v2/* endpoints appear.
| URL | Format | Surface | Best for |
|---|---|---|---|
https://api.cleanlist.ai/openapi-public-v2.json | Raw JSON | v2 (current) | Code generation against the current API |
https://api.cleanlist.ai/openapi-public.json | Raw JSON | v1 (legacy) | The frozen legacy surface |
https://api.cleanlist.ai/docs | Swagger UI | v1 (legacy) | Interactive exploration of the legacy surface |
https://api.cleanlist.ai/redoc | Redoc | v1 (legacy) | Clean read-only reference for the legacy surface |
Heads up: the hosted Swagger (/docs) and Redoc (/redoc) UIs currently render the legacy v1 spec (/openapi-public.json) — there is no hosted interactive UI for v2 yet. To explore or build against the current v2 surface, pull the raw JSON from /openapi-public-v2.json (opens in a new tab) and load it into a local viewer (e.g. Swagger Editor) or a code generator. All specs stay in sync with production automatically. See API Versions & Migration.
Browsing interactively
The hosted UIs below currently render the legacy v1 surface. For the current v2 surface, see Exploring v2 instead.
Swagger UI — /docs (opens in a new tab) (v1)
Swagger UI lets you expand each endpoint, see request/response schemas, and "Try it out" against the live API. Paste your clapi_ key into the Authorize dialog (HTTP Bearer scheme) before calling anything. Note this renders the v1 (/api/v1/public) surface.
Redoc — /redoc (opens in a new tab) (v1)
Redoc renders a static three-column reference that's easier to skim than Swagger when reading rather than experimenting. It also renders the v1 surface.
Exploring v2
There is no hosted Swagger/Redoc UI for v2 yet. To browse the current v2 surface interactively, pull the raw spec and open it in a local viewer:
curl https://api.cleanlist.ai/openapi-public-v2.json -o cleanlist-v2.json
# then open cleanlist-v2.json in Swagger Editor (https://editor.swagger.io) or RedoclyDownloading the spec
curl https://api.cleanlist.ai/openapi-public-v2.json -o cleanlist-openapi.jsonThe spec is unauthenticated — you can pull it without an API key.
Generating a client SDK
TypeScript
npx openapi-typescript https://api.cleanlist.ai/openapi-public-v2.json -o ./cleanlist-types.tsPython
pipx install openapi-python-client
openapi-python-client generate --url https://api.cleanlist.ai/openapi-public-v2.jsonOther languages
# Java, Go, Ruby, Rust, C#, PHP, Swift, Kotlin, etc.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i https://api.cleanlist.ai/openapi-public-v2.json \
-g <language> \
-o ./cleanlist-clientSee the OpenAPI Generator project (opens in a new tab) for the full language list.
Versioning
The Public API is versioned via the URL prefix. /api/v2 is the current surface and what this spec describes; the older Legacy API (v1) at /api/v1/public is still supported but frozen. Generate clients against the v2 spec above. For the full version story and migration steps, see API Versions & Migration.