The REST API

Everything a teammate can do to a lead on the board, an agent can do over /api/v1, because the UI and the API call the same service layer. This article covers the contracts. The complete machine-readable reference lives at /llms.txt on the app, written for pasting straight into an agent's context.

Keys and auth

Mint an API key in Settings → API keys (owner or admin). It's shown once at creation and stored hashed. Every request sends it as Authorization: Bearer lr_…. The key's team is the only tenancy signal: whatever a request body claims, it can only ever touch the key's own team.

Name keys after the agent that holds them. The name is what appears on lead timelines, and "clay-enricher" reads better in an audit than "key-2".

Rate limits

Requests are limited per key on fixed one-minute windows, with the ceiling set by your plan tier. Over the limit you get a 429 with a Retry-After header telling you exactly how long to wait.

The contracts that matter

• Adding leads is idempotent. POST /api/v1/leads with the same pipeline and contact email converges on one contact and one card. A repeat call returns created: false instead of duplicating, so you can retry freely.
• Stages are keys, not UUIDs. Move a card with "contacted", never a stage id.
• Custom fields are typed. Read GET /api/v1/schema first. Writes that don't match the schema fail with a structured invalid_field error rather than storing junk.
• Errors are structured. Every failure is { "error": { "code", "message", "details?" } }, with codes an agent can branch on.
• Everything is attributed. Every mutation lands on the lead's timeline under the key's name.

What the API can do

Add leads, list and search contacts, enrich them, move cards through stages, read timelines, draft and send email (through your verified domain, with all guardrails), and poll for changes with updatedSince cursors. What it can't do: create pipelines, stages, or field definitions. Configuration stays human-only.

If your agent speaks MCP instead, the same operations are available as tools with no HTTP glue to write.