API reference

Authentication

Authorization: Bearer ce_live_your_key_here

Rate limits

Limits are enforced per API key on a rolling monthly window. When you exceed your limit, requests return 429 Too Many Requests until the window resets.

Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp) on every response.

{
  "ok": false,
  "error": "quota_exceeded",
  "message": "Monthly request quota exceeded."
}

Error codes

All errors follow a consistent JSON envelope with a machine-readable code and a human-readable message.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Monthly request limit reached. Resets 2026-07-01T00:00:00Z.",
    "status": 429
  }
}

MCP integration

Common Elements exposes an MCP (Model Context Protocol) server that lets AI agents — including Claude — call the API directly as tools without writing HTTP client code.

{
  "mcpServers": {
    "common-elements": {
      "command": "npx",
      "args": ["-y", "@common-elements/mcp"],
      "env": {
        "CE_API_KEY": "ce_live_your_key_here"
      }
    }
  }
}

Once connected, your agent can call tools like compliance_scan and association_lookup conversationally, with structured responses automatically parsed. MCP server documentation and changelog live at commonelements.com/developers/mcp.

Command-line tool

The ce CLI wraps this API for terminal and scripting use. It reads your key from CE_API_KEY and shares the same scopes and quota as every other surface.

npm install -g @common-elements/cli
export CE_API_KEY=ce_live_your_key_here

ce associations search --state FL --query "sunset" --limit 5
ce statutes search "reserve study" --state FL
ce export associations --state FL --out fl-associations.csv

Full command and option reference lives at commonelements.com/developers/cli.

FAQ

What happens when I get a 429 response?

A 429 means either your monthly request quota is used up or you sent requests faster than the max requests/second for your tier. The body carries a JSON error envelope with "quota_exceeded" as the error code. For quota exhaustion, wait for the reset at the start of the next calendar month or upgrade your tier from your API keys settings; there is no automatic overage charge. For a per-second burst, back off and retry with an increasing delay (for example 1s, then 2s, then 4s) instead of retrying immediately.

How do API keys map to scopes?

Every key carries a list of scopes set when it is created, one per data domain: associations, compliance, risk, licenses, professionals, vendors, and statutes. A request is only authorized if the key carries the scope the endpoint requires; a key without the "vendors" scope gets a 403 from vendor endpoints even with a valid, unexpired key.

What does "read-only" vs "full-access" mean for a scope?

Every scope on a Developer API key is read and analysis access to the public dataset: no Developer API key can write to your account or to anyone else, regardless of scope. The "all" scope is full access, unlocking every endpoint across every domain. Narrower scopes like "associations" or "compliance" unlock only endpoints in that one domain, so a key you hand to a teammate or embed in a single-purpose integration can be scoped down to just what it needs.

Where can I see my usage?

Your API keys settings page shows live usage for every key you hold, as requests used against requests included for the current calendar month. It is the fastest way to check how close a key is to its limit before you hit a 429.