Create a form

Generate a new form from a natural-language prompt.

POST /api/v1/forms/generate

Request

Headers

Header	Required	Description
`Authorization`	Yes	Bearer {api_key}
`Content-Type`	Yes	application/json

Body

Field	Type	Required	Description
`prompt`	string	Yes	Description of the form. Max 4,000 characters.
`metadata`	object	No	Key-value pairs stored with the form.

Response (success)

Status: 200 OK

{
  "success": true,
  "data": {
    "formId": "form_1739012345_abc123xyz",
    "formUrl": "https://www.chatterforms.com/forms/form_1739012345_abc123xyz",
    "formSchema": {
      "title": "Contact Form",
      "fields": [
        { "type": "text", "label": "Name", "required": true },
        { "type": "email", "label": "Email", "required": true }
      ]
    },
    "warnings": [],
    "settings_url": "https://www.chatterforms.com/settings"
  },
  "meta": { "request_id": null, "api_version": "2024-01-01" }
}

When payment or Calendly fields exist but accounts are not connected, warnings and settings_url are included.

Code examples

curl -X POST https://backend.chatterforms.com/api/v1/forms/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cf_live_YOUR_API_KEY" \
  -d '{
    "prompt": "A contact form with name, email, and digital signature",
    "metadata": { "source": "api", "campaign": "summer-2025" }
  }'

const API_KEY = 'cf_live_YOUR_API_KEY';
const BASE_URL = 'https://backend.chatterforms.com';

async function createForm(prompt, metadata = {}) {
  const res = await fetch(`${BASE_URL}/api/v1/forms/generate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify({ prompt, metadata }),
  });

  const json = await res.json();
  if (!json.success) throw new Error(json.error?.message || 'Request failed');
  return json.data;
}

// Usage
const data = await createForm('A contact form with name, email, and signature');
console.log('Form URL:', data.formUrl);

import requests

API_KEY = 'cf_live_YOUR_API_KEY'
BASE_URL = 'https://backend.chatterforms.com'

def create_form(prompt: str, metadata: dict = None) -> dict:
    url = f'{BASE_URL}/api/v1/forms/generate'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {API_KEY}',
    }
    body = {'prompt': prompt}
    if metadata:
        body['metadata'] = metadata

    response = requests.post(url, json=body, headers=headers)
    data = response.json()

    if not data.get('success'):
        raise Exception(data.get('error', {}).get('message', 'Request failed'))

    return data['data']

# Usage
data = create_form('A contact form with name, email, and signature')
print('Form URL:', data['formUrl'])

Error responses

Status	Code	Description
400	PROMPT_REQUIRED	Missing or empty prompt
400	PROMPT_TOO_LONG	Prompt exceeds 4,000 characters
401	INVALID_API_KEY	Missing or invalid API key
403	UPGRADE_REQUIRED	Feature requires higher plan
413	FORM_GENERATION_FAILED	Token limit exceeded
415	UNSUPPORTED_MEDIA_TYPE	Must be application/json
500	FORM_GENERATION_FAILED	Internal error

See Errors for details.