# 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/ - 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 `, 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=&since= 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= human results page GET /r/:id/export.csv?t= 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/?= (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=. Webhook headers: X-FS-Event, X-FS-Delivery, X-FS-Signature: t=,v1=.")>. Reliable webhooks retry at 30s, 2m, 10m, 1h, 6h, 24h. Delivery is at-least-once: dedupe on event id. ## Embedding inline, auto-resizing popup 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]