Skip to content

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/config

Response ​

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

KeyMeaning
localeThe 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
captchaSiteKeyTurnstile 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 ​

bash
curl https://studio.example.com/api/forms/v1/{projectId}/{modelId}/config

CORS ​

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

Request Body ​

FieldTypeRequiredDescription
dataobjectYesForm field values
captchaTokenstringConditionalTurnstile token (when captcha is configured)
_hpstringNoHoneypot field (must be empty -- bots fill it)

Response ​

Success:

json
{
  "success": true,
  "message": "Thank you for your submission!"
}

Validation Error:

json
{
  "success": false,
  "errors": [
    { "field": "email", "message": "email must be a valid email" }
  ]
}

Security Features ​

FeatureDescription
Rate limitingPer IP and model, sliding one-minute window (default 10/min, overridable per form with limits.rateLimitPerIp). 429 forms.rate_limited.
HoneypotHidden field -- bots fill it, humans do not. Silent 200 rejection.
CaptchaCloudflare Turnstile verification (Starter+ plan). A missing or invalid token returns HTTP 200 with { "success": false, "errors": [{ "field": "captcha", ... }] }.
HTML sanitizationAll string values stripped of HTML tags, JS patterns, entities
Field filteringOnly exposed fields are accepted; others are silently dropped
ValidationSchema-based validation against model field definitions
Monthly limitsAtomic 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 ​

PlanForm ModelsSubmissions/Month
Free00
Starter1100
Pro153,000
EnterpriseUnlimitedUnlimited

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/submissions

Query Parameters ​

ParameterTypeDefaultDescription
statusstring(all)Filter: pending, approved, rejected, spam. Omit to return every status.
pagenumber1Page number
limitnumber50Items per page (max 100)
sortstringnewestSort: newest, oldest

Response ​

json
{
  "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
FieldTypeRequiredDescription
status'approved' | 'rejected' | 'spam'YesNew 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/:submissionId

Returns { "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
FieldTypeRequiredDescription
action'approve' | 'reject' | 'spam' | 'delete'YesImperative action to apply to each submission
submissionIdsstring[]YesSubmission 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).

Released under the AGPL-3.0 License. Privacy