OpenAPI Specification

Cleanlist's API is built with FastAPI, which auto-generates an OpenAPI 3.x document from the route definitions. Three URLs are available:

All three are kept in sync with the production API automatically.

Browsing interactively

Swagger UI

https://api.cleanlist.ai/docs (opens in a new tab)

Swagger UI lets you expand each endpoint, see request / response schemas, and "Try it out" against the live API. You'll need a clapi_ API key — paste it into the Authorize dialog (HTTP Bearer scheme) before calling any endpoint.

Redoc

https://api.cleanlist.ai/redoc (opens in a new tab)

Redoc renders a static, three-column reference that's easier to skim than Swagger when you're reading rather than experimenting.

Downloading the spec

curl https://api.cleanlist.ai/openapi.json -o cleanlist-openapi.json

The spec is unauthenticated — you can pull it without an API key.

Generating a client SDK

TypeScript (openapi-typescript)

npx openapi-typescript https://api.cleanlist.ai/openapi.json -o ./cleanlist-types.ts

Use the generated types with your preferred fetch library:

import type { paths } from "./cleanlist-types";
 
type EnrichBulkRequest =
  paths["/api/v1/public/enrich/bulk"]["post"]["requestBody"]["content"]["application/json"];
type EnrichBulkResponse =
  paths["/api/v1/public/enrich/bulk"]["post"]["responses"]["200"]["content"]["application/json"];

Python (openapi-python-client)

pipx install openapi-python-client
openapi-python-client generate --url https://api.cleanlist.ai/openapi.json

Other 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.json \
  -g <language> \
  -o ./cleanlist-client

See the OpenAPI Generator project (opens in a new tab) for the full list of supported languages.

Public API surface

Although the OpenAPI spec exposes Cleanlist's full backend, the stable, externally-supported surface for clapi_ keys is the /api/v1/public/* namespace. Treat anything outside /public/* as internal — it can change without notice and is gated to portal-issued tokens.

The supported public endpoints are:

API key management at /api/v1/api-keys/* is also supported but requires a Clerk session token, not a clapi_ key.

Versioning

The Public API is versioned via the URL prefix (/api/v1/...). Backwards-incompatible changes will be released under a new version prefix; the existing version will continue to work for a deprecation period announced via the portal (opens in a new tab) and email to API key holders.

Related

• Authentication
• Enrichment
• Errors