Reference
This is the same reference agents read at /llms.txt. Interactive API docs: /api/docs.
# FormServer
> Hosted, server-rendered forms you create with a REST call or an MCP tool. No account needed to create.
> Formling-compatible API, plus live events (WebSocket / webhooks).
- API base: https://ai.commondesk.ai/api/v1
- Form pages: https://ai.commondesk.ai/f/<form_id>
- MCP (Streamable HTTP): https://ai.commondesk.ai/mcp
- OpenAPI: https://ai.commondesk.ai/api/openapi.json
## Auth
- Creating a form is anonymous (rate limited: 20/hour/IP).
- Everything else uses `Authorization: Bearer <admin_token>`, scoped to one form.
- The admin_token is returned ONCE at creation. Only its SHA-256 hash is stored; it cannot be recovered.
## Endpoints
POST /api/v1/forms create (no auth) -> form_id, form_url, responses_url, admin_token, claim_url, expires_at, events_ws, webhook_secret
GET /api/v1/forms/:id definition, settings, status, stats
PATCH /api/v1/forms/:id RFC 7396 merge patch; null removes a key; `fields` replaces the whole array
POST /api/v1/forms/:id/close stop accepting responses (idempotent)
DELETE /api/v1/forms/:id soft delete; purged after 24h (idempotent)
GET /api/v1/forms/:id/responses ?since=ISO&limit<=500&cursor=&format=json|csv
GET /api/v1/forms/:id/events [ext] ?since_seq=&type=&limit= activity log
WS /api/v1/forms/:id/events/ws [ext] ?t=<admin_token>&since=<seq> live events
GET /api/v1/forms/:id/webhooks/deliveries [ext] webhook delivery log
POST /api/v1/forms/:id/webhooks/test [ext] send a `ping` event
GET /f/:id public form (410 expired, closed page if closed/full, 404 missing)
POST /f/:id/submit submit JSON or form-encoded, keyed by field key
GET /f/:id/embed.js embed loader
GET /r/:id?t=<admin_token> human results page
GET /r/:id/export.csv?t=<admin_token> CSV download
## Create example
curl -X POST https://ai.commondesk.ai/api/v1/forms -H 'Content-Type: application/json' -d '{
"title": "Beta feedback",
"description": "Two minutes, promise.",
"fields": [
{"key": "name", "type": "short_text", "label": "Your name", "required": true},
{"key": "email", "type": "email", "label": "Email"},
{"key": "score", "type": "rating", "label": "Overall", "scale": 5, "anchors": {"low": "Poor", "high": "Great"}},
{"key": "areas", "type": "multi_select", "label": "What did you try?", "options": ["Editor", "Sharing", "Export"]},
{"key": "source", "type": "hidden", "label": "Source"}
],
"theme": {"colors": {"accent": "#6d28d9"}, "radius": "lg"},
"settings": {"submit_label": "Send", "success_message": "Thanks!", "max_responses": 500}
}'
## Fields
Every field: key (^[a-z][a-z0-9_]{0,63}$, unique), type, label; optional placeholder, required, help.
short_text min_length, max_length, pattern -> string
long_text max_length -> string
email -> string
phone -> string
url (http/https) -> string
number min, max, step, display: input|slider -> number
rating scale (2-10, default 5), anchors {low, high} -> integer 1..scale
select options, display: radio|dropdown -> string (option value)
multi_select options, min_selections, max_selections -> array of strings
yes_no -> boolean
checkbox (consent; label is the text) -> boolean
matrix rows[], columns[] -> {row: column}
ranking options -> ordered array of option values
date min, max (YYYY-MM-DD) -> "YYYY-MM-DD"
time -> "HH:MM" (24h)
address -> {line1, line2, city, region, postal_code, country}
statement body (display only; **bold**, *italic*, [link](https://...))
hidden default (prefill from URL) -> string
Options: strings, or {label, value?, image_url? (https)}.
URL prefill: /f/<id>?<key>=<value> (repeat key for multi_select). Invalid prefill values are ignored.
Form-encoded submission names: key, key[row] (matrix), key[part] (address), key[option]=position (ranking).
## Theme
theme: {font, colors: {bg, card, text, accent, muted, border}, radius: none|sm|md|lg|xl|full,
density: compact|comfortable|spacious, logo_url (https), layout: card|plain|split, custom_css}
custom_css (top level or in theme): sanitized and scoped to .fl-form. @import, non-https url(), expression()
are removed. Stable hooks: [data-part="root|header|title|description|card|field|label|help|error|input|choice|
submit|success|statement|matrix|ranking|rating|footer"], classes .field, .choice. Variables: --bg --card --text
--accent --muted --border --font --radius --density.
## Settings
submit_label (<=50), success_message (<=1000), max_responses (auto-closes), close_at (ISO-8601),
notify_webhook (URL; one JSON POST per submission), webhooks [ext]: [{url, events: ["form.submitted", ...] or ["*"]}]
## Events [ext]
form.viewed, form.started, form.submitted, form.rejected, form.closed, form.reopened, form.updated,
form.expired, form.deleted, ping.
Envelope: {id, seq, form_id, type, at, visit_id?, is_bot?, data}. `seq` increases per event; reconnect with since=<seq>.
Webhook headers: X-FS-Event, X-FS-Delivery, X-FS-Signature: t=<unix>,v1=<hex HMAC-SHA256(webhook_secret, "<t>.<body>")>.
Reliable webhooks retry at 30s, 2m, 10m, 1h, 6h, 24h. Delivery is at-least-once: dedupe on event id.
## Embedding
<script src="https://ai.commondesk.ai/f/<id>/embed.js"></script> inline, auto-resizing
<script src="https://ai.commondesk.ai/f/<id>/embed.js" data-mode="popup" data-button="Feedback"></script> popup
<iframe src="https://ai.commondesk.ai/f/<id>?embed=1"></iframe> direct
## Errors
{"error": {"code", "message", "field"?, "details"?, "docs"}}
validation_error 400 | unauthorized 401 | forbidden 403 | not_found 404 | form_closed 409 | form_expired 410 |
payload_too_large 413 (body > 100 KB) | rate_limited 429 | not_implemented 501 | email_unavailable 503 | internal_error 500
## Limits & lifecycle
Create: 20/hour/IP. Submit: 10/minute/IP/form. Unclaimed forms expire after 30 days; data purged 7 days later.
Deleted forms are purged after 24 hours.
## MCP tools
create_form(title, fields, description?, theme?, custom_css?, settings?)
get_form(form_id, admin_token)
update_form(form_id, admin_token, title?, description?, fields?, theme?, custom_css?, settings?)
get_responses(form_id, admin_token, since?, limit?, cursor?, format?)
close_form(form_id, admin_token)
delete_form(form_id, admin_token)
get_events(form_id, admin_token, since_seq?, type?, limit?) [ext]