API reference

Endpoints and credentials

Every website posts to the same URL. The key tells 1DB which website it is, and formSlug which form.

The API is not served from www.1-db.com; only the MCP server is. In code, use ${DB_API_ENDPOINT}/v1/leads with these variables:

DB_API_ENDPOINT=https://gallant-goshawk-513.convex.site
DB_API_KEY=1db_...        # 1db_ followed by 32 hex characters
DB_FORM_SLUG=acme-contact # the real slug, from the dashboard, get_website or 1db init

• Ingest key (1db_ + 32 hex characters): one per website. It can only create leads, so it is safe in browser code. A server route is still better: it can pass on the visitor's IP and browser and retry on failure. If the browser posts directly, the public prefix is fine: NEXT_PUBLIC_DB_API_KEY, VITE_DB_API_KEY.
• Agent token (1db_at_…): manages an organization. Only a person can create one, in Settings → API keys → Agent tokens or by approving npx @1db/cli setup in the browser. It never goes in a project.

Form slugs are unique across all of 1DB and look like acme-contact (website slug, then the form). Always use the real slug, never a guess like contact.

Send a lead

curl -X POST https://gallant-goshawk-513.convex.site/v1/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DB_API_KEY" \
  -d '{"formSlug":"acme-contact","email":"jane@example.com","name":"Jane Doe","message":"Hello"}'

The body is formSlug plus the form's fields, flat. A stored lead answers:

200 {"success":true,"leadId":"…","duplicate":false}

duplicate: true means this key already sent this submission_id (v2 only): nothing new was stored or sent on.

Errors from /v1/leads

Every error has a readable error string and a stable code, and a hint saying what to change. Show error to visitors; branch on code.

{"error":"Check the highlighted fields","code":"INVALID_FIELDS",
 "fields":{"email":"Enter a valid email address"},"field":"email","details":"Enter a valid email address"}

fields maps each bad field to a message; field and details repeat the first one. 429s also carry retryAfter (seconds) and a Retry-After header.

Lead contract

v1 (the default) stores the body as sent. v2 checks every field and names each bad one. Opt in per request with X-1DB-Contract: 2.

Headers

The two client headers work with either contract. Without them, 1DB uses the connection's own IP and user agent, so every visitor of a server route shares one rate-limit bucket.

v2 fields

Use these names; common aliases such as zip or firstName still work. Fields not listed here are stored as sent.

Retries

On a 429 or 500, retry with the same submission_id. If the first attempt was stored, the retry answers duplicate: true and nothing is sent twice. The same id on another key is a different lead. v1 never dedupes.

Rate limits

• /v1/leads: 100 leads a minute per ingest key (bursts to 200), and 50 a minute per visitor IP.
• /v1/agent/*: 60 requests a minute per agent token (bursts to 120).

Agent API

Send the agent token as Authorization: Bearer 1db_at_…. GET /v1/agent lists every route. The routes, MCP tools and CLI commands are in AI agents, MCP and CLI.

curl https://gallant-goshawk-513.convex.site/v1/agent/websites/health?website=acme.com \
  -H "Authorization: Bearer $ONEDB_TOKEN"

Errors are an object under error:

{"error":{"code":"forbidden","message":"This token is missing the routing scope","hint":"…"}}

Embed script

For a site where you can't write code, one script tag renders a form built from the form's fields in 1DB and posts it to /v1/leads:

<script src="https://gallant-goshawk-513.convex.site/v1/embed.js?key=1db_...&form=acme-contact" async></script>
<button data-1db>Contact us</button>   <!-- opens the popup -->
<div data-1db-inline></div>           <!-- or renders it here, in inline mode -->

The mode (popup, slide-in or inline), title, colors and success message come from the form's embed settings in the dashboard. The key is in the page, which is fine for an ingest key.