The ClearList API powers the MCP server and web UI. Agents authenticate with API keys or as OAuth 2.1 clients; the web UI uses Firebase ID tokens.
Two authentication methods are supported:
Send your API key in the X-ClearList-API-Key header:
X-ClearList-API-Key: cl_your_api_key_here
API keys use the format cl_<64-hex> (67 characters total). The same key is also accepted as Authorization: Bearer cl_<64-hex>.
OAuth 2.1 clients (authorization code with PKCE S256) receive an access token in the same format and send it the same way. OAuth grants carry the scopes read and/or write: a grant without write gets 403 on POST, PUT, PATCH and DELETE. API keys from the email flow below are always full access.
Authorization: Bearer <firebase-id-token>
Agents acquire API keys through the email verification flow — no manual key generation needed:
POST /api/auth/send-code with { "email": "user@example.com" }POST /api/auth/verify-code with { "email": "...", "code": "123456", "agent": true }apiKey: store it for all subsequent callsFull endpoint documentation is available in the OpenAPI spec. The MCP server at mcp-server/ (also on npm as @clearlist/mcp-server) provides 28 tools that map to these API routes — connect via the npm package/stdio, or directly at the hosted /api/mcp streamable-http endpoint, no install required.
API routes are served on Vercel's serverless infrastructure with standard rate limits. AI-powered endpoints (listing creation, bulk upload) have extended timeouts (up to 120 seconds).
Eight write endpoints accept an Idempotency-Key header (1–255 chars; a UUID works well). If a request fails mid-flight and you retry with the same key within 24 hours, the stored first response is replayed instead of re-executing. Replayed responses carry an Idempotency-Replayed: true header. A duplicate that arrives while the first request is still running gets 409 idempotency_conflict: wait a few seconds and retry. A key names one request: reusing it on the same endpoint with a different path, body, or kind of credential (the seller's own session, an API key, or a connected OAuth app) gets 422 idempotency_key_reuse instead of the first request's stored answer. Only successful (2xx) responses are stored; error responses always re-execute, so a corrected request is never stuck behind a stale error.
POST /api/items: a retry would create a second item.POST /api/items/bulk-upload: a retry would re-upload every photo.POST /api/items/bulk-generate: a replay returns the original job_id, so you poll the generation already running instead of paying for a second one.POST /api/items/[id]/restore: without a key, a retry after a timeout reports 409 "This item is not deleted" for a restore that actually succeeded. On the one endpoint that recovers a destroyed listing, that is the worst thing it could tell you.POST /api/pages/publish: a retry short-circuits on the slug that already exists, so it will not finish a half-written page.POST /api/conversations/[id]: a reply emails the buyer, so a retried 500 sends them the same message twice. This one is not idempotent in any sense; always send a key.POST /api/conversations/[id]/address: a retry after a lost response would otherwise report the spent confirmation token as a failure, for an address the buyer already received.POST /api/pages/extend: a retry replays the first renewal instead of running a second one against your daily renewal limit.Do not assume anything else is retry-safe because it looks like an update. PUT /api/items/[id] is not on the list and is not naturally idempotent: a blind retry can land on top of a concurrent edit, and it returns 409 both when the item changed since you read it and when the item has been deleted. Check the OpenAPI spec for the Idempotency-Key parameter on the specific operation you are calling.
Every API response carries an X-API-Version header (currently 0.3, the major.minor of the OpenAPI spec version). Within a version, changes are additive only — new fields and endpoints may appear, existing ones never change shape or disappear.
Breaking changes ship as a new version. The old behavior is kept through a deprecation window of at least 90 days, announced via Deprecation and Sunset response headers (RFC 8594) on affected endpoints, plus the developer portal and the MCP server card version field.
Current API version: 0.3