# REST API

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

Last updated 2026-11-14. Web version: https://wrenform.com/docs/api

```sh
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"}'
```

```js
const res = await fetch("https://wrenform.com/api/v1/forms", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.WRENFORM_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Contact – example.com", recipients: ["you@example.com"] }),
});
const { form, snippet, nextSteps } = await res.json();
```

The base URL is `https://wrenform.com/api/v1`. The full description is at
[/api/v1/openapi.json](https://wrenform.com/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:

```json
{ "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](/docs/errors) 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

- [MCP server](/docs/mcp): the same actions as tools for AI coding agents.
- [Forms without an account](/docs/quick-forms): `POST /api/v1/quick-forms` needs no key.
- [Webhooks](/docs/webhooks): receive submissions on your server as they arrive.
