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: v2 (/api/v2) is the current API — use it for all new work. v1 (/api/v1/public) is legacy but fully supported, with no planned sunset. The expanded ~30-endpoint surface is served on both prefixes, so migrating is usually just swapping /api/v1/public for /api/v2. Only the original 5-endpoint single-file Public API stays v1-only.
API Versions & Migration
Cleanlist versions the Public API through the URL prefix. There are two live surfaces.
The two surfaces
| Surface | Base URL | Status | OpenAPI spec |
|---|---|---|---|
| API v2 | https://api.cleanlist.ai/api/v2 | Current — use for all new integrations | /openapi-public-v2.json (opens in a new tab) |
| Legacy v1 | https://api.cleanlist.ai/api/v1/public | Supported, frozen, no planned sunset | /openapi-public.json (opens in a new tab) |
Authentication is the same on both: a clapi_ Bearer token (or Clerk JWT), with the same OAuth scopes. API-key management is unversioned and stays at https://api.cleanlist.ai/api/v1/api-keys.
What lives where
The full, modern surface — workspace, lead lists, people/company search, enrichment, smart agents, sync, and export (~30 endpoints) — is dual-mounted: the exact same handlers serve under both /api/v1/public and /api/v2. Nothing was moved or removed.
- If you already call these endpoints under
/api/v1/public, they keep working untouched. Migrate whenever you like by swapping the prefix. - The canonical, documented home for these endpoints is now v2 — that's what the rest of this API reference describes.
The one thing that is v1-only is the original single-file Public API — a small, older set of endpoints (key validation, bulk enrich + status, webhook delivery history). These are not part of v2; their modern equivalents live on v2 under cleaner names (see the mapping below). They are documented in the Legacy API (v1) reference.
What changed
Nothing about behavior. For the shared endpoints, v2 is the same handlers behind a new, longer-lived prefix:
- Same auth, OAuth scopes, request bodies, response envelope, and credit/quote model.
- Same path after the prefix —
/api/v1/public/whoamibecomes/api/v2/whoami, and so on. - Different only in the prefix and the OpenAPI document you generate clients from.
v2 exists so the Cleanlist MCP and generated clients (@cleanlist-ai/client) have a stable, versioned target that won't shift as the platform evolves.
How to migrate
- Swap the base path. Change
https://api.cleanlist.ai/api/v1/publictohttps://api.cleanlist.ai/api/v2in your client config. Leave/api/v1/api-keysas-is. - Regenerate typed clients against the v2 spec at
/openapi-public-v2.json(opens in a new tab) (see OpenAPI Spec). - Update the 4 legacy single-file endpoints, if you use them, to their v2 equivalents below.
- No rush. v1 stays supported with no sunset — you can migrate endpoint by endpoint.
Legacy single-file endpoints → v2 equivalents
| Legacy (v1-only) | v2 equivalent |
|---|---|
GET /api/v1/public/auth/validate-key | GET /api/v2/whoami |
POST /api/v1/public/enrich/bulk | POST /api/v2/enrichment/bulk |
GET /api/v1/public/enrich/status?workflow_id={id} (or ?task_id={id}) | GET /api/v2/enrichment/status/{workflow_id} |
GET /api/v1/public/webhooks/deliveries | Remains on v1 — v2 consumers use status polling |