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

{
  "modelId": "contact-form",
  "fields": {
    "name": { "type": "string", "required": true },
    "email": { "type": "email", "required": true },
    "message": { "type": "text", "required": true },
    "newsletter": { "type": "boolean", "required": false }
  },
  "captcha": "turnstile",
  "successMessage": "Thank you for your submission!",
  "honeypotField": "_hp"
}

Only fields listed in the model's exposedFields configuration are returned. Internal fields are never exposed.

Example

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

CORS

The endpoint returns Access-Control-Allow-Origin: * headers for cross-origin embedding.

---

Submit Form

Submit data to a form-enabled model.

POST /api/forms/v1/:projectId/:modelId/submit

Request 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 sliding window (configurable, default 10/min)
Honeypot	Hidden field -- bots fill it, humans do not. Silent 200 rejection.
Captcha	Cloudflare Turnstile verification (Starter+ plan)
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

Plan Limits

Plan	Form Models	Submissions/Month
Free	0	0
Starter	1	100
Pro	15	3,000
Enterprise	Unlimited	Unlimited

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 authentication and workspace membership.

List Submissions

GET /api/workspaces/:workspaceId/projects/:projectId/forms/:modelId/submissions

Query Parameters

Parameter	Type	Default	Description
status	string	pending	Filter: pending, approved, rejected, spam
page	number	1	Page number
limit	number	20	Items per page
sort	string	newest	Sort: newest, oldest

Response

{
  "submissions": [
    {
      "id": "uuid",
      "model_id": "contact-form",
      "data": { "name": "John", "email": "[email protected]", "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

---

Delete Submission

DELETE /api/workspaces/:workspaceId/projects/:projectId/forms/:modelId/submissions/:submissionId

---

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)

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