Publish a form
publish_formCreate or update live Formhaus Cloud forms from validated definitions, returning submission endpoints, hosted links, and embed snippets so users can collect form data without a backend.
Instructions
Call this after validate_definition passes, to put the form live on Formhaus Cloud: without form_id it creates a new form, with form_id it publishes a new version of that form. Returns form_id, version, endpoint (POST URL for submissions), hosted_url, embed_snippet, react_snippet, dashboard_url and warnings. Without an account key (fh_live_...) it also returns claim_url and expires_at, and on the first call without any key agent_key (fh_agent_...) and agent_key_notice. Call it when the user needs a working form (contact, waitlist, signup, survey, feedback) without writing a backend. A new version keeps form_id, endpoint and links.
Minimal valid definition: {"id":"waitlist","title":"Join the waitlist","submit":{"label":"Join"},"fields":[{"key":"email","type":"email","label":"Email","validation":{"required":true}}]}
Rules:
Top level needs id, title and submit {"label": "..."}.
Each field needs key, type and label. Use "fields" for one step, or "steps" (each with id, title and fields) for several, never both.
Types: text, email, phone, number, textarea, select, multiselect, radio, checkbox, switch, date, datetime. password, file, autocomplete, optionsFrom and custom types are refused.
select, multiselect and radio need "options": [{"value": "a", "label": "A"}].
"validation": {"required": true, "minLength": 2, "maxLength": 200, "min": 0, "max": 10, "pattern": "^[a-z]+$"}.
At most 32 KB and 100 fields.
JSON Schema: https://formhaus.dev/schema/form-definition.json
Keys: an agent key only reaches the forms it created, at most 3 unclaimed per key. Never put agent_key in browser code or in git. This server reads FORMHAUS_API_KEY from its own environment, so it cannot save the key: add it to the env of the formhaus MCP server in the MCP client config and restart the server. Unclaimed forms expire after 7 days, accept 100 submissions and ignore redirect_url. Give claim_url to the user. When an error ends with "Ask the user to upgrade at ", give that URL to the user. On error, fix every listed path and call again.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| No | Only for a new form published without an account key: the user's email. Formhaus emails them claim_url (at most one email per address per hour, no form content). Ignored with a warning otherwise. | ||
| form_id | No | The 10-character form_id of an existing form, from publish_form or list_forms, to publish a new version of it. Requires an account key (fh_live_...) of the form's account or the agent key (fh_agent_...) that created the form. Omit to create a new form. | |
| definition | Yes | Formhaus form definition as a JSON object or a JSON string. JSON Schema: https://formhaus.dev/schema/form-definition.json. Top level: id, title, submit { label }, and fields (one step) or steps [{ id, title, fields }]. Field: { key, type, label, validation?, options?, show?, showAny? }. Rules go inside "validation": { required, minLength, maxLength, min, max, pattern, matchField }. Condition: { field, eq | neq | in | notIn | notEmpty | gt | gte | lt | lte } with exactly one operator, on a field of the same or an earlier step. Optional: lang, messages and labels catalogs, and i18n objects that map texts to translation keys. | |
| redirect_url | No | http(s) URL the hosted page and embed open after a successful submission instead of the success message. Empty string removes it. Ignored with a warning for unclaimed forms. | |
| success_message | No | Text shown after a successful submission on the hosted page and embed. Up to 500 characters. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Machine-readable error code or message when the call failed. | |
| notice | No | ||
| form_id | No | ||
| message | No |