chatformdocs
API referenceV1

Ask a model to change an existing form: add, edit or remove questions and rewire the flow

Returns the proposed document **without saving it**. Send it to `PUT /v1/forms/{id}/doc` to keep it. An edit may add no questions at all: most requests about a working form change the routing rather than the wording. Pass `history` (oldest first) when this is a follow-up, or the model cannot resolve 'also', 'it' or 'instead'. A request about the form's settings (its colours, the interviewer's tone, a closing date) comes back in `settings`, one entry per setting with its value before and after, already applied to `doc` unless it is marked `locked` because the plan does not include it. A question about how to do something comes back as `answer`, with no `doc`.

POST
/v1/ai/edit-form

Authorization

AuthorizationBearer <token>

A server-side secret key. Never send one from a browser — a request carrying an Origin header is refused for this reason.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/ai/edit-form" \  -H "Content-Type: application/json" \  -d '{    "formId": "string",    "prompt": "string"  }'
{  "doc": {    "schemaVersion": 0,    "title": "string",    "description": "string",    "blocks": [      {        "property1": null,        "property2": null      }    ],    "endings": [      {        "property1": null,        "property2": null      }    ],    "endingRules": [      null    ],    "logic": [      null    ],    "layout": {      "property1": {        "x": 0,        "y": 0      },      "property2": {        "x": 0,        "y": 0      }    },    "variables": [      null    ],    "hiddenFields": [      null    ],    "settings": {      "property1": null,      "property2": null    },    "theme": {      "property1": null,      "property2": null    },    "embed": {      "property1": null,      "property2": null    },    "property1": null,    "property2": null  },  "issues": [    {      "level": "string",      "code": "string",      "message": "string",      "path": "string",      "refs": [        "string"      ]    }  ],  "property1": null,  "property2": null}

Ask what a form request leaves open, before generating from it

Returns up to three questions whose answers would change the form, and **usually returns none**, which is the intended answer rather than a failure. Worth calling when a person is going to see the result: a request that asks to take a payment but names no UPI id, or to branch by plan without naming the plans, produces a form with a hole in it that only they can fill. Feed the answers back as `clarifications` on `POST /v1/ai/generate-form`. Skipping this endpoint entirely is fine; generation does not require it. Runs on the cheapest tier and is not charged as a generation, being a question about a form rather than a form, though its tokens are still counted.

Generate a form document from a natural-language prompt

Returns a document and its lint issues **without saving anything**. Pass the result to `POST /v1/forms` to keep it. Consumes one `ai_generations` unit and the tokens it costs, charged only when a usable document comes back. If you are already driving this from a model of your own, writing the document yourself and posting it to `/v1/forms` costs you nothing here. Settings the prompt asks for ("a dark, playful form that closes on the 30th") are set on `doc` and listed in `settings`, one entry per setting with its value before and after; one marked `locked` is not on your plan and was left at its default.