What is the current Cleanlist API version?

v2, served at https://api.cleanlist.ai/api/v2. It covers search, enrichment, lead lists, smart agents, sync and export, and it is what new integrations and the Cleanlist MCP use.

Is the legacy v1 API going away?

No. The legacy /api/v1/public surface is still supported with no announced sunset. It is frozen, so new endpoints land only on v2, but existing keys and clients keep working.

How do I migrate from v1 to v2?

For the shared endpoints, swap the base path /api/v1/public for /api/v2; auth, scopes, bodies and responses are the same. Move the five legacy v1-only endpoints to their v2 equivalents, such as GET /whoami instead of GET /auth/validate-key.

Do the legacy v1 endpoints check OAuth scopes?

No. The five legacy v1-only endpoints accept any valid key without a scope check. Every v2 endpoint checks one scope, so a key that works on v1 can still get 403 insufficient_scope on v2.

🔌

Audience: developers. API keys need a Pro or Enterprise plan (legacy Pro and Scale plans included) or an AppSumo Tier 5, 6 or 7 license, and they never work during a trial. 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 still supported. The v2 endpoints are also reachable under /api/v1/public, so migrating is usually just swapping the prefix. Only the five original single-file v1 endpoints stay v1-only.

API Versions & Migration

Cleanlist versions the 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	`/openapi-public.json` (opens in a new tab)

Both use a clapi_ Bearer key (or a Clerk session JWT). API key management is unversioned and stays at https://api.cleanlist.ai/api/v1/api-keys. The interactive docs at api.cleanlist.ai/docs (opens in a new tab) open on v2 and have a version switcher for v1.

What lives where

The v2 endpoints (workspace, people search, company search, lead lists, enrichment, smart agents, sync and export) are served by the same handlers under both /api/v2 and /api/v1/public.

If you already call these endpoints under /api/v1/public, they keep working. Migrate whenever you like by swapping the prefix.
The documented home for these endpoints is v2, which is what the rest of this API reference describes.
A few routes used only by the Cleanlist MCP exist on /api/v2 alone.

The five original single-file endpoints are v1-only and are documented in the Legacy API (v1) reference:

Legacy v1-only endpoint	What it does
`GET /api/v1/public/auth/validate-key`	Checks a key
`POST /api/v1/public/enrich/bulk`	Enriches 1 to 250 contacts, with an optional `webhook_url`
`GET /api/v1/public/enrich/status`	Polls a v1 enrichment (`workflow_id` or `task_id`)
`GET /api/v1/public/webhooks/deliveries`	Lists webhook delivery attempts
`POST /api/v1/public/folders`	Creates a lead-list folder

The legacy v1-only endpoints don't check OAuth scopes. Every v2 endpoint checks one, so a key that works on v1 can still get 403 insufficient_scope on v2. Call GET /whoami to see your granted scopes.

What changed

For the shared endpoints, nothing about behavior:

Same auth, OAuth scopes, request bodies, response envelope, errors and credit and quote model.
Same path after the prefix: /api/v1/public/whoami becomes /api/v2/whoami, and so on.
Different only in the prefix and the OpenAPI document that describes them.

How to migrate

Swap the base path. Change https://api.cleanlist.ai/api/v1/public to https://api.cleanlist.ai/api/v2 in your client config. Leave /api/v1/api-keys as it is.
Move the legacy v1-only endpoints you use to their v2 equivalents (table below).
Check your client's coverage. The served v2 spec does not include POST /credits/estimate, company search or sync, so a client generated from it can't run the quote flow on its own. Call those endpoints over plain HTTP, or use an official SDK, which includes credits_estimate. See OpenAPI Spec.
No rush. v1 stays supported, so you can migrate one endpoint at a time.

Legacy v1-only endpoints and their 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` (enriches a whole list; needs a `quote_id`)
`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`	None. v2 has no webhooks; use status polling
`POST /api/v1/public/folders`	None in the public v2 reference. To move a list into an existing folder, use `PATCH /api/v2/lead-lists/{list_id}` with `folder_id`

POST /api/v1/public/folders always runs the legacy handler, even though the v2 endpoints are also mounted under /api/v1/public.

Learn more

Introduction Quickstart