Update a draft form
update_form
Update a form that belongs to the authenticated organization. Requires an org API key or OAuth sign-in with the forms:write scope. Same checks as PATCH /api/v1/forms/{id}: title, settings, and fields. A field entry with an id updates that field. A field entry with no id inserts a field. op add also inserts a field, and that row must not include an id. The server assigns the id. Required on an insert: label and type (an existing field type). Optional on an insert: helpText (at most 2000 characters), required, options, and stageId. stageId defaults to the Interest stage, or the first stage. New fields are appended. order on an insert is ignored. On an existing field, optional order is an integer greater than or equal to 0 and sets that field's position. An order already used by another field on this version is refused (409 'A field already occupies this order on the form version.'). op remove, or removeFieldIds, deletes fields on the current draft. Answers and consents are matched by field key on every version of the form, not by the draft field id. A field that has answers or consents cannot be removed (409 'This field has answers or consents and cannot be removed.'). Changing a field key is refused when that field's current key, or the new key, already has answers or consents on this form (409 'A field key that already has answers or consents cannot be changed.'). At most 20 fields can be added and 20 removed in one call. A form can hold at most 140 fields. Title is at most 200 characters, a field label at most 500, and stored settings JSON at most 32 KB. A field id that is not on the current draft returns 409 'This field id is not on the current draft.' Re-read the form with get_form and retry with the current field ids. A malformed field id is rejected. Top-level settings keys whose names start with __ are ignored, and the stored editor stamp is kept. A lower editorSeq does not overwrite a newer save. A form that belongs to another organization is not found. MCP, an org API key, and OAuth share a limit of 60 updates per organization per hour. Adding or removing fields uses that same limit. A website session is not counted. Returns the updated draft, any new field ids, and editorUrl (/app/forms/{formId}). Does not publish the form.
Schema valid · SHA-256 1ded8c42f2f1…
View input schema
{
"type": "object",
"properties": {
"formId": {
"type": "string",
"description": "Form id in the authenticated organization."
},
"title": {
"type": "string",
"maxLength": 200,
"description": "Form title, at most 200 characters. On a published form this is held as a draft until publish."
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "description, indexable, confirmationMessage, and notifyEmails are type-checked. Other client keys are stored. Top-level keys whose names start with __ are ignored, including editorSession and editorSeq inside settings."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"properties": {
"order": {
"type": "integer",
"minimum": 0,
"description": "Position of an existing field (an entry with id). Integer greater than or equal to 0. An order already used by another field on this version is refused. Ignored on an insert; new fields are appended. Omitted keys are not written."
}
}
},
"description": "Fields to update, add, or remove. An id updates that field. No id inserts a field. op add inserts a field and must not include an id (label and type required; helpText at most 2000 characters, required, options, and stageId optional; stageId defaults to Interest or the first stage; the server assigns the id). On an existing field, order is an integer greater than or equal to 0 and sets that field's position. order on an insert is ignored and the new field is appended. An order already used by another field on this version is refused. op remove deletes that field when it is on the current draft and its key has no answers or consents on any version of this form. At most 20 adds and 20 removes per call. A form holds at most 140 fields. Unknown keys are rejected. Omitted keys are not written."
},
"removeFieldIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Field ids to delete from the current draft. A field whose key has answers or consents on any version of this form is refused. Combined with op remove, at most 20 deletes per call."
},
"editorSession": {
"type": "string",
"description": "Editor tab session. Send with editorSeq. Omitted saves keep last-commit-wins and leave the stored stamp."
},
"editorSeq": {
"type": "integer",
"minimum": 1,
"description": "Editor sequence for this session. A lower sequence does not overwrite a newer save."
}
},
"required": [
"formId"
],
"additionalProperties": false
}