FormServer

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]