8. AI Generation API

PRO endpoint for generating form fields from natural language descriptions. Requires AI credits; the base action cost is 3 credits before any oversized-token surcharge.

POST /formforge/v1/generate

Accepts a natural language prompt and returns an array of field definitions.

curl -s -X POST -u "admin:XXXX XXXX XXXX XXXX" \
  -H "Content-Type: application/json" \
  https://example.com/wp-json/formforge/v1/generate \
  -d '{"prompt": "Create a job application form for a software developer position"}'

{
  "fields": [
    { "id": "field_1", "type": "text", "label": "Full Name", "required": true, "placeholder": "", "options": [] },
    { "id": "field_2", "type": "email", "label": "Email", "required": true, "placeholder": "", "options": [] },
    {
      "id": "field_3", "type": "select", "label": "Years of Experience", "required": true, "placeholder": "",
      "options": [
        { "value": "0-2", "label": "0-2 years" },
        { "value": "3-5", "label": "3-5 years" }
      ]
    }
  ],
  "message": "Generated 3 fields."
}

Every field has id, type, label, required, placeholder and options; rows, min, max, max_stars and accept appear only when the model sets them. The ids come from the model. When the model also returns form settings, the answer has a settings object with submit_text, success_message and redirect_url.

{
  "fields": [],
  "success": false,
  "error": "credits_exhausted",
  "message": "(the message from the Forge API)",
  "remaining": 0,
  "reset_date": ""
}

Other answers: 404 with feature_not_available when the Pro add-on is not installed, 400 with empty_prompt when the prompt is empty, and 200 with an empty fields list and a message when AI is not configured or the call fails.

Pipeline: Generate then Create

# Generate fields, then create a form
FIELDS=$(curl -s -X POST -u "admin:XXXX" \
  -H "Content-Type: application/json" \
  https://example.com/wp-json/formforge/v1/generate \
  -d '{"prompt": "Simple event RSVP form"}' | jq '.fields')

curl -s -X POST -u "admin:XXXX" \
  -H "Content-Type: application/json" \
  https://example.com/wp-json/formforge/v1/forms \
  -d "{\"title\": \"Event RSVP\", \"fields\": $FIELDS}"

Prompt Tips for Better Results

Generated field definitions are normalized before save. Current aliases include FILE/file/upload -> file_upload, PARAGRAPH/paragraph/html/content -> html_block, dropdown -> select, and tel -> phone. Unknown types are downgraded to text, so AI output cannot create unsupported frontend controls or stale notification payloads.

Admin-side Error Event (formforge:ai-error)

Whenever AI generation fails in the admin builder, Fillin Forge dispatches a jQuery event you can listen to from any other admin script (analytics, custom toast UIs, audit logs). The default error card, with a title, an explanation and, where it helps, a Try again button or a link to the Fillin Forge Pro settings, is shown first; the event lets extensions add behavior on top without re-implementing the classification logic.

jQuery( document ).on( 'formforge:ai-error', function( e, payload ) {
    // payload.code    is the title of the error card (for example "Out of credits")
    // payload.message is the text shown in the error card
    if ( window.myAnalytics ) {
        window.myAnalytics.track( 'formforge_ai_error', {
            code: payload.code,
            message: payload.message
        } );
    }
} );

The event fires each time the error card is shown. payload.code holds the title of the card, which is one of: Out of credits (credits_exhausted or HTTP 402), Active subscription required (401, 403, pro_only or a missing license), Too many requests (429), Cannot reach the server (network error), Service temporarily unavailable (5xx), Could not understand the request (400 or empty_prompt), AI generation unavailable (404) and Could not generate the form (any other error). The titles are translated into the language of the admin, so match on them with care. payload.message is the text of the card.

—