← 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/ provides 24 tools that map to these API routes.

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

Versioning

The API is currently unversioned. All routes are at /api/. Breaking changes will be communicated through the MCP server card version field.

Current API version: 0.3.0