← clearlist.me

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 24 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

Write endpoints that create records (POST /api/items, POST /api/items/bulk-upload) accept an Idempotency-Keyheader (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 — retries never create duplicate items or re-upload photos. 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.

Other write endpoints (POST /api/pages/publish, POST /api/payments/checkout-link, PUTupdates) are naturally idempotent — repeating the same request converges to the same state, so they are safe to retry without a key.

Versioning & Deprecation

Every API response carries an X-API-Version header (currently 0.3, the major.minor of the OpenAPI specversion). 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