Forms API
Public API
The form config and submit endpoints are part of Studio's public, versioned API (/api/forms/v1/), designed to be called directly from your site. Submission management (review, approve, convert) is part of the internal application API.
Studio supports public form submissions that map to collection models. Forms can be embedded on external websites to collect data that flows into the content pipeline.
Public Endpoints
These endpoints require no authentication and are designed for external embedding.
Get Form Configuration
Get the public schema for a form-enabled model.
GET /api/forms/v1/:projectId/:modelId/configResponse
{
"modelId": "contact-form",
"locale": "en",
"fields": {
"name": { "type": "string", "required": true },
"email": { "type": "email", "required": true },
"message": { "type": "text", "required": true },
"newsletter": { "type": "boolean", "required": false }
},
"captcha": "turnstile",
"captchaSiteKey": "0x4AAAA...",
"successMessage": "Thank you for your submission!",
"honeypotField": "_hp"
}Only fields listed in the model's exposedFields configuration are returned (with requiredOverrides applied). Internal fields are never exposed.
| Key | Meaning |
|---|---|
locale | The project's default locale; submissions are validated and written in it |
captcha | "turnstile" when the form has captcha configured and the plan includes it, otherwise null |
captchaSiteKey | Turnstile widget key for your page, or null when captcha is off or the operator has not set NUXT_PUBLIC_TURNSTILE_SITE_KEY |
honeypotField | "_hp" when the honeypot is enabled, otherwise null |
The config endpoint is limited to 30 requests per minute per IP (429 forms.rate_limited). Other errors: 404 when the project, model or form is missing, disabled, or not public; 403 forms.upgrade when the plan does not include forms or the model is beyond the plan's form-model limit.
Example
curl https://studio.example.com/api/forms/v1/{projectId}/{modelId}/configCORS
Both public endpoints return Access-Control-Allow-Origin: * headers for cross-origin embedding, and the OPTIONS preflight is answered with 204.
Submit Form
Submit data to a form-enabled model.
POST /api/forms/v1/:projectId/:modelId/submitRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | Form field values |
captchaToken | string | Conditional | Turnstile token (when captcha is configured) |
_hp | string | No | Honeypot field (must be empty -- bots fill it) |
Response
Success:
{
"success": true,
"message": "Thank you for your submission!"
}Validation Error:
{
"success": false,
"errors": [
{ "field": "email", "message": "email must be a valid email" }
]
}Security Features
| Feature | Description |
|---|---|
| Rate limiting | Per IP and model, sliding one-minute window (default 10/min, overridable per form with limits.rateLimitPerIp). 429 forms.rate_limited. |
| Honeypot | Hidden field -- bots fill it, humans do not. Silent 200 rejection. |
| Captcha | Cloudflare Turnstile verification (Starter+ plan). A missing or invalid token returns HTTP 200 with { "success": false, "errors": [{ "field": "captcha", ... }] }. |
| HTML sanitization | All string values stripped of HTML tags, JS patterns, entities |
| Field filtering | Only exposed fields are accepted; others are silently dropped |
| Validation | Schema-based validation against model field definitions |
| Monthly limits | Atomic check + insert prevents race conditions. An optional per-form cap (limits.maxPerMonth) returns 429 forms.model_monthly_limit; the plan limit returns 429 forms.monthly_limit. |
Plan Limits
| Plan | Form Models | Submissions/Month |
|---|---|---|
| Free | 0 | 0 |
| Starter | 1 | 100 |
| Pro | 15 | 3,000 |
| Enterprise | Unlimited | Unlimited |
Notifications
Unless the form sets notifications: false, Studio emails the workspace owners and admins on every submission (requires the forms.notifications plan feature). Plans with forms.webhook_notification also dispatch a form.submitted webhook event.
Auto-Approve
When configured and the plan supports forms.auto_approve, submissions are automatically converted to content entries and merged into the repository.
Admin Endpoints
These endpoints require a session. Listing is open to workspace owners and admins and to members assigned to the project, and needs a plan with forms (403 forms.upgrade). Update, delete and bulk are limited to workspace owners and admins.
List Submissions
GET /api/workspaces/:workspaceId/projects/:projectId/forms/:modelId/submissionsQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | (all) | Filter: pending, approved, rejected, spam. Omit to return every status. |
page | number | 1 | Page number |
limit | number | 50 | Items per page (max 100) |
sort | string | newest | Sort: newest, oldest |
Response
{
"submissions": [
{
"id": "uuid",
"model_id": "contact-form",
"data": { "name": "John", "email": "john@example.com", "message": "Hello" },
"status": "pending",
"source_ip": "192.168.1.1",
"created_at": "2026-01-01T00:00:00Z"
}
],
"total": 15
}Update Submission Status
PATCH /api/workspaces/:workspaceId/projects/:projectId/forms/:modelId/submissions/:submissionId| Field | Type | Required | Description |
|---|---|---|---|
status | 'approved' | 'rejected' | 'spam' | Yes | New status |
approved creates a draft content entry in Git and returns the submission with its entry_id; rejected and spam return the updated row. Errors: 400 forms.invalid_status, 404 forms.submission_not_found.
Delete Submission
DELETE /api/workspaces/:workspaceId/projects/:projectId/forms/:modelId/submissions/:submissionIdReturns { "deleted": true }; 404 forms.submission_not_found when the submission is not in this model.
Bulk Update
POST /api/workspaces/:workspaceId/projects/:projectId/forms/:modelId/submissions/bulk| Field | Type | Required | Description |
|---|---|---|---|
action | 'approve' | 'reject' | 'spam' | 'delete' | Yes | Imperative action to apply to each submission |
submissionIds | string[] | Yes | Submission IDs to act on (max 50 per request) |
Over 50 IDs returns 400 forms.bulk_limit. delete and approve return { "results": [{ "id", "success", "entryId?", "error?" }], "updated": 3 }; reject and spam return { "updated": 3 }.
The field is action (imperative), not status. approve creates a content entry in Git for each submission; delete permanently removes them (with a GDPR audit log entry).
Related Pages
- Chat API -- agent tools for submission management
- Field Types -- form field validation rules