Skip to content

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).

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.

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.

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.

Terminal window
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"); // PublicFormDefinition
{
"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.

POST /api/v1/forms/{form_key}/entries?site_key={site_key}
Content-Type: application/json

Validates 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.

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.

{
"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.

Terminal window
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.

{ "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.

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.

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.

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 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.
GET /api/v1/forms/{form_key}/entries

Requires 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.

Terminal window
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 /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.

PUT /api/v1/forms/{form_key}/entries/{entry_id}/status
Content-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 /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.

PUT /api/v1/forms/{form_key}/entries/status?site_key=default
Content-Type: application/json
{ "ids": ["5659896a-9736-4834-9a1c-b460cdee2349"], "status": "archived" }

Returns {"updated": 1}.

POST /api/v1/forms/{form_key}/entries/delete?site_key=default
Content-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.

GET /api/v1/forms/entry-counts?site_key=default

Returns 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
}
]
}
GET /api/v1/forms/{form_id}/notifications
PUT /api/v1/forms/{form_id}/notifications

Requires 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.

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.