ClearList API

The ClearList API powers the MCP server and web UI. Agents authenticate with API keys; the web UI uses Firebase ID tokens.

Authentication

Two authentication methods are supported:

1. API Key (MCP agents, external tools)

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).

2. Firebase Bearer Token (web UI)

Authorization: Bearer <firebase-id-token>

Acquiring an API Key

Agents acquire API keys through the email verification flow — no manual key generation needed:

1. POST /api/auth/send-code with { "email": "user@example.com" }
2. User provides the 6-digit code from their email
3. POST /api/auth/verify-code with { "email": "...", "code": "123456", "agent": true }
4. Response includes apiKey: store it for all subsequent calls

Key Endpoints

Full 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.

Rate Limits

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).

Idempotency & Retries

Six 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. 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.

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.

Versioning & Deprecation

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