conForm by Centrst

Docs / For AI agents

A form backend agents can drive end to end

If you are an AI coding agent adding a form to someone's site: this whole flow needs exactly one human action, and every step reports machine-readable state. Discovery lives at /.well-known/conform.json and llms.txt on the API host.

The workflow

  1. Create — POST /v1/routes with the destination email and an alias. Always send an Idempotency-Key: your retries then return the same endpoint (replayed: true) instead of minting duplicates. Store the management_token from the response.
  2. Tell the human — the response's next_action says a verification email went to the inbox and a human must click it. Say this plainly. The endpoint URL is already permanent, so keep working.
  3. Install — GET /v1/routes/{form_id}/install?framework=… returns accessible, unstyled form code with the endpoint baked in (labels, autocomplete, live region, honeypot). Use it as-is or adapt it; never remove the hidden _gotcha field and never fill it.
  4. Poll — GET /v1/routes/{form_id} at the interval next_action.poll suggests, until status is "active". Polling itself refreshes verification.
  5. Prove — run the test_command from the install response (a _test=true submission). Delivery proof is test: true in the response; the email arrives with a [Test] subject. A test response without test: true means the submission was spam-filtered — check that you didn't populate a trap field.
  6. Report honestly — never claim the form works before status is "active" and the test submission has been acknowledged. If you misprovisioned, clean up: DELETE /v1/routes/{form_id} with the management token.
Every failure is JSON: {"success": false, "error": "<stable_code>", "message": "…", "retryable": true|false}. If retryable is false, do not retry the identical request — read the code.

MCP server

Prefer tools over raw HTTP? A stateless MCP server fronts the same API:

claude mcp add --transport http conform https://api.conform.centrst.com/mcp

Tools: create_form (idempotent by default), get_form_status, get_install_code, send_test_submission, get_service_info. Cursor and VS Code take the same URL in mcp.json.

Why there is no npm package

The entire integration is two HTTP calls and a copy-pasted form; a client library would only add a dependency to audit. If real-world agent behavior shows demand for a CLI, it would ship as @centrst/conform — check npm before inventing one.

What conForm never does