Forms
Contentrain Studio lets you accept public form submissions for your collection models. Visitors submit data through a public API endpoint, and your team reviews, approves, or rejects submissions before they become content entries.
Availability
Core forms — public submit/config endpoints, the submission review queue, CAPTCHA, and auto-approve — work in every deployment, including the self-hosted Community Edition (the forms.enabled feature is not Enterprise-gated). A few extras are gated:
- Webhook notifications on submission — Enterprise Edition (
forms.webhook_notification). - File upload in forms — Enterprise Edition and on the roadmap (not yet available).
- Spam filter — Enterprise Edition and on the roadmap (not yet available).
- Email notifications — the workspace owner and admins get an email for each new submission (Starter and above, and Community; needs an email provider). Turn it off per model with
form.notifications: falsein the model definition.
How Forms Work
Public Form → Submit API → Submission Queue → Review → Content Entry- You enable forms on a collection model and configure validation rules
- A public API endpoint is generated for that model
- External forms (your website, app, etc.) POST data to the endpoint
- Submissions land in a review queue with
pendingstatus - A workspace owner or admin approves or rejects each submission
- Approving a submission creates a draft content entry
Enabling Forms on a Model
To enable forms for a collection model:
- Open the model in the content panel
- Open the model's Form tab (Form Settings)
- Turn on Form Enabled, then turn on Public so the form can be reached without authentication
- Under Exposed Fields, select the fields visitors can fill in (at least one is required)
- Adjust the Security and Behavior settings (see Form Configuration) and save
The public endpoints answer with 404 unless the form is both enabled and public.

TIP
Only collection models support form submissions. Singletons, documents, and dictionaries cannot accept external submissions.
Public Form API
Once enabled, each model gets a public submission endpoint:
POST /api/forms/v1/{projectId}/{modelId}/submitRequest Format
The endpoint reads only data (the submitted field values), an optional captchaToken, and the honeypot field _hp. Submissions are validated and stored in the project's default locale — any locale field in the body is ignored.
{
"data": {
"name": "Jane Smith",
"email": "jane@example.com",
"message": "I'd like to learn more about your product."
}
}Response
On success, the endpoint returns your configured Success Message, or the default message shown below:
{
"success": true,
"message": "Thank you! Your submission has been received."
}On a validation failure, it returns the per-field errors:
{
"success": false,
"errors": [
{ "field": "email", "message": "email must be a valid email" }
]
}Configuration Endpoint
You can fetch the form configuration (field definitions, validation rules) from the public API:
GET /api/forms/v1/{projectId}/{modelId}/configThis is useful for dynamically building forms on your frontend based on the model schema. The config endpoint is rate-limited per IP.
Submission Management
Viewing Submissions
Select a form-enabled model and open its Submissions tab. The list shows each submission with a status badge and a total count. Open a submission to see its data and metadata:
- Submission data
- Source IP address
- User agent
- Referrer URL
- Locale
- Created at

Submission Statuses
| Status | Description |
|---|---|
| Pending | New submission awaiting review |
| Approved | Reviewed and accepted |
| Rejected | Reviewed and declined |
| Spam | Marked as spam (API only; the Studio UI has no spam action) |
Reviewing a Submission
Moderating submissions requires workspace owner or admin. Other roles with project access can view the list but see no actions.
Click any submission to open the detail modal, review the submitted data, then choose an action (pending submissions only):
- Approve — Create a draft content entry from the submission
- Reject — Decline the submission
- Delete — Permanently remove the submission
The list also has quick Approve and Reject buttons on each pending row.
Filtering
Use the status tabs (All, Pending, Approved, Rejected, Spam) to filter the list.
Moderation API
The same actions are available through the workspace API for automation (owner/admin only):
| Method | Path | Body | Notes |
|---|---|---|---|
GET | /api/workspaces/{workspaceId}/projects/{projectId}/forms/{modelId}/submissions | Query: status, sort (newest or oldest), page, limit | Also open to members assigned to the project |
PATCH | .../submissions/{submissionId} | { "status": "approved" | "rejected" | "spam" } | Approving creates the entry |
DELETE | .../submissions/{submissionId} | None | Permanent |
POST | .../submissions/bulk | { "action": "approve" | "reject" | "spam" | "delete", "submissionIds": [...] } | Not available in the UI |
Converting Submissions to Content
Approving a submission always creates a content entry:
- Approve the submission
- The submitted data is written to the model as a new draft entry, in the locale the submission was validated against
- The content branch is merged immediately, so the entry appears in the collection right away
Approval does not go through the review workflow, and the entry is not published. If the merge fails or the data no longer validates, the approval fails with a 409 or 422 error and the submission stays pending so you can retry.
The submission's entry_id field is populated with the newly created content entry ID, linking the submission to its resulting content.
Form Configuration
The form configuration section lets you control:
| Setting | Description |
|---|---|
| Form Enabled | Accept form submissions for this collection |
| Public | Make the form reachable without authentication (shown once the form is enabled) |
| Exposed Fields | Which fields are visible in the public form; other submitted fields are discarded |
| Honeypot Field | Hidden field _hp; a submission that fills it gets a success response but is discarded |
| CAPTCHA Protection | None or Cloudflare Turnstile (send the result as captchaToken) |
| Rate Limit (per IP/min) | Maximum submissions per IP address per minute for this form |
| Monthly Cap (this form) | Stop accepting submissions on this form after this many in a month; leave empty to use only the plan limit |
| Auto-Approve | Automatically create a draft content entry when a form is submitted (Starter+) |
| Email Notifications | Email the workspace owner and admins on each new submission (on by default) |
| Success Message | Message shown after a successful submission |
| Webhook notification | Trigger a webhook on new submissions (see Webhooks) |
| Spam filter | AI-powered spam detection (Enterprise Edition, roadmap — not yet available) |
Security
Form submissions include metadata for security review:
- Source IP — The IP address of the submitter
- User Agent — The browser or client identifier
- Referrer — The referring page URL
WARNING
The public form API is rate-limited per IP address and form (adjustable under Rate Limit). Excess requests receive 429.
Plan Limits
| Feature | Free | Starter | Pro | Enterprise |
|---|---|---|---|---|
| Form-enabled models | 0 | 1 | 15 | Unlimited |
| Submissions/month | 0 | 100 | 3,000 | Unlimited |
| File upload in forms | No | No | No | No |
| CAPTCHA | No | Yes | Yes | Yes |
| Auto-approve | No | Yes | Yes | Yes |
| Spam filter | No | No | No | No |
| Webhook notification | No | Yes | Yes | Yes |
The CAPTCHA and Auto-approve columns reflect features that ship today. Webhook notification requires the Enterprise Edition. File upload and the Spam filter are Enterprise-Edition roadmap features and are not yet available.
Next Steps
- Content Models — Set up models for form submissions
- Webhooks — Get notified when forms are submitted
- Content Editing — Manage converted form entries