Docs / AI and API
REST API
Everything the dashboard does with forms, over HTTP with an API key, described in OpenAPI 3.1.
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-RemainingandRateLimit-Reset. Over the limit, you get429withRetry-After. - Send an
Idempotency-Keyheader 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
- Create a key with the default scopes.
- Call
GET /api/v1/me: you should see your account and plan. - Create a form, then
POST /api/v1/forms/<id>/testandGET /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 withBearer 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;
statuslists that as an issue.
Next steps
- MCP server: the same actions as tools for AI coding agents.
- Forms without an account:
POST /api/v1/quick-formsneeds no key. - Webhooks: receive submissions on your server as they arrive.