Skip to content

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: false in the model definition.

How Forms Work ​

Public Form → Submit API → Submission Queue → Review → Content Entry
  1. You enable forms on a collection model and configure validation rules
  2. A public API endpoint is generated for that model
  3. External forms (your website, app, etc.) POST data to the endpoint
  4. Submissions land in a review queue with pending status
  5. A workspace owner or admin approves or rejects each submission
  6. Approving a submission creates a draft content entry

Enabling Forms on a Model ​

To enable forms for a collection model:

  1. Open the model in the content panel
  2. Open the model's Form tab (Form Settings)
  3. Turn on Form Enabled, then turn on Public so the form can be reached without authentication
  4. Under Exposed Fields, select the fields visitors can fill in (at least one is required)
  5. 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.

The Form tab: enable form submissions, mark the form public, and choose which fields are exposed

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}/submit

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

json
{
  "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:

json
{
  "success": true,
  "message": "Thank you! Your submission has been received."
}

On a validation failure, it returns the per-field errors:

json
{
  "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}/config

This 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

The Submissions tab: filter by status (All / Pending / Approved / Rejected / Spam), each submission showing a status badge

Submission Statuses ​

StatusDescription
PendingNew submission awaiting review
ApprovedReviewed and accepted
RejectedReviewed and declined
SpamMarked 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):

MethodPathBodyNotes
GET/api/workspaces/{workspaceId}/projects/{projectId}/forms/{modelId}/submissionsQuery: status, sort (newest or oldest), page, limitAlso open to members assigned to the project
PATCH.../submissions/{submissionId}{ "status": "approved" | "rejected" | "spam" }Approving creates the entry
DELETE.../submissions/{submissionId}NonePermanent
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:

  1. Approve the submission
  2. The submitted data is written to the model as a new draft entry, in the locale the submission was validated against
  3. 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:

SettingDescription
Form EnabledAccept form submissions for this collection
PublicMake the form reachable without authentication (shown once the form is enabled)
Exposed FieldsWhich fields are visible in the public form; other submitted fields are discarded
Honeypot FieldHidden field _hp; a submission that fills it gets a success response but is discarded
CAPTCHA ProtectionNone 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-ApproveAutomatically create a draft content entry when a form is submitted (Starter+)
Email NotificationsEmail the workspace owner and admins on each new submission (on by default)
Success MessageMessage shown after a successful submission
Webhook notificationTrigger a webhook on new submissions (see Webhooks)
Spam filterAI-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 ​

FeatureFreeStarterProEnterprise
Form-enabled models0115Unlimited
Submissions/month01003,000Unlimited
File upload in formsNoNoNoNo
CAPTCHANoYesYesYes
Auto-approveNoYesYesYes
Spam filterNoNoNoNo
Webhook notificationNoYesYesYes

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 ​

Released under the AGPL-3.0 License. Privacy