Skip to content
Wrenform

Docs / AI and API

REST API

Everything the dashboard does with forms, over HTTP with an API key, described in OpenAPI 3.1.

Last updated 2026-11-14View as Markdown
curl -X POST https://wrenform.com/api/v1/forms \
  -H "Authorization: Bearer $WRENFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Contact – example.com","recipients":["you@example.com"],"allowedOrigins":["https://example.com"],"framework":"html"}'

The base URL is https://wrenform.com/api/v1. The full description is at /api/v1/openapi.json (OpenAPI 3.1): load it into Postman, generate a client, or hand it to your AI tool. The API runs on the same rules as the dashboard, so limits, validation and the audit log are identical.

API keys

Create a key under Account → API & AI tools. It's shown once, starts with wf_live_, and goes in the Authorization: Bearer header. Keys stay on your server or in your CI secrets, never in browser code. The public form endpoint /f/<id> needs no key at all.

Each key has scopes: forms:read, forms:write, submissions:read, submissions:write, webhooks:write. A call without the right scope gets 403 insufficient_scope, naming the scope it needs. You can set an expiry date and revoke a key at any time. Billing, account deletion and key management stay in the dashboard.

Endpoints

Method Path What it does Scope
GET /me The account, plan and usage this key acts for any key
GET /forms List forms forms:read
POST /forms Create a form; returns its endpoint, an optional snippet and next steps forms:write
GET /forms/{id} Read a form's settings forms:read
PATCH /forms/{id} Change a form's settings forms:write
DELETE /forms/{id} Delete a form and all its submissions (confirmName must equal the name) forms:write
POST /forms/{id}/pause Stop accepting submissions forms:write
POST /forms/{id}/resume Accept submissions again forms:write
GET /forms/{id}/status The form's health, with plain-language issues and fixes forms:read
GET /forms/{id}/snippet Ready-to-paste code for a framework forms:read
POST /forms/{id}/test Send a test submission (10 per form per hour) forms:write
PUT /forms/{id}/recipients Set exactly which emails receive submissions; new ones must confirm by email forms:write
GET /forms/{id}/submissions List submissions, newest first submissions:read
GET /forms/{id}/submissions.csv CSV export (10 per account per hour) submissions:read
GET /forms/{id}/webhooks A form's webhook endpoints with recent deliveries forms:read
POST /forms/{id}/webhooks Add a webhook endpoint; the signing secret is returned once webhooks:write
GET /recipients The account's recipients and their forms forms:read
POST /recipients/{email}/resend Resend a recipient's confirmation email forms:write
GET /submissions/{sid} One submission submissions:read
DELETE /submissions/{sid} Delete a submission submissions:write
POST /submissions/{sid}/mark Move a submission between inbox and spam submissions:write
PATCH /webhooks/{wid} Change a webhook's URL, or enable or disable it webhooks:write
DELETE /webhooks/{wid} Delete a webhook endpoint webhooks:write
POST /webhooks/{wid}/rotate-secret New signing secret (shown once; the old one keeps signing for 24 hours) webhooks:write
POST /webhooks/{wid}/test Send a signed sample delivery webhooks:write
POST /deliveries/{did}/retry One more attempt for an abandoned delivery webhooks:write
POST /quick-forms No account: create a form with only the recipient's email. Nothing is forwarded until that address confirms; unconfirmed forms expire after 7 days. 200 with existing=true if one is already waiting. none (no account)
GET /quick-forms/{id} No account: a quick form's status only none (no account)

Paths with {id} take the form's public ID, the same one as in /f/<id>. Field names in request and response bodies are camelCase.

Responses and errors

Successful calls return JSON (201 for creation, 204 for deletion). Errors share one shape:

{ "ok": false, "error": { "code": "validation_failed", "message": "Check the highlighted fields.", "fields": { "recipients": "Not a valid email address." }, "docs": "https://wrenform.com/docs/errors#validation_failed" } }

The error reference lists every code. Each response carries an X-Request-Id header; quote it if you contact us.

Rate limits and retries

  • Calls are limited per key, and each response says where you stand in RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Over the limit, you get 429 with Retry-After.
  • Send an Idempotency-Key header on a POST to make it safe to retry: the same key within 24 hours returns the first response instead of acting twice.

Test it

  1. Create a key with the default scopes.
  2. Call GET /api/v1/me: you should see your account and plan.
  3. Create a form, then POST /api/v1/forms/<id>/test and GET /api/v1/forms/<id>/status. The test message arrives by email once a recipient has confirmed.

Common problems

  • 401 unauthenticated. The header is missing, the key was revoked, or it expired. Check it starts with Bearer wf_live_.
  • 403 insufficient_scope. Create a key with the scope named in the error.
  • 403 plan_limit. The plan's form or recipient limit is reached.
  • The test message doesn't arrive. New recipients must confirm by email first; status lists that as an issue.

Next steps

Something wrong or unclear on this page? Report a problem: write to hello [at] wrenform.com with the page address (/docs/api).