AI Forms API Reference

Base URL: https://smartform.dev/api/v2

All endpoints require authentication via API key. Send your key in the Authorization: Bearer <API_KEY> header.

Create a Form

POST /api/v2/forms

Creates a new AI-powered form from an A2UI JSON definition.

Request Body

Field	Type	Required	Description
`a2uiJson`	object	yes	A2UI v0.9.1 form definition
`title`	string	no	Optional human-readable title
`expiryDays`	number	no	Days until form auto-expires (default: 7, max: 365)
`callbackUrl`	string	no	Webhook URL for form submissions
`webhookSecret`	string	no	HMAC secret for webhook signing
`postSubmitType`	string	no	`"message"` or `"redirect"` (default: `"message"`)
`postSubmitValue`	string	no	Message text or redirect URL after submission

Response (201)

Field	Type	Description
`form_id`	string	Unique form identifier
`hosted_url`	string	Full-page hosted form URL
`embed_url`	string	Embed iframe URL
`embed_code`	string	Ready-to-paste `<script>` tag
`iframe_code`	string	Ready-to-paste `<iframe>` tag
`expires_at`	string	ISO-8601 expiry timestamp
`post_submit_type`	string	Post-submit behavior
`post_submit_value`	string	Post-submit message or URL

Example

curl -X POST https://smartform.dev/api/v2/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "a2uiJson": {
      "version": "0.9.1",
      "surfaces": [{
        "surfaceId": "main",
        "components": [
          { "type": "text-field", "id": "name", "label": "Full Name", "required": true },
          { "type": "email", "id": "email", "label": "Email Address", "required": true },
          { "type": "select", "id": "tier", "label": "Plan", "options": ["Free", "Pro", "Enterprise"] }
        ]
      }]
    },
    "postSubmitType": "message",
    "postSubmitValue": "Thanks! We'll be in touch."
  }'

Get a Form

GET /api/v2/forms/{formId}

Returns form details, status, and submission count.

Response (200)

{
  "id": "uuid",
  "title": "My Form",
  "a2ui_json": { ... },
  "status": "ACTIVE",
  "submission_count": 5,
  "created_at": "2025-01-01T00:00:00.000Z",
  "expires_at": "2025-01-08T00:00:00.000Z",
  "post_submit_type": "message",
  "post_submit_value": "Thanks!"
}

Update a Form

PUT /api/v2/forms/{formId}

Update title, A2UI definition, expiry, or post-submit config.

Request Body

All fields optional. Only provided fields will be updated.

Field	Type	Description
`a2uiJson`	object	Updated A2UI definition
`title`	string	New title
`expiryDays`	number	Extend expiry from now
`postSubmitType`	string	`"message"` or `"redirect"`
`postSubmitValue`	string	Updated message or URL

Deactivate a Form

DELETE /api/v2/forms/{formId}

Sets form status to DEACTIVATED. Submissions are no longer accepted.

List Submissions

GET /api/v2/forms/{formId}/submissions?limit=50&offset=0

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Max results (max 100)
`offset`	number	0	Pagination offset
`since`	string	—	ISO-8601 timestamp, only return submissions after this date

Response (200)

{
  "submissions": [
    {
      "id": "uuid",
      "data": { "name": "Alice", "email": "alice@example.com" },
      "metadata": { "userAgent": "...", "ipAddress": "..." },
      "submitted_at": "2025-01-01T12:00:00.000Z"
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 50
}

Submit to a Form (Public)

POST /api/v2/forms/{formId}/submit

This endpoint is public (no API key required). Submit form responses as an end user.

Request Body

Field	Type	Required	Description
`data`	object	yes	Key-value pairs of component IDs to values
`metadata`	object	no	Browser metadata (auto-collected by embed)

Response (201)

{
  "submission_id": "uuid",
  "status": "accepted",
  "post_submit_type": "message",
  "post_submit_value": "Thanks!"
}

A2UI Form Definition

A2UI is a declarative JSON format for defining forms. LLMs generate it natively.

Structure

{
  "version": "0.9.1",
  "surfaces": [
    {
      "surfaceId": "main",
      "components": [
        {
          "type": "text-field",
          "id": "name",
          "label": "Full Name",
          "required": true,
          "placeholder": "Enter your name"
        }
      ]
    }
  ]
}

Supported Component Types

Type	Description	Value Type
`text-field`	Single-line text input	string
`select`	Single-select dropdown	string
`multi-select`	Multi-select checkboxes	string[]
`date-time-input`	Date picker	string
`slider`	Range slider with min/max	number
`emoji-picker`	Emoji/icon picker	string
`text`	Static text/description	—
`card`	Visual card component	—
`image`	Image display	—
`button`	Custom button	—

Error Codes

Status	Meaning
400	Invalid request (missing fields, validation error)
401	Missing or invalid API key
404	Form not found
410	Form is not active or has expired
422	Submission validation failed
500	Server error

Authentication

Generate an API key from your SmartForm settings. Send it as:

Authorization: Bearer sf_your_api_key_here

Never expose API keys in client-side code. Server-side only.