Forms API
The Forms API has two public endpoints that a site calls with a public API key, one to read a form’s definition and one to submit it, plus administrative endpoints for managing forms and reading form entries. A form is a content model of kind form; each submission is stored as a form entry. For concepts and console steps, see the Forms guide.
All paths are under https://your-instance.plenarycms.io/api/v1. Replace your-instance.plenarycms.io with your instance’s host, and read keys from environment variables (PLENARY_PUBLIC_KEY below).
Endpoint summary
Section titled “Endpoint summary”| Method | Path | Auth | Purpose |
|---|---|---|---|
GET |
/forms/{form_key} |
Public key | Read a form definition |
POST |
/forms/{form_key}/entries |
Any API key or user | Submit a form |
GET |
/forms/{form_key}/entries |
content:form_entries:read |
List form entries |
GET |
/forms/{form_key}/entries/{entry_id} |
content:form_entries:read |
Get a form entry |
PUT |
/forms/{form_key}/entries/{entry_id}/status |
content:form_entries:update |
Set a form entry’s status |
PUT |
/forms/{form_key}/entries/status?site_key= |
content:form_entries:update |
Set status in bulk |
DELETE |
/forms/{form_key}/entries/{entry_id} |
content:form_entries:delete |
Delete a form entry |
POST |
/forms/{form_key}/entries/delete?site_key= |
content:form_entries:delete |
Delete in bulk |
GET |
/forms/entry-counts |
Any user or key; narrowed per form | Entry counts |
GET, PUT |
/forms/{form_id}/notifications |
content:forms:update |
Email notifications |
Form management (GET /forms, POST /forms, PUT /forms/{form_id}, DELETE /forms/{form_id}) and form webhooks are listed under Administrative endpoints.
Authentication
Section titled “Authentication”| Credential | Header | May use |
|---|---|---|
| Public API key | X-API-KEY: pln_pub_… (or ?api_key=) |
Read an active form’s definition and submit it. Nothing else on this page. |
| Private API key | X-API-KEY: pln_prv_… |
Anything its content:* grants allow, including reading form entries. |
| User session | Authorization: Bearer <access_token> |
Anything the user’s roles allow. |
A public key has no permissions, so every administrative endpoint answers it with 403 permission_denied. A request with no credential gets 401 authentication_required. If the key has allowed origins set, a browser request from another origin gets 403 api_key_origin_not_allowed; if it has a per-minute rate limit, exceeding it gets 429 rate_limited. See Authentication.
Read a form definition
Section titled “Read a form definition”GET /api/v1/forms/{form_key}Returns the render-safe definition of an active form: its fields, their types, settings, UI hints, and validation rules, plus the anti-spam token ts. This is the one model-shaped resource a public key may read.
| Parameter | In | Description |
|---|---|---|
form_key |
path | The form’s key, for example contact. |
A public key sees the form only when the form is active and belongs to the key’s site. Otherwise the response is 404 form_not_found, the same as for a key that names no form or names a content model.
curl https://your-instance.plenarycms.io/api/v1/forms/contact \ -H "X-API-KEY: $PLENARY_PUBLIC_KEY"import { createClient } from "@plenary/client";
const plenary = createClient({ baseUrl: "https://your-instance.plenarycms.io", apiKey: process.env.PLENARY_PUBLIC_KEY ?? "", siteKey: "default", locale: "en-us",});
const form = await plenary.getForm("contact"); // PublicFormDefinitionResponse 200
Section titled “Response 200”{ "key": "contact", "name": "Contact", "fields": [ { "key": "name", "name": "Name", "type": "text", "required": true, "ui": { "placeholder": "Jane Doe" }, "validation": { "max_length": 80 } }, { "key": "email", "name": "Email", "type": "email", "required": true, "ui": { "placeholder": "jane@example.com" } }, { "key": "topic", "name": "Topic", "type": "select", "required": false, "settings": { "options": [ { "label": "Sales", "value": "sales" }, { "label": "Support", "value": "support" } ] } }, { "key": "message", "name": "Message", "type": "text", "required": true, "ui": { "control": "textarea" }, "validation": { "min_length": 10, "max_length": 2000 } } ], "ts": "MTc5MTM2NDM2Ni5KTjE0RTNQQzVlQlZybDBNRGgtZDYzTlMwWWtyRVpmY2hMU3Y0elNTT3pV"}| Field | Type | Description |
|---|---|---|
key |
string | The form key. |
name |
string | The form’s display name. |
fields |
array | One object per field, in the form’s order. |
fields[].key |
string | The key to use in submitted data. |
fields[].name |
string | The field’s label. |
fields[].type |
string | One of the form field types. |
fields[].required |
boolean | Whether a value must be submitted. |
fields[].settings |
object | Present when non-empty. What a renderer needs: options for select/multi_select, item settings for list, sub-fields under object for an object field. |
fields[].ui |
object | Present when non-empty. Hints such as control (input, textarea; select, radio, segmented), placeholder, help_text, autocomplete. |
fields[].validation |
object | Present when non-empty. The field’s rules, for example min_length, max_length, regex on text. Use them for client-side checks. |
ts |
string | The anti-spam time token. Opaque; send it back unchanged. Only present for public keys. |
The definition never includes ids, timestamps, the form’s site_key or active flag, or any field marked private or hidden.
A user session or private key with content:forms:read or content:form_entries:read gets the full administrative model document from this path instead, without ts.
Submit a form
Section titled “Submit a form”POST /api/v1/forms/{form_key}/entries?site_key={site_key}Content-Type: application/jsonValidates the values against the form’s fields and stores a form entry. Any API key may call it, including a public key; this is the only write a public key can make.
Parameters
Section titled “Parameters”| Parameter | In | Required | Description |
|---|---|---|---|
form_key |
path | yes | The form’s key. |
site_key |
query | see below | The site the entry belongs to. |
data |
body | yes | Field values keyed by field key. |
website |
body | no | Honeypot value. Non-empty marks the entry as spam. |
ts |
body | no | The ts token from the definition, unchanged. |
Choosing the site.
| Caller | site_key |
|---|---|
| Public key | Optional; the key’s site is used. Another site is 403 permission_denied. |
| Any other credential | Required. |
A form belongs to exactly one site and accepts entries on that site only; for any other site the response is 404 form_not_found. @plenary/client always sends the client’s siteKey, or opts.siteKey when given.
Request body
Section titled “Request body”{ "data": { "name": "Jane Doe", "email": "jane@example.com", "topic": "sales", "message": "Hello, I would like a demo." }, "website": "", "ts": "MTc5MTM2NDM2Ni5KTjE0RTNQQzVlQlZybDBNRGgtZDYzTlMwWWtyRVpmY2hMU3Y0elNTT3pV"}data holds native JSON values: a string for text, email, url, phone, date, time, datetime, color, and select; a number for number; a boolean for boolean; an array of strings for multi_select and tags; an object for object and json; an array for list. phone values must be E.164 (+13035550142) and color values #rrggbb or #rrggbbaa.
An empty string or null for email, url, phone, select, number, date, time, datetime, or color means “not answered”, so a form can post every input it renders. For text, an empty string is a value; omit the key instead. The request body is capped at 256 KiB.
curl -X POST "https://your-instance.plenarycms.io/api/v1/forms/contact/entries?site_key=default" \ -H "X-API-KEY: $PLENARY_PUBLIC_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": { "name": "Jane Doe", "email": "jane@example.com", "topic": "sales", "message": "Hello, I would like a demo." }, "website": "", "ts": "TOKEN_FROM_GET_FORM" }'const result = await plenary.submitForm( "contact", { name: "Jane Doe", email: "jane@example.com", topic: "sales", message: "Hello, I would like a demo.", }, { website: "", ts: form.ts },);submitForm(formKey, data, opts?) takes opts.siteKey, opts.website, and opts.ts, and sends website and ts as top-level siblings of data.
Response 202
Section titled “Response 202”{ "ok": true, "id": "5659896a-9736-4834-9a1c-b460cdee2349" }id is the new form entry’s id. The response is 202 Accepted because email notifications and webhooks run after it is sent. A submission caught by the spam checks gets exactly this response too.
Anti-spam fields
Section titled “Anti-spam fields”| Field | Rule |
|---|---|
website |
Render a text input named website, hidden off-screen (not display: none alone), and send its value. If it is non-empty, the entry is stored with status spam. Absent or empty: no effect. It must be top-level, never inside data, because a form may define its own website field. |
ts |
Send the ts string from the definition read. If the submit arrives less than 3 seconds after that read, or the token’s signature does not verify, the entry is stored with status spam. Absent: no time check runs. The token has no maximum age. |
Spam entries still go through full field validation, so an invalid spam submission gets the normal 422. They never trigger email notifications or form.submitted webhooks. Because the token records the definition read, render form pages per request rather than caching them.
Rate limit
Section titled “Rate limit”Submits are limited to 10 per minute per form per client IP. Exceeding it returns 429 form_entry_rate_limited. The client IP is the leftmost X-Forwarded-For address, or the connection address when the header is absent, so a server that submits on visitors’ behalf shares one budget. The limit is disabled when the instance runs with dev_mode: true. A per-key rate limit configured on the API key applies in addition.
Submit errors
Section titled “Submit errors”Every error body has this shape:
{ "error": { "code": "entry_field_required", "vars": { "field": "message" } } }@plenary/client throws PlenaryValidationError for 400 and 422, PlenaryNotFoundError for 404, PlenaryForbiddenError for 403, and PlenaryError for anything else. Each carries status, code, and vars.
| Status | Code | Vars | Meaning |
|---|---|---|---|
| 400 | invalid_json_body |
The body is not valid JSON. | |
| 401 | authentication_required |
No API key or session. | |
| 403 | permission_denied |
site_key names a site other than the public key’s own. |
|
| 404 | form_not_found |
Unknown key, inactive form, a content model’s key, or a form that belongs to another site. | |
| 409 | entry_field_value_taken |
field |
A field marked unique already holds this value in another entry. |
| 413 | form_entry_body_too_large |
The body exceeds 256 KiB. | |
| 422 | entry_site_key_required |
No site could be determined; pass site_key. |
|
| 429 | form_entry_rate_limited |
The per-form, per-IP limit was exceeded. |
Field validation errors are all 422 and stop at the first failing field:
| Code | Vars | Meaning |
|---|---|---|
entry_field_unknown |
field |
data has a key the form does not define. |
entry_field_required |
field |
A required field is missing. |
entry_field_required_nonempty |
field |
A required field is present but empty. |
entry_field_value_required |
field |
A field was sent with no value. |
entry_field_schema_invalid |
field, path, message |
The value has the wrong JSON type or shape for the field type, for example a phone that is not E.164. |
entry_field_rule_violation |
field, name, rule, plus the rule’s own value (for example min_length) |
A validation rule failed. rule is min_length, max_length, regex, or a phone or color rule. |
entry_object_field_invalid |
field |
An object value is not an object. |
entry_subfield_* |
field, sub_field, … |
The same checks one level inside an object field. |
entry_list_item_schema_invalid |
field, index, path, message |
A list item has the wrong shape. |
entry_list_subfield_* |
field, index, sub_field, … |
The same checks inside an object item of a list. |
Real responses from a form with a required message field (min_length: 10):
{"error":{"code":"entry_field_required","vars":{"field":"message"}}}{"error":{"code":"entry_field_rule_violation","vars":{"field":"message","min_length":10,"name":"Message","rule":"min_length"}}}{"error":{"code":"entry_field_required_nonempty","vars":{"field":"name"}}}{"error":{"code":"entry_field_unknown","vars":{"field":"phone"}}}Validation rules are enforced for text (min_length, max_length, regex), phone, and color.
The form entry object
Section titled “The form entry object”The administrative endpoints return form entries in this shape:
{ "id": "5659896a-9736-4834-9a1c-b460cdee2349", "form_key": "contact", "site_key": "default", "status": "new", "created_at": "2026-10-07T09:13:47.239Z", "updated_at": "2026-10-07T09:13:47.239Z", "data": { "email": "jane@example.com", "message": "Hello, I would like a demo.", "name": "Jane Doe", "topic": "sales" }, "source": { "ip": "203.0.113.7", "user_agent": "Mozilla/5.0", "referer": "https://example.com/contact" }}| Field | Description |
|---|---|
id |
The form entry id (UUID). |
form_key |
The form it belongs to. |
site_key |
The site it was submitted to. |
status |
Triage status: new, read, archived, or spam. |
created_at |
When it was submitted. There is no separate submitted_at. |
updated_at |
When its status last changed. |
data |
The stored values, keyed by field key. |
source |
Provenance captured from the submit request: ip (client IP), user_agent (truncated to 512 characters), referer (truncated to 1024). A key is omitted when the request did not carry it. source is shown in the console but cannot be filtered on. |
List form entries
Section titled “List form entries”GET /api/v1/forms/{form_key}/entriesRequires content:form_entries:read on the form. Returns an array of form entry objects.
| Query parameter | Description |
|---|---|
site_key |
Only entries on this site. Omit to list every site the caller may read. |
where:{field}[op] |
Filter, for example where:status=spam or where:data.email=jane@example.com. Filterable fields: status, created_at, updated_at, and any scalar field as data.<key>. |
filters |
A JSON filter tree, for $or/$and. Mutually exclusive with where:. |
sort:{field} |
asc or desc, for example sort:created_at=desc. |
limit |
Default 100, maximum 500. |
offset |
Rows to skip. |
count |
true adds the total match count in the X-Total-Count response header. |
The query syntax is the same as the Content API. include and exclude are refused with 400 form_entry_query_selection_unsupported.
curl -i "https://your-instance.plenarycms.io/api/v1/forms/contact/entries?site_key=default&where:status=new&sort:created_at=desc&limit=50&count=true" \ -H "X-API-KEY: $PLENARY_PRIVATE_KEY"@plenary/client has no method for this endpoint; call it with fetch and a private key or session that holds the capability.
Get a form entry
Section titled “Get a form entry”GET /api/v1/forms/{form_key}/entries/{entry_id}Requires content:form_entries:read. Returns one form entry object, 404 entry_not_found if the id names no entry of this form, or 400 entry_id_invalid if it is not a UUID.
Set a form entry’s status
Section titled “Set a form entry’s status”PUT /api/v1/forms/{form_key}/entries/{entry_id}/statusContent-Type: application/json
{ "status": "read" }Requires content:form_entries:update. status must be new, read, archived, or spam; anything else returns 422 form_entry_status_invalid. Returns the updated form entry. The submitted values cannot be changed; status is the only mutable field.
Delete a form entry
Section titled “Delete a form entry”DELETE /api/v1/forms/{form_key}/entries/{entry_id}Requires content:form_entries:delete. Returns {"id": "…", "deleted": true}, or 404 entry_not_found. Deletion is permanent.
Bulk status and bulk delete
Section titled “Bulk status and bulk delete”PUT /api/v1/forms/{form_key}/entries/status?site_key=defaultContent-Type: application/json
{ "ids": ["5659896a-9736-4834-9a1c-b460cdee2349"], "status": "archived" }Returns {"updated": 1}.
POST /api/v1/forms/{form_key}/entries/delete?site_key=defaultContent-Type: application/json
{ "ids": ["5659896a-9736-4834-9a1c-b460cdee2349"] }Returns {"deleted": 1}.
Both require site_key (422 entry_site_key_required without it) and the matching capability for that site. An empty ids returns 422 form_entry_ids_required. If any id names no entry of this form on this site, the whole request fails with 422 form_entry_bulk_not_found and nothing changes.
Entry counts
Section titled “Entry counts”GET /api/v1/forms/entry-counts?site_key=defaultReturns per-form totals for the forms whose entries the caller may read. site_key is optional.
{ "counts": [ { "form_id": "4caadbec-0240-4782-8701-643f9fff4af9", "form_key": "contact", "total": 5, "new": 3, "read": 0, "archived": 0, "spam": 2 } ]}Email notifications
Section titled “Email notifications”GET /api/v1/forms/{form_id}/notificationsPUT /api/v1/forms/{form_id}/notificationsRequires content:forms:update on the form. form_id is the form’s UUID, not its key. The PUT body has the same shape as the GET response without email_configured:
{ "notifications": { "email": { "enabled": true, "recipients": [ { "type": "user", "id": "6063d721-3d78-4f06-b983-0aed7300408b" }, { "type": "role", "key": "editor" } ], "include_data": false } }, "email_configured": true}| Field | Description |
|---|---|
enabled |
Send an email for each new non-spam form entry. |
recipients[] |
{"type": "user", "id": "<user id>"} or {"type": "role", "key": "<role key>"}. A role resolves at send time to every active user of the role with an email address. |
include_data |
false sends a link-only email. true also lists every submitted value. |
email_configured |
Read-only. false when no email provider is configured, in which case nothing is sent. |
Unknown recipients are rejected with 422 notification_recipient_user_unknown, notification_recipient_role_unknown, or notification_recipient_invalid (each with vars.index). Saving records a revision of the form.
Administrative endpoints
Section titled “Administrative endpoints”These manage forms themselves. All refuse public keys.
| Method | Path | Capability | Notes |
|---|---|---|---|
GET |
/forms |
content:forms:read or content:form_entries:read |
Lists forms. |
POST |
/forms |
content:forms:create |
Creates a form; returns 201 with the model document. Same body as POST /models (key, name_singular, site_key, fields, active); the kind is always form. Send "active": true, or the form is created inactive. |
GET |
/forms/{form_id or form_key} |
content:forms:read or content:form_entries:read |
The full model document, including webhooks with secrets masked. |
PUT |
/forms/{form_id} |
content:forms:update |
Updates the form. |
DELETE |
/forms/{form_id}?key_confirm={form_key} |
content:forms:delete |
Refused while the form has entries unless &purge_content=1 is added. |
GET |
/forms/{form_id}/yaml |
content:forms:read |
The form as YAML. See Model YAML. |
GET |
/forms/{form_id}/revisions |
content:revisions:read |
The form’s change history. |
PUT |
/forms/{form_id}/webhooks |
content:webhooks:manage |
Replaces the form’s webhooks. See Webhooks. |
GET |
/forms/{form_id}/webhooks/health |
content:webhooks:manage |
Latest delivery per webhook. |
GET |
/forms/{form_id}/webhooks/{webhook_id}/deliveries |
content:webhooks:manage |
The 50 most recent deliveries. |
A form is invisible on /models and a content model is invisible on /forms: each returns 404 on the other surface. Creating or updating a form with a disallowed setting returns 422 with one of model_form_field_type_not_allowed (vars.index, vars.type), model_form_field_localized_not_allowed, model_form_name_plural_not_allowed, model_form_title_field_not_allowed, model_form_preview_not_allowed, model_form_private_not_allowed, model_form_change_notes_not_allowed, or model_form_always_published_not_allowed.