Generate Forms using Weavely's Free API

Generate form

POST api.weavely.ai/v1/forms/generate

Request

No authentication header is required for this endpoint.

Body

name

string

A friendly name for the form (optional).

prompt

string

required

A natural-language description of the form to generate
e.g. "A simple contact form in Flemish".

files

array[object]

Optional array of the following objects:

{
mimeType: file.mimeType,  // e.g., "image/png", "application/pdf"
data: file.data // file encoded as base64
}

Response

url

string

The URL that opens the generated form in the Weavely editor.

Get form fields

GET api.weavely.ai/v1/forms/[formId]/fields

Request

Headers

Authorization

string

required

Bearer <token>
Your personal token.

Path Parameters

formId

string

required

The unique identifier of the form.

Response

formId

string

The form’s unique identifier.

version

string|null

The timestamp of the published version, or null if the form has no published version.

fields

array

The list of fields in the form.

Each field object includes:

string

The field’s unique identifier.

label

string

The field’s display label.

type

string

The type of the field (e.g., text, datetime, etc.).

Create form

POST api.weavely.ai/v1/forms

Creates a new form from a complete form specification.

Request

Headers

Authorization

string

required

Bearer <token>
Your personal token.

Content-Type

string

required

application/json

Body

The request body is a complete form specification with the following structure:

formJSON

object

required

The form structure containing all pages and elements.

{
  "pages": [
    {
      "id": "string",
      "name": "string",
      "type": "form-page" | "ending-page",
      "elements": [...]
    }
  ]
}

See **Form Structure Reference **below for complete element types and configurations.

themeJSON

object

required

The form’s visual theme configuration.

{
  "name": "string",
  "font": {...},
  "logo": {...},
  "colors": {...},
  "layout": {...},
  "visual": {...}
}

See **Theme Configuration Reference **below for all available options.

settings

object

Optional form settings.

{
  "access": {
    "stopSubmissions": boolean
  },
  "general": {
    "showProgressBar": boolean,
    "autoSaveProgress": boolean
  },
  "notifications": {
    "submissionEmail": {...},
    "confirmationEmail": {...}
  }
}

logicRules

array

Optional conditional logic rules.Each rule defines conditions and actions to execute based on field values.See **Logic Rules Reference **below for complete documentation.

eventTriggers

array

Optional event-based triggers.Triggers execute actions in response to form events (e.g., form submission, page load).See Event Triggers Reference below for available triggers and actions.

calculatedValues

array

Optional calculated field values.(Currently undocumented - reserved for future use)

pageAttributes

object

Optional page-specific attributes.(Currently undocumented - reserved for future use)

Response

string

The unique identifier (UUID) of the created form.

url

string

Direct link to edit the form in the Weavely editor.Format: https://forms.weavely.ai/editor/{formId}

Example

Request:

curl -X POST https://api.weavely.ai/v1/forms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wvy_your_token_here" \
  -d '{
    "formJSON": {
      "pages": [{
        "id": "page-1",
        "name": "Contact",
        "type": "form-page",
        "elements": [
          {
            "id": "name",
            "type": "input-text",
            "label": "Your Name",
            "settings": { "required": true },
            "placeholder": "Enter your name..."
          }
        ]
      }]
    },
    "themeJSON": {
      "name": "Nova",
      "colors": {
        "primary": "#6c5ce7",
        "background": "#FFFFFF"
      }
    }
  }'

Response:

{
  "id": "8e2d178f-4e9c-4fe3-9619-e44412bf7ba1",
  "url": "https://forms.weavely.ai/editor/8e2d178f-4e9c-4fe3-9619-e44412bf7ba1"
}

Form Structure Reference

Element Types

Weavely forms support 27 element types organized into categories: Input Elements:

input-text - Single-line text input
input-number - Numeric input
input-email - Email address input with validation
input-phone-number - Phone number input
input-url - URL input with validation
input-time - Time picker
input-date - Date picker
text-area - Multi-line text input
input-file - File upload

Choice Elements:

checkbox-buttons - Multiple selection checkboxes
radio-buttons - Single selection radio buttons
dropdown - Dropdown select menu
image-choice - Image-based selection
checkbox - Single checkbox (yes/no)
matrix - Grid of choices (rows × columns)
ranking - Drag-and-drop ranking

Rating Elements:

star-rating - Star-based rating (customizable number of stars)
scale-rating - Numeric scale rating
range-slider - Slider with min/max values

Display Elements:

heading - Heading text
paragraph - Paragraph text
image - Image display
embed-html - Custom HTML embed
embed-audio - Audio player
embed-video - Video embed

Special Elements:

signature - Digital signature capture
navigation-buttons - Form navigation controls (previous/next/submit)

Element Specifications

input-text

Single-line text input

{
  "type": "input-text",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

input-number

Numeric input only

{
  "type": "input-number",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

input-email

Email input with validation

{
  "type": "input-email",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

input-phone-number

Phone number input

{
  "type": "input-phone-number",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

input-url

URL input with validation

{
  "type": "input-url",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

input-time

Time picker input

{
  "type": "input-time",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

input-date

Date picker input

{
  "type": "input-date",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

text-area

Multi-line text input

{
  "type": "text-area",
  "label": "string",
  "settings": {
    "required": boolean
  },
  "description": "string",
  "placeholder": "string"
}

input-file

File upload input

{
  "type": "input-file",
  "label": "string",
  "settings": {
    "required": boolean,
    "maxFiles": number,
    "maxFileSize": number,
    "allowedFileType": "string"
  },
  "description": "string",
  "placeholder": "string"
}

checkbox-buttons

Multiple selection checkboxes

{
  "type": "checkbox-buttons",
  "label": "string",
  "settings": {
    "required": boolean,
    "randomize": boolean,
    "allowOtherOption": boolean,
    "otherOptionLabel": "string",
    "options": [
      {
        "label": "string",
        "value": "string"
      }
    ]
  },
  "description": "string",
  "placeholder": "string"
}

radio-buttons

Single selection radio group

{
  "type": "radio-buttons",
  "label": "string",
  "settings": {
    "required": boolean,
    "randomize": boolean,
    "allowOtherOption": boolean,
    "otherOptionLabel": "string",
    "options": [
      {
        "label": "string",
        "value": "string"
      }
    ]
  },
  "description": "string",
  "placeholder": "string"
}

dropdown

Dropdown select menu

{
  "type": "dropdown",
  "label": "string",
  "settings": {
    "required": boolean,
    "randomize": boolean,
    "placeholder": "string",
    "options": [
      {
        "label": "string",
        "value": "string"
      }
    ]
  },
  "description": "string",
  "placeholder": "string"
}

image-choice

Image-based selection

{
  "type": "image-choice",
  "label": "string",
  "settings": {
    "required": boolean,
    "multiple": boolean,
    "randomize": boolean,
    "imageWidth": number,
    "imageHeight": number,
    "imageFit": "string",
    "options": [
      {
        "label": "string",
        "value": "string",
        "data": "string (URL)" | null
      }
    ]
  },
  "description": "string",
  "placeholder": "string"
}

checkbox

Single checkbox (yes/no)

{
  "type": "checkbox",
  "label": "string",
  "settings": {
    "required": boolean,
    "default": boolean
  },
  "description": "string",
  "placeholder": "string"
}

matrix

Grid of choices (rows × columns)

{
  "type": "matrix",
  "label": "string",
  "fields": [
    {
      "id": "string (UUID)",
      "type": "matrix-field",
      "label": "string",
      "settings": {
        "required": boolean,
        "multiple": boolean,
        "options": [
          {
            "label": "string",
            "value": "string"
          }
        ]
      },
      "description": "string",
      "placeholder": "string"
    }
  ],
  "settings": {
    "required": boolean,
    "multiple": boolean,
    "options": [
      {
        "label": "string",
        "value": "string"
      }
    ]
  },
  "description": "string"
}

ranking

Drag-and-drop ranking

{
  "type": "ranking",
  "label": "string",
  "settings": {
    "required": boolean,
    "options": [
      {
        "label": "string",
        "value": "string"
      }
    ]
  },
  "description": "string",
  "placeholder": "string"
}

star-rating

Star-based rating

{
  "type": "star-rating",
  "label": "string",
  "settings": {
    "required": boolean,
    "stars": number,
    "icon": "string"
  },
  "description": "string",
  "placeholder": "string"
}

scale-rating

Numeric scale rating

{
  "type": "scale-rating",
  "label": "string",
  "settings": {
    "required": boolean,
    "scales": number
  },
  "description": "string",
  "placeholder": "string"
}

range-slider

Slider with min/max values

{
  "type": "range-slider",
  "label": "string",
  "settings": {
    "min": number,
    "max": number,
    "step": number
  },
  "description": "string",
  "placeholder": "string"
}

heading

Heading text

{
  "type": "heading",
  "label": "string"
}

paragraph

Paragraph text

{
  "type": "paragraph",
  "label": "string"
}

image

Image display

{
  "type": "image",
  "settings": {
    "src": "string (URL)"
  }
}

embed-html

Custom HTML embed

{
  "type": "embed-html",
  "settings": {
    "codeSnippet": "string"
  }
}

embed-audio

Audio player

{
  "type": "embed-audio",
  "settings": {
    "url": "string"
  }
}

embed-video

Video embed

{
  "type": "embed-video",
  "settings": {
    "url": "string"
  }
}

signature

Digital signature capture

{
  "type": "signature",
  "label": "string",
  "settings": {
    "fileFormat": "string"
  },
  "description": "string",
  "placeholder": "string"
}

navigation-buttons

Form navigation controls

{
  "type": "navigation-buttons",
  "elements": [
    {
      "id": "string (UUID)",
      "type": "previous_page",
      "label": "string"
    },
    {
      "id": "string (UUID)",
      "type": "next-page",
      "label": "string"
    },
    {
      "id": "string (UUID)",
      "type": "submit_form",
      "label": "string"
    }
  ]
}

Sub-types:

previous_page - Go to previous page
next-page - Go to next page
submit_form - Submit the form

Theme Configuration Reference

The themeJSON object controls all visual styling for the form. It contains the following sections: name, font, logo, colors, layout, visual, and components.

Theme Presets

Weavely includes 7 preset themes. Set via the name field — the preset provides default values for colors, fonts, and components. Any explicit values you set will override the preset defaults.

Nova
Retro
Dawn
Dusk
Frost
Ember
Glass

Font

Controls typography for body text and headings independently.

"font": {
  "text": {
    "size": "16px",
    "family": "Plus Jakarta Sans"
  },
  "headings": {
    "size": "32px",
    "family": "Plus Jakarta Sans"
  }
}

You can also set the font family globally using a shorthand:

"font": {
  "family": "Poppins"
}

Logo

Optional logo image displayed on the form.

"logo": {
  "src": "string (URL)" | null,
  "variables": {
    "width": "40px",
    "justifySelf": "center"
  }
}

Set src to an image URL, or null for no logo.

Colors

Full color palette for the form. All values are hex codes.

"colors": {
  "primary": "#6c5ce7",
  "background": "#FFFFFF",
  "text": "#000000",
  "question": "#000000",
  "answer": "#000000",
  "secondary": "#222222",
  "surface": "#F7F8FA",
  "border": "#dedfe0",
  "error": "#FF0000"
}

Color	Controls
`primary`	Buttons, accents, active states
`background`	Page/form background
`text`	General body text
`question`	Field labels / question text
`answer`	User input text
`secondary`	Secondary UI elements
`surface`	Input field backgrounds
`border`	Input borders, dividers
`error`	Validation error messages

You can provide only a subset of colors (e.g. just primary and background) and the theme preset will fill in the rest.

Layout

Controls where the visual (image or color) appears relative to the form.

"layout": {
  "type": "right"
}

Type	Description
`under`	Visual is placed behind the form as a full-page background
`left`	Visual is displayed as a left side panel, form on the right
`right`	Visual is displayed as a right side panel, form on the left
`clean`	No visual — form only
`over`	Visual overlays the form area
`through`	Visual bleeds through the form

Visual

The background visual — either an image or a solid color. Works together with layout to determine how the visual is positioned. Image visual:

"visual": {
  "type": "image",
  "value": "string (image URL)",
  "variables": {
    "size": "cover",
    "repeat": "no-repeat",
    "position": "center"
  }
}

Color visual:

"visual": {
  "type": "color",
  "value": "#5a3131",
  "variables": {
    "size": "cover",
    "repeat": "no-repeat",
    "position": "center"
  }
}

The variables object uses CSS-like properties and defaults to size: "cover", repeat: "no-repeat", position: "center" for both types. Common combinations:

Side image: layout.type: "right" (or "left") + visual.type: "image" — displays a photo alongside the form
Background color: layout.type: "under" + visual.type: "color" — fills the page behind the form with a solid color
Background image: layout.type: "under" + visual.type: "image" — fills the page behind the form with an image
No visual: layout.type: "clean" — form only, no visual element

Components

Controls form layout, input style, button style, and question weight.

"components": {
  "form": {
    "variables": {
      "gap": "30px",
      "maxWidth": "700px",
      "textAlign": "left"
    }
  },
  "input": {
    "preset": "default"
  },
  "button": {
    "preset": "default",
    "hoverAnimation": {
      "preset": "grow"
    }
  },
  "question": {
    "variables": {
      "fontWeight": "500"
    }
  }
}

Input presets:

default — Rounded input styling
square — Square input styling

Button presets:

default — Rounded button styling
square — Square button styling

Hover animation presets:

default — Default hover animation
grow — Grow effect on hover

Complete themeJSON Example

{
  "name": "Nova",
  "font": {
    "text": { "size": "16px", "family": "Plus Jakarta Sans" },
    "headings": { "size": "32px", "family": "Plus Jakarta Sans" }
  },
  "logo": {
    "src": null,
    "variables": { "width": "40px", "justifySelf": "center" }
  },
  "colors": {
    "primary": "#6c5ce7",
    "background": "#FFFFFF",
    "text": "#000000",
    "question": "#000000",
    "answer": "#000000",
    "secondary": "#222222",
    "surface": "#F7F8FA",
    "border": "#dedfe0",
    "error": "#FF0000"
  },
  "layout": { "type": "right" },
  "visual": {
    "type": "image",
    "value": "https://example.com/your-image.jpg",
    "variables": { "size": "cover", "repeat": "no-repeat", "position": "center" }
  },
  "components": {
    "form": { "variables": { "gap": "30px", "maxWidth": "700px", "textAlign": "left" } },
    "input": { "preset": "default" },
    "button": { "preset": "default", "hoverAnimation": { "preset": "grow" } },
    "question": { "variables": { "fontWeight": "500" } }
  }
}

Logic Rules Reference

Logic rules enable conditional behavior based on field values.

Structure

{
  "id": "string (UUID)",
  "name": "string",
  "logicalOperator": "any" | "all",
  "conditions": [{
    "id": "string (UUID)",
    "variable": "field:{elementId}",
    "operator": "isEmpty" | "isEqual" | "contains" | ...,
    "value": null | string | number
  }],
  "actions": [{
    "id": "string (UUID)",
    "name": "hideElement" | "showElement" | "skipToPage" | ...,
    "data": { "elementId": "string (UUID)" }
  }]
}

Logical Operators

any - OR logic: trigger actions if ANY condition is true
all - AND logic: trigger actions if ALL conditions are true

Condition Operators

Universal (all field types):

isEmpty - Check if field is empty/null
isNotEmpty - Check if field has a value
isEqual - Check if field equals a specific value
isNotEqual - Check if field does not equal a specific value

String operators (text fields):

contains - Check if field contains a substring
doesNotContain - Check if field does not contain a substring
startsWith - Check if field starts with a string
endsWith - Check if field ends with a string

Numeric operators (number fields):

lessThan - Check if field is less than a value
lessThanOrEqual - Check if field is less than or equal to a value
greaterThan - Check if field is greater than a value
greaterThanOrEqual - Check if field is greater than or equal to a value

Available Actions

hideElement - Hide a specific element
showElement - Show a specific element
hidePage - Hide a specific page
skipToPage - Navigate to a specific page
setEnding - Set which ending page to display

Event Triggers Reference

Event triggers execute actions in response to form events.

Structure

{
  "id": "string (UUID)",
  "name": "string",
  "trigger": {
    "name": "formSubmitted" | "formLoaded" | "formPageShown"
  },
  "actions": [{
    "id": "string (UUID)",
    "name": "openUrl" | "restartForm",
    "data": { "url": "string" }
  }]
}

Available Triggers

formSubmitted - Triggered when form is successfully submitted
formLoaded - Triggered when form initially loads
formPageShown - Triggered when a form page is displayed

Available Actions

openUrl - Redirect to a URL
- Requires data.url field
restartForm - Restart the form from the beginning
- No additional data required

Get Started

Features

Integrations

Account Management

Developers

​Generate form

​Request

​Body

​Response

​Get form fields

​Request

​Headers

​Path Parameters

​Response

​Create form

​Request

​Headers

​Body

​Response

​Example

​Form Structure Reference

​Element Types

​Element Specifications

​Theme Configuration Reference

​Theme Presets

​Font

​Logo

​Colors

​Layout

​Visual

​Components

​Complete themeJSON Example

​Logic Rules Reference

​Structure

​Logical Operators

​Condition Operators

​Available Actions

​Event Triggers Reference

​Structure

​Available Triggers

​Available Actions

Generate form

Request

Body

Response

Get form fields

Request

Headers

Path Parameters

Response

Create form

Request

Headers

Body

Response

Example

Form Structure Reference

Element Types

Element Specifications

Theme Configuration Reference

Theme Presets

Font

Logo

Colors

Layout

Visual

Components

Complete themeJSON Example

Logic Rules Reference

Structure

Logical Operators

Condition Operators

Available Actions

Event Triggers Reference

Structure

Available Triggers

Available Actions