Create a form

import app from '@adonisjs/core/services/app'
import { SiteClient } from '@fetchski/attract-cms-sdk'

const site = await app.container.make(SiteClient)
const form = await site.forms().createForm({ title: 'Example title', visibility: 'public', email: 'jo@acme.example' })

{
  "title": "Example title",
  "contents": {
    "metaType": "area",
    "_id": "clx8m2k4p0000a1b2c3d4e5f6",
    "items": [
      {
        "type": "form-section",
        "_id": "clx8m2k4p0000a1b2c3d4e5f6",
        "metaType": "widget",
        "formFontOverrides": [],
        "formEyebrowEnabled": true,
        "formEyebrow": "Get in touch",
        "formEyebrowColor": "Example form eyebrow color",
        "formEyebrowColorLight": "Example form eyebrow color light",
        "formEyebrowWeight": "bold",
        "formEyebrowSize": "normal",
        "formHeading": "Send us a message",
        "formHeadingColor": "Example form heading color",
        "formHeadingColorLight": "Example form heading color light",
        "formHeadingWeight": "extrabold",
        "formHeadingSize": "normal",
        "formIntro": "Fill out the form below and we’ll get back to you shortly.",
        "formIntroColor": "Example form intro color",
        "formIntroColorLight": "Example form intro color light",
        "formIntroWeight": "normal",
        "formIntroSize": "normal",
        "formBand": "raised",
        "formAccentColor": "Example form accent color",
        "formAccentColorLight": "Example form accent color light",
        "formAlign": "center",
        "formWidth": "normal",
        "formLabelGap": "normal",
        "formBg": "transparent",
        "formBgCustom": "Example form bg custom",
        "formBgLight": "inherit",
        "formBgLightCustom": "Example form bg light custom",
        "formSubmitLabel": "Submit",
        "formSubmitVariant": "solid",
        "formSubmitSize": "normal",
        "formSubmitRadius": "slight",
        "formSubmitColor": "--fetchski-accent",
        "formSubmitColorLight": "Example form submit color light",
        "formSubmitTextColor": "--fetchski-ink",
        "formSubmitTextColorLight": "Example form submit text color light",
        "formSubmitHoverColor": "Example form submit hover color",
        "formSubmitHoverColorLight": "Example form submit hover color light",
        "formSubmitStyle": "sweep",
        "formSubmitShadowColor": "Example form submit shadow color",
        "formSubmitShadowColorLight": "Example form submit shadow color light",
        "formSubmitAnimation": "lift-scale",
        "formSubmitIcon": "Example form submit icon",
        "formSubmitIconFamily": "classic-regular",
        "formSubmitIconPosition": "before",
        "formSubmitIconNudge": false,
        "_form": [
          {}
        ],
        "sectionCss": {
          "slots": {
            "key": "Example value"
          },
          "css": "Example css",
          "mark": "Example mark"
        },
        "fields": {
          "metaType": "area",
          "_id": "clx8m2k4p0000a1b2c3d4e5f6",
          "items": [
            {}
          ]
        }
      }
    ]
  },
  "slug": "example-slug",
  "visibility": "public",
  "scheduledPublish": "Example scheduled publish",
  "scheduledUnpublish": "Example scheduled unpublish",
  "thankYouHeading": "Example thank you heading",
  "thankYouBody": {
    "metaType": "area",
    "_id": "clx8m2k4p0000a1b2c3d4e5f6",
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "_id": "clx8m2k4p0000a1b2c3d4e5f6",
        "metaType": "widget",
        "content": "<p>Hello from the API.</p>",
        "sectionCss": {
          "slots": {
            "key": "Example value"
          },
          "css": "Example css",
          "mark": "Example mark"
        }
      }
    ]
  },
  "sendConfirmationEmail": true,
  "emailConfirmationField": "jo@acme.example",
  "emails": [],
  "email": "jo@acme.example",
  "googleSheetSubmissions": true,
  "googleSpreadsheetId": "clx8m2k4p0000a1b2c3d4e5f6",
  "googleSheetName": "Example google sheet name",
  "submitLabel": "Example submit label",
  "enableRecaptcha": true,
  "enableQueryParams": true,
  "queryParamList": [],
  "formActions": [],
  "archived": false,
  "_id": "clx8m2k4p0000a1b2c3d4e5f6",
  "type": "Example type",
  "createdAt": "2026-10-24T09:30:00.000Z",
  "updatedAt": "2026-10-24T09:30:00.000Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

import app from '@adonisjs/core/services/app'
import { SiteClient } from '@fetchski/attract-cms-sdk'

const site = await app.container.make(SiteClient)
const form = await site.forms().createForm({ title: 'Example title', visibility: 'public', email: 'jo@acme.example' })

{
  "title": "Example title",
  "contents": {
    "metaType": "area",
    "_id": "clx8m2k4p0000a1b2c3d4e5f6",
    "items": [
      {
        "type": "form-section",
        "_id": "clx8m2k4p0000a1b2c3d4e5f6",
        "metaType": "widget",
        "formFontOverrides": [],
        "formEyebrowEnabled": true,
        "formEyebrow": "Get in touch",
        "formEyebrowColor": "Example form eyebrow color",
        "formEyebrowColorLight": "Example form eyebrow color light",
        "formEyebrowWeight": "bold",
        "formEyebrowSize": "normal",
        "formHeading": "Send us a message",
        "formHeadingColor": "Example form heading color",
        "formHeadingColorLight": "Example form heading color light",
        "formHeadingWeight": "extrabold",
        "formHeadingSize": "normal",
        "formIntro": "Fill out the form below and we’ll get back to you shortly.",
        "formIntroColor": "Example form intro color",
        "formIntroColorLight": "Example form intro color light",
        "formIntroWeight": "normal",
        "formIntroSize": "normal",
        "formBand": "raised",
        "formAccentColor": "Example form accent color",
        "formAccentColorLight": "Example form accent color light",
        "formAlign": "center",
        "formWidth": "normal",
        "formLabelGap": "normal",
        "formBg": "transparent",
        "formBgCustom": "Example form bg custom",
        "formBgLight": "inherit",
        "formBgLightCustom": "Example form bg light custom",
        "formSubmitLabel": "Submit",
        "formSubmitVariant": "solid",
        "formSubmitSize": "normal",
        "formSubmitRadius": "slight",
        "formSubmitColor": "--fetchski-accent",
        "formSubmitColorLight": "Example form submit color light",
        "formSubmitTextColor": "--fetchski-ink",
        "formSubmitTextColorLight": "Example form submit text color light",
        "formSubmitHoverColor": "Example form submit hover color",
        "formSubmitHoverColorLight": "Example form submit hover color light",
        "formSubmitStyle": "sweep",
        "formSubmitShadowColor": "Example form submit shadow color",
        "formSubmitShadowColorLight": "Example form submit shadow color light",
        "formSubmitAnimation": "lift-scale",
        "formSubmitIcon": "Example form submit icon",
        "formSubmitIconFamily": "classic-regular",
        "formSubmitIconPosition": "before",
        "formSubmitIconNudge": false,
        "_form": [
          {}
        ],
        "sectionCss": {
          "slots": {
            "key": "Example value"
          },
          "css": "Example css",
          "mark": "Example mark"
        },
        "fields": {
          "metaType": "area",
          "_id": "clx8m2k4p0000a1b2c3d4e5f6",
          "items": [
            {}
          ]
        }
      }
    ]
  },
  "slug": "example-slug",
  "visibility": "public",
  "scheduledPublish": "Example scheduled publish",
  "scheduledUnpublish": "Example scheduled unpublish",
  "thankYouHeading": "Example thank you heading",
  "thankYouBody": {
    "metaType": "area",
    "_id": "clx8m2k4p0000a1b2c3d4e5f6",
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "_id": "clx8m2k4p0000a1b2c3d4e5f6",
        "metaType": "widget",
        "content": "<p>Hello from the API.</p>",
        "sectionCss": {
          "slots": {
            "key": "Example value"
          },
          "css": "Example css",
          "mark": "Example mark"
        }
      }
    ]
  },
  "sendConfirmationEmail": true,
  "emailConfirmationField": "jo@acme.example",
  "emails": [],
  "email": "jo@acme.example",
  "googleSheetSubmissions": true,
  "googleSpreadsheetId": "clx8m2k4p0000a1b2c3d4e5f6",
  "googleSheetName": "Example google sheet name",
  "submitLabel": "Example submit label",
  "enableRecaptcha": true,
  "enableQueryParams": true,
  "queryParamList": [],
  "formActions": [],
  "archived": false,
  "_id": "clx8m2k4p0000a1b2c3d4e5f6",
  "type": "Example type",
  "createdAt": "2026-10-24T09:30:00.000Z",
  "updatedAt": "2026-10-24T09:30:00.000Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

In your app

A controller answers a route on your app: it calls createForm() and returns the answer.

Add the controller

app/controllers/create_form_controller.ts

import { inject } from '@adonisjs/core'
import { SiteClient } from '@fetchski/attract-cms-sdk'

@inject()
export default class CreateFormController {
  constructor(protected site: SiteClient) {}

  async handle() {
    return this.site.forms().createForm({ title: 'Example title', visibility: 'public', email: 'jo@acme.example' })
  }
}

The other values are the example’s: take yours from the request, a form or your database.

Add the route

start/routes.ts

import router from '@adonisjs/core/services/router'

const CreateFormController = () => import('#controllers/create_form_controller')

router.post('/form', [CreateFormController])

Put it behind your auth middleware (.use(middleware.auth())): it acts with your key’s access.

Call it

Your own page’s form or script sends POST /form and gets back its answer as JSON. Test it, below, calls it.

Required parameters

One object, e.g. createForm({ title }); leave out the optional fields.

string

required

Required. Its title: the name it goes by in every list, and the heading of its page where it has one.

Visibility

required

Required. Select whether this content is public or private. One of public, loginRequired.

string

required

Required. The “from” address on this form’s emails. A new form starts with the Email in Site settings → Brand; change it here for this form.

Optional parameters

AposMode | null | undefined

Optional. Leave it out and the site uses "published". published (the default) or draft. Drafts need a credential that may see them: an API key with the type’s write scope (content:<type>:write), or a signed-in editor. The public and a key with only the read scope get 403. One of draft, published.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. The locale to read or write, e.g. en (default: the site’s default locale).

FormSectionArea | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area. A new document starts with form-section.

Show FormSectionArea

AfterContentAreaMetaType

Always area. One of area.

string

The area’s id, set by the site: leave it out when you write one.

readonly FormSectionWidget[]

A list of FormSectionWidget. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). At most 1 items.

Show FormSectionWidget

A form-section widget: its type and its own fields. A field left out takes its default.

FormSectionWidgetType

required

Required. The widget’s type: always form-section. One of form-section.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

readonly FormSectionWidgetFormFontOverridesItem[]

A list of FormSectionWidgetFormFontOverridesItem. Optional. Set part of this form in a different typeface. Leave empty to follow the site’s fonts (Site design → Typography). At most 4 items.

Show FormSectionWidgetFormFontOverridesItem

string

The row’s id, unique in its array.

Target | null

Which text this typeface replaces. Rows apply in order, so a broad row (Everything) followed by a narrow one (Headings) gives the section a base face plus an exception. One of all, heading, body, eyebrow, button, code.

Source | null

Where the typeface comes from. The first option costs nothing extra — those faces are already loaded. The others load an additional font on pages that use this section. One of slot, curated, cdn, upload.

Slot | null

Set in Site design → Typography. Following the site’s own faces keeps a section on-brand and adds no download. One of display, body, accent.

Curated | null

Vetted families from Bunny Fonts and Fontshare, with their available weights already verified. One of archivo, bricolage-grotesque, clash-display, courier-prime, dm-mono, dm-sans, fira-code, fraunces, general-sans, ibm-plex-mono, ibm-plex-sans, inconsolata, inter, jetbrains-mono, karla, lora, manrope, nunito-sans, outfit, playfair-display, public-sans, red-hat-mono, satoshi, sentient, sora, source-code-pro, source-sans-3, source-serif-4, space-grotesk, space-mono, spline-sans-mono, supreme, switzer, syne, ubuntu-mono, unbounded, victor-mono, work-sans, zodiak.

CdnProvider | null

Where to browse for the family. Pick one, then follow the link below to find the exact name. One of bunny, fontshare.

string

Exactly as the provider’s catalog spells it, e.g. “Space Grotesk” or “Clash Display”. A name the provider doesn’t have loads nothing and this row is ignored.

string

Comma-separated weights to load, e.g. 400, 700. Empty loads 400, 500, 700. Weights the family doesn’t ship are skipped by the CDN and synthesized by the browser (faux bold) — but a family that ships only ONE weight (Acme, for instance) loads nothing at all unless that weight is among these, so set it explicitly if the typeface doesn’t appear.

readonly FormSectionWidgetFormFontOverridesItemUploadsItem[]

A list of FormSectionWidgetFormFontOverridesItemUploadsItem. One file per weight/style of the SAME typeface. woff2 strongly recommended (smallest, universally supported); woff/ttf/otf also accepted. At most 4 items.

Show FormSectionWidgetFormFontOverridesItemUploadsItem

Readonly<Record<string, unknown>>

required

Required. File attachment reference.

string

The row’s id, unique in its array.

Weight | null

Weight. One of 100, 200, 300, 400, 500, 600, 700, 800, 900.

Style | null

Style. One of normal, italic.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Fallback | null

Generic system font shown while this typeface loads (and if it fails). Curated picks set this automatically. One of sans, serif, mono.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

boolean

Show eyebrow.

string

Small label shown above the title.

string | null

Optional. Overrides the eyebrow + its dash. Leave empty to use the secondary (mint) color.

string | null

Optional light-theme override. Falls back to the dark-theme color, then the mint default.

FormEyebrowWeight | null

Eyebrow weight. One of normal, medium, semibold, bold, extrabold.

FormEyebrowSize | null

Eyebrow size. One of small, normal, large, xlarge.

string

Heading.

string | null

Optional — leave empty to track the theme text color.

string | null

Optional light-theme override. Falls back to the dark-theme color.

FormHeadingWeight | null

Weight. One of normal, medium, semibold, bold, extrabold.

FormHeadingSize | null

Size. One of small, normal, large, xlarge, xxlarge.

string

Optional short sentence under the heading.

string | null

Optional — leave empty to use the muted text color.

string | null

Optional light-theme override. Falls back to the dark-theme color.

FormIntroWeight | null

Weight. One of normal, medium, semibold, bold, extrabold.

FormIntroSize | null

Size. One of small, normal, large, xlarge, xxlarge.

FormBand | null

Plain sits on the page; Raised is a contained card; Accent is a solid brand-color band. One of plain, raised, accent.

string | null

The accent band color. Leave empty to use the site accent color.

string | null

Optional light-theme override. Falls back to the dark-theme color, then the accent.

FormAlign | null

Alignment of the section header (the form fields stay left-aligned for legibility). One of center, left.

FormWidth | null

Content width. One of narrow, normal, wide.

FormLabelGap | null

Vertical space between each field’s label and its input. One of compact, normal, roomy, spacious.

FormBg | null

The section’s full-width background band in dark mode. Transparent lets the page background show through. The palette options track the site colors; choose “Custom color…” for a specific color. One of transparent, surface, raised, sunken, hill, accent-soft, custom.

string | null

Used when “Section background (dark theme)” is set to Custom color.

FormBgLight | null

“Match dark theme” reuses the dark-theme choice; otherwise set the light-mode band independently. One of inherit, transparent, surface, raised, sunken, hill, accent-soft, custom.

string | null

Used when “Section background (light theme)” is set to Custom color.

string

The visible button text. Leave empty to hide the button.

FormSubmitVariant | null

Solid fills with the color; Outline / Soft / Text link use it for the border + text. One of solid, outline, soft, link.

FormSubmitSize | null

Button size. One of small, normal, large.

FormSubmitRadius | null

Corner radius. One of pill, rounded, slight, square.

string | null

Solid fill, or the border + text for the other styles. Defaults to the brand accent; CLEAR it for a transparent, outline-only button.

string | null

Optional light-theme override. Falls back to the dark-theme color. (Brand tokens already flip per theme.)

string | null

The text/icon color. Clear it to derive from the button color (readable on solid fills).

string | null

Optional light-theme override. Falls back to the dark-theme label color.

string | null

Optional. Drives the hover treatment. Leave empty to derive it from the button color.

string | null

Optional light-theme override. Falls back to the dark-theme hover color.

FormSubmitStyle | null

The hover treatment: a soft shadow, a colored offset shadow, a glow, a fill sweep, or a thicker border. One of none, single, dual, glow, sweep, thicken.

string | null

Optional. The offset-shadow or glow color on hover. Leave empty to use the site secondary color.

string | null

Optional light-theme override. Falls back to the dark-theme shadow color.

FormSubmitAnimation | null

Hover motion. One of lift, scale, lift-scale, none.

string

Any Font Awesome icon name, e.g. star, bolt, arrow-left-to-bracket (no “fa-” prefix). Browse at fontawesome.com/icons.

FormSubmitIconFamily | null

Icon family. One of classic-regular, duotone-regular, brands, jelly, jelly-duo, whiteboard.

FormSubmitIconPosition | null

Which side of the label the icon sits on (when an icon name is set). One of before, after.

boolean

The icon slides toward its side on hover (e.g. an arrow edges outward).

readonly Readonly<Record<string, unknown>>[]

The Form record that stores this form’s submissions and routes them (its Actions / integrations / Google Sheet). Create one in the Forms manager. The fields themselves are built right here on the page. The related @apostrophecms/form documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

CustomCSS | null

A CustomCSS. CSS for this one section, typed into the slot of the part it styles. It wins over Site design → Custom CSS. Nested rules like &:hover, @media (width >= 48rem) and [data-theme=“light”] & work inside a slot.

Show CustomCSS

Readonly<Record<string, string>>

The CSS typed into each part slot, by slot name.

string

The compiled CSS (read only: rebuilt from slots).

string

The site’s check mark for css (read only).

FormSectionFieldsArea

A FormSectionFieldsArea. Add and arrange the form’s fields here — edited live on the page. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show FormSectionFieldsArea

AfterContentAreaMetaType

Always area. One of area.

string

The area’s id, set by the site: leave it out when you write one.

readonly FormSectionFieldsAreaItem[]

A list of FormSectionFieldsAreaItem. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them).

Show FormSectionFieldsAreaItem

A widget in an area that takes @apostrophecms/form-text-field, @apostrophecms/form-textarea-field, @apostrophecms/form-file-field, @apostrophecms/form-boolean-field, @apostrophecms/form-select-field, @apostrophecms/form-radio-field, @apostrophecms/form-checkboxes-field, @apostrophecms/form-conditional, @apostrophecms/form-group, @apostrophecms/form-divider, @apostrophecms/rich-text: the one its type names.

Show FormTextFieldWidget

A @apostrophecms/form-text-field widget: its type and its own fields. A field left out takes its default.

FormTextFieldWidgetType

required

Required. The widget’s type: always @apostrophecms/form-text-field. One of @apostrophecms/form-text-field.

string

required

Required. Field label.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

boolean | null

Is this field required?

string

No spaces or punctuation other than dashes. If left blank, the form will populate this with a simplified form of the label. Changing this field after a form is in use may cause problems with any integrations.

InputType | null

If you are requesting certain formatted information (e.g., email, url, phone number), select the relevant input type here. If not, use “Text”. One of text, email, tel, url, date, password.

string

Text to display in the field before someone uses it (e.g., to provide additional directions).

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormTextareaFieldWidget

A @apostrophecms/form-textarea-field widget: its type and its own fields. A field left out takes its default.

FormTextareaFieldWidgetType

required

Required. The widget’s type: always @apostrophecms/form-textarea-field. One of @apostrophecms/form-textarea-field.

string

required

Required. Field label.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

boolean | null

Is this field required?

string

Text to display in the field before someone uses it (e.g., to provide additional directions).

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormFileFieldWidget

A @apostrophecms/form-file-field widget: its type and its own fields. A field left out takes its default.

FormFileFieldWidgetType

required

Required. The widget’s type: always @apostrophecms/form-file-field. One of @apostrophecms/form-file-field.

string

required

Required. Field label.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

boolean | null

Is this field required?

string

boolean

Allow multiple file attachments.

boolean

Limit file size?

number | null

In Bytes.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormBooleanFieldWidget

A @apostrophecms/form-boolean-field widget: its type and its own fields. A field left out takes its default.

FormBooleanFieldWidgetType

required

Required. The widget’s type: always @apostrophecms/form-boolean-field. One of @apostrophecms/form-boolean-field.

string

required

Required. Field label.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

boolean | null

Is this field required?

string

boolean | null

If “yes,” the checkbox will start in the checked state.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormSelectFieldWidget

A @apostrophecms/form-select-field widget: its type and its own fields. A field left out takes its default.

FormSelectFieldWidgetType

required

Required. The widget’s type: always @apostrophecms/form-select-field. One of @apostrophecms/form-select-field.

string

required

Required. Field label.

readonly FormSelectFieldWidgetChoicesItem[]

required

Required. A list of FormSelectFieldWidgetChoicesItem. Select input options.

Show FormSelectFieldWidgetChoicesItem

string

required

Required. The readable label displayed to users.

string

The row’s id, unique in its array.

string

The value saved (as text) in the database. If not entered, the label will be used.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

boolean | null

Is this field required?

string

boolean

Allow multiple options to be selected.

number | null

Number of options in the list that should be visible. At least 0.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormRadioFieldWidget

A @apostrophecms/form-radio-field widget: its type and its own fields. A field left out takes its default.

FormRadioFieldWidgetType

required

Required. The widget’s type: always @apostrophecms/form-radio-field. One of @apostrophecms/form-radio-field.

string

required

Required. Field label.

readonly FormRadioFieldWidgetChoicesItem[]

required

Required. A list of FormRadioFieldWidgetChoicesItem. Radio input options. At least 1 items.

Show FormRadioFieldWidgetChoicesItem

string

required

Required. The readable label displayed to users.

string

The row’s id, unique in its array.

string

The value saved (as text) in the database. If not entered, the label will be used.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

boolean | null

Is this field required?

string

boolean

Allow multiple options to be selected.

number | null

Number of options in the list that should be visible. At least 0.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormCheckboxesFieldWidget

A @apostrophecms/form-checkboxes-field widget: its type and its own fields. A field left out takes its default.

FormCheckboxesFieldWidgetType

required

Required. The widget’s type: always @apostrophecms/form-checkboxes-field. One of @apostrophecms/form-checkboxes-field.

string

required

Required. Field label.

readonly FormCheckboxesFieldWidgetChoicesItem[]

required

Required. A list of FormCheckboxesFieldWidgetChoicesItem. Checkbox input options. At least 1 items.

Show FormCheckboxesFieldWidgetChoicesItem

string

required

Required. The readable label displayed to users.

string

The row’s id, unique in its array.

string

The value saved (as text) in the database. If not entered, the label will be used.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

boolean | null

Is this field required?

string

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormConditionalWidget

A @apostrophecms/form-conditional widget: its type and its own fields. A field left out takes its default.

FormConditionalWidgetType

required

Required. The widget’s type: always @apostrophecms/form-conditional. One of @apostrophecms/form-conditional.

string

required

Required. Form field to check.

string

required

Required. Value that activates this group.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

FormConditionalContentsArea

A FormConditionalContentsArea. aposForm:conditionalContentsHelp Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show FormConditionalContentsArea

AfterContentAreaMetaType

Always area. One of area.

string

The area’s id, set by the site: leave it out when you write one.

readonly FormConditionalContentsAreaItem[]

A list of FormConditionalContentsAreaItem. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). Its fields are listed under the first FormConditionalContentsAreaItem above.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormGroupWidget

A @apostrophecms/form-group widget: its type and its own fields. A field left out takes its default.

FormGroupWidgetType

required

Required. The widget’s type: always @apostrophecms/form-group. One of @apostrophecms/form-group.

string

required

Required. Group Label.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

FormGroupContentsArea

A FormGroupContentsArea. aposForm:groupContentsHelp Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show FormGroupContentsArea

AfterContentAreaMetaType

Always area. One of area.

string

The area’s id, set by the site: leave it out when you write one.

readonly FormGroupContentsAreaItem[]

A list of FormGroupContentsAreaItem. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). Its fields are listed under the first FormGroupContentsAreaItem above.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show FormDividerWidget

A @apostrophecms/form-divider widget: its type and its own fields. A field left out takes its default.

FormDividerWidgetType

required

Required. The widget’s type: always @apostrophecms/form-divider. One of @apostrophecms/form-divider.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Show RichTextWidget

A @apostrophecms/rich-text widget: its type and its own fields. A field left out takes its default.

RichTextWidgetType

required

Required. The widget’s type: always @apostrophecms/rich-text. One of @apostrophecms/rich-text.

string

The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Always widget. One of widget.

string

The text as HTML, e.g. <h2>Our story</h2><p>It began with <strong>one</strong> idea.</p>. The site keeps the tags and styles this area’s editor offers (paragraphs, headings, bold, italic, links, lists…) and removes the rest.

CustomCSS | null

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

string | null | undefined

Optional. Leave it out and the site uses "". The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept). Left out, it’s made from the title.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

string | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

string | null | undefined

Optional. Leave it out and the site uses "". Thank you message title.

RichTextArea | null | undefined

Show RichTextArea

AfterContentAreaMetaType

Always area. One of area.

string

The area’s id, set by the site: leave it out when you write one.

readonly RichTextWidget[]

A list of RichTextWidget. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). Its fields are listed under the first RichTextWidget above.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

boolean | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Enable this to send a message to the person who submits this form.

string | null | undefined

Optional. Leave it out and the site uses "". Enter the “name” value of the field where people with enter their email address. For best results, make sure this field only accepts email addresses.

readonly FormEmailsItem[] | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Email Address(es) for Results.

Show FormEmailsItem

string

required

Required. Email Address for Results. Format: an email address.

string

The row’s id, unique in its array.

readonly FormEmailsItemConditionsItem[]

A list of FormEmailsItemConditionsItem. For example, if you only notify this email address if the “country” field is set to “Austria”. All conditions must be met. Add the email again with another conditional set if needed.

Show FormEmailsItemConditionsItem

string

The row’s id, unique in its array.

string

Only select (drop-down) and checkbox fields can be used for this condition.

string

Enter the value an end-user will enter to meet this conditional.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

boolean | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Submit to Google Spreadsheets.

string | null | undefined

Optional. Leave it out and the site uses "". Google Spreadsheet ID.

string | null | undefined

Optional. Leave it out and the site uses "". The name of the sheet tab in your Google spreadsheet where you want the submission appended. If not provided, the first sheet of the spreadsheet will be used.

string | null | undefined

Optional. Leave it out and the site uses "". Submit button label.

boolean | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. To use, reCAPTCHA a site ID and secret key must be configured in website code or the website global settings.

boolean | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Enable query parameter capture.

readonly FormQueryParamListItem[] | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Create an array item for each query parameter value you wish to capture.

Show FormQueryParamListItem

string

required

Required. Key.

string

The row’s id, unique in its array.

number | null

Enter a whole number to limit the length of the value saved. At least 1.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

readonly FormFormActionsItem[] | null | undefined

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. What happens to each submission, beyond being stored in the CMS. Add one row per destination; several can run for one form. Storage always happens regardless.

Show FormFormActionsItem

ActionType

required

Required. Action. One of webhook, emailNotify.

string

The row’s id, unique in its array.

boolean

Enabled.

readonly Readonly<Record<string, unknown>>[]

Where each submission is sent (⌘K → Webhook Destinations). It is signed with that destination’s secret, retried if the receiver is down, and listed on its Deliveries tab. The related webhook-destination documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

string | null

Where a copy of each submission is emailed (sent through Connections → Email). Replying answers the visitor. When set, an email address; empty or null when not.

Readonly<Record<string, unknown>>

Optional: any keys not listed above, by their wire names; they are sent with the rest.

boolean | null | undefined

Optional. Leave it out and the site uses false. In the archive: kept, but out of every list and off the site until it is restored. false (or null) for a live document.

Returns

A Form. Form content type. Read its properties (form.title): each says whether the site always sends it. The example answer is the site’s wire JSON: some keys differ from the property names (_id → id, _form → form, _destination → destination).

string

Always sent. Its title: the name it goes by in every list, and the heading of its page where it has one.

string

Always sent. The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept).

Visibility

Always sent. Select whether this content is public or private. One of public, loginRequired; a newer site may send others, so keep a fallback.

string

Always sent. The “from” address on this form’s emails. A new form starts with the Email in Site settings → Brand; change it here for this form.

string

Always sent. The document’s id. On a type with drafts it ends in its locale and mode (…:en:published, …:en:draft): the part before the first colon is its aposDocId, shared by both copies. The {_id} the type’s routes take.

string

Always sent. The document type’s name: always this type’s.

Date

Always sent. When it was created (ISO 8601). Format: an ISO 8601 date and time.

Date

Always sent. When it last changed (ISO 8601). Format: an ISO 8601 date and time.

FormSectionArea

Sometimes sent: undefined when the site leaves it out. A FormSectionArea. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area. A new document starts with form-section.

Show FormSectionArea

AfterContentAreaMetaType

Sometimes sent: undefined when the site leaves it out. Always area. One of area; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The area’s id, set by the site: leave it out when you write one.

readonly FormSectionWidget[]

Sometimes sent: undefined when the site leaves it out. A list of FormSectionWidget. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). At most 1 items.

Show FormSectionWidget

A form-section widget: its type and its own fields. A field left out takes its default.

FormSectionWidgetType

Always sent. The widget’s type: always form-section. One of form-section; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

readonly FormSectionWidgetFormFontOverridesItem[]

Sometimes sent: undefined when the site leaves it out. A list of FormSectionWidgetFormFontOverridesItem. Optional. Set part of this form in a different typeface. Leave empty to follow the site’s fonts (Site design → Typography). At most 4 items.

Show FormSectionWidgetFormFontOverridesItem

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

Target | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Which text this typeface replaces. Rows apply in order, so a broad row (Everything) followed by a narrow one (Headings) gives the section a base face plus an exception. One of all, heading, body, eyebrow, button, code; a newer site may send others, so keep a fallback.

Source | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where the typeface comes from. The first option costs nothing extra — those faces are already loaded. The others load an additional font on pages that use this section. One of slot, curated, cdn, upload; a newer site may send others, so keep a fallback.

Slot | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Set in Site design → Typography. Following the site’s own faces keeps a section on-brand and adds no download. One of display, body, accent; a newer site may send others, so keep a fallback.

Curated | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Vetted families from Bunny Fonts and Fontshare, with their available weights already verified. One of archivo, bricolage-grotesque, clash-display, courier-prime, dm-mono, dm-sans, fira-code, fraunces, general-sans, ibm-plex-mono, ibm-plex-sans, inconsolata, inter, jetbrains-mono, karla, lora, manrope, nunito-sans, outfit, playfair-display, public-sans, red-hat-mono, satoshi, sentient, sora, source-code-pro, source-sans-3, source-serif-4, space-grotesk, space-mono, spline-sans-mono, supreme, switzer, syne, ubuntu-mono, unbounded, victor-mono, work-sans, zodiak; a newer site may send others, so keep a fallback.

CdnProvider | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where to browse for the family. Pick one, then follow the link below to find the exact name. One of bunny, fontshare; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. Exactly as the provider’s catalog spells it, e.g. “Space Grotesk” or “Clash Display”. A name the provider doesn’t have loads nothing and this row is ignored.

string

Sometimes sent: undefined when the site leaves it out. Comma-separated weights to load, e.g. 400, 700. Empty loads 400, 500, 700. Weights the family doesn’t ship are skipped by the CDN and synthesized by the browser (faux bold) — but a family that ships only ONE weight (Acme, for instance) loads nothing at all unless that weight is among these, so set it explicitly if the typeface doesn’t appear.

readonly FormSectionWidgetFormFontOverridesItemUploadsItem[]

Sometimes sent: undefined when the site leaves it out. A list of FormSectionWidgetFormFontOverridesItemUploadsItem. One file per weight/style of the SAME typeface. woff2 strongly recommended (smallest, universally supported); woff/ttf/otf also accepted. At most 4 items.

Show FormSectionWidgetFormFontOverridesItemUploadsItem

Readonly<Record<string, unknown>>

Always sent. File attachment reference.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

Weight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Weight. One of 100, 200, 300, 400, 500, 600, 700, 800, 900; a newer site may send others, so keep a fallback.

Style | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Style. One of normal, italic; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

Always there: {} when there are none. Any keys the site sent that aren’t listed above (such as one added after this SDK was built), by their wire names, as sent. Pass this model to a write and they are sent too.

Fallback | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Generic system font shown while this typeface loads (and if it fails). Curated picks set this automatically. One of sans, serif, mono; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

boolean

Sometimes sent: undefined when the site leaves it out. Show eyebrow.

string

Sometimes sent: undefined when the site leaves it out. Small label shown above the title.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Overrides the eyebrow + its dash. Leave empty to use the secondary (mint) color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme color, then the mint default.

FormEyebrowWeight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Eyebrow weight. One of normal, medium, semibold, bold, extrabold; a newer site may send others, so keep a fallback.

FormEyebrowSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Eyebrow size. One of small, normal, large, xlarge; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. Heading.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional — leave empty to track the theme text color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme color.

FormHeadingWeight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Weight. One of normal, medium, semibold, bold, extrabold; a newer site may send others, so keep a fallback.

FormHeadingSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large, xlarge, xxlarge; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. Optional short sentence under the heading.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional — leave empty to use the muted text color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme color.

FormIntroWeight | null

FormIntroSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Size. One of small, normal, large, xlarge, xxlarge; a newer site may send others, so keep a fallback.

FormBand | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Plain sits on the page; Raised is a contained card; Accent is a solid brand-color band. One of plain, raised, accent; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The accent band color. Leave empty to use the site accent color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme color, then the accent.

FormAlign | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Alignment of the section header (the form fields stay left-aligned for legibility). One of center, left; a newer site may send others, so keep a fallback.

FormWidth | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Content width. One of narrow, normal, wide; a newer site may send others, so keep a fallback.

FormLabelGap | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Vertical space between each field’s label and its input. One of compact, normal, roomy, spacious; a newer site may send others, so keep a fallback.

FormBg | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The section’s full-width background band in dark mode. Transparent lets the page background show through. The palette options track the site colors; choose “Custom color…” for a specific color. One of transparent, surface, raised, sunken, hill, accent-soft, custom; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Used when “Section background (dark theme)” is set to Custom color.

FormBgLight | null

Sometimes sent: undefined when the site leaves it out, and it can be null. “Match dark theme” reuses the dark-theme choice; otherwise set the light-mode band independently. One of inherit, transparent, surface, raised, sunken, hill, accent-soft, custom; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Used when “Section background (light theme)” is set to Custom color.

string

Sometimes sent: undefined when the site leaves it out. The visible button text. Leave empty to hide the button.

FormSubmitVariant | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Solid fills with the color; Outline / Soft / Text link use it for the border + text. One of solid, outline, soft, link; a newer site may send others, so keep a fallback.

FormSubmitSize | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Button size. One of small, normal, large; a newer site may send others, so keep a fallback.

FormSubmitRadius | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Corner radius. One of pill, rounded, slight, square; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Solid fill, or the border + text for the other styles. Defaults to the brand accent; CLEAR it for a transparent, outline-only button.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme color. (Brand tokens already flip per theme.)

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The text/icon color. Clear it to derive from the button color (readable on solid fills).

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme label color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. Drives the hover treatment. Leave empty to derive it from the button color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme hover color.

FormSubmitStyle | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The hover treatment: a soft shadow, a colored offset shadow, a glow, a fill sweep, or a thicker border. One of none, single, dual, glow, sweep, thicken; a newer site may send others, so keep a fallback.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional. The offset-shadow or glow color on hover. Leave empty to use the site secondary color.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Optional light-theme override. Falls back to the dark-theme shadow color.

FormSubmitAnimation | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Hover motion. One of lift, scale, lift-scale, none; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. Any Font Awesome icon name, e.g. star, bolt, arrow-left-to-bracket (no “fa-” prefix). Browse at fontawesome.com/icons.

FormSubmitIconFamily | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Icon family. One of classic-regular, duotone-regular, brands, jelly, jelly-duo, whiteboard; a newer site may send others, so keep a fallback.

FormSubmitIconPosition | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Which side of the label the icon sits on (when an icon name is set). One of before, after; a newer site may send others, so keep a fallback.

boolean

Sometimes sent: undefined when the site leaves it out. The icon slides toward its side on hover (e.g. an arrow edges outward).

readonly Readonly<Record<string, unknown>>[]

Sometimes sent: undefined when the site leaves it out. The Form record that stores this form’s submissions and routes them (its Actions / integrations / Google Sheet). Create one in the Forms manager. The fields themselves are built right here on the page. The related @apostrophecms/form documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

CustomCSS | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A CustomCSS. CSS for this one section, typed into the slot of the part it styles. It wins over Site design → Custom CSS. Nested rules like &:hover, @media (width >= 48rem) and [data-theme=“light”] & work inside a slot.

Show CustomCSS

Readonly<Record<string, string>>

Sometimes sent: undefined when the site leaves it out. The CSS typed into each part slot, by slot name.

string

Sometimes sent: undefined when the site leaves it out. The compiled CSS (read only: rebuilt from slots).

string

Sometimes sent: undefined when the site leaves it out. The site’s check mark for css (read only).

FormSectionFieldsArea

Sometimes sent: undefined when the site leaves it out. A FormSectionFieldsArea. Add and arrange the form’s fields here — edited live on the page. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show FormSectionFieldsArea

AfterContentAreaMetaType

Sometimes sent: undefined when the site leaves it out. Always area. One of area; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The area’s id, set by the site: leave it out when you write one.

readonly FormSectionFieldsAreaItem[]

Sometimes sent: undefined when the site leaves it out. A list of FormSectionFieldsAreaItem. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them).

Show FormSectionFieldsAreaItem

Show FormTextFieldWidget

A @apostrophecms/form-text-field widget: its type and its own fields. A field left out takes its default.

FormTextFieldWidgetType

Always sent. The widget’s type: always @apostrophecms/form-text-field. One of @apostrophecms/form-text-field; a newer site may send others, so keep a fallback.

string

Always sent. Field label.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Is this field required?

string

Sometimes sent: undefined when the site leaves it out. No spaces or punctuation other than dashes. If left blank, the form will populate this with a simplified form of the label. Changing this field after a form is in use may cause problems with any integrations.

InputType | null

Sometimes sent: undefined when the site leaves it out, and it can be null. If you are requesting certain formatted information (e.g., email, url, phone number), select the relevant input type here. If not, use “Text”. One of text, email, tel, url, date, password; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. Text to display in the field before someone uses it (e.g., to provide additional directions).

Readonly<Record<string, unknown>>

Show FormTextareaFieldWidget

A @apostrophecms/form-textarea-field widget: its type and its own fields. A field left out takes its default.

FormTextareaFieldWidgetType

Always sent. The widget’s type: always @apostrophecms/form-textarea-field. One of @apostrophecms/form-textarea-field; a newer site may send others, so keep a fallback.

string

Always sent. Field label.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Is this field required?

string

Sometimes sent: undefined when the site leaves it out. Text to display in the field before someone uses it (e.g., to provide additional directions).

Readonly<Record<string, unknown>>

Show FormFileFieldWidget

A @apostrophecms/form-file-field widget: its type and its own fields. A field left out takes its default.

FormFileFieldWidgetType

Always sent. The widget’s type: always @apostrophecms/form-file-field. One of @apostrophecms/form-file-field; a newer site may send others, so keep a fallback.

string

Always sent. Field label.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Is this field required?

string

boolean

Sometimes sent: undefined when the site leaves it out. Allow multiple file attachments.

boolean

Sometimes sent: undefined when the site leaves it out. Limit file size?

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. In Bytes.

Readonly<Record<string, unknown>>

Show FormBooleanFieldWidget

A @apostrophecms/form-boolean-field widget: its type and its own fields. A field left out takes its default.

FormBooleanFieldWidgetType

Always sent. The widget’s type: always @apostrophecms/form-boolean-field. One of @apostrophecms/form-boolean-field; a newer site may send others, so keep a fallback.

string

Always sent. Field label.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Is this field required?

string

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. If “yes,” the checkbox will start in the checked state.

Readonly<Record<string, unknown>>

Show FormSelectFieldWidget

A @apostrophecms/form-select-field widget: its type and its own fields. A field left out takes its default.

FormSelectFieldWidgetType

Always sent. The widget’s type: always @apostrophecms/form-select-field. One of @apostrophecms/form-select-field; a newer site may send others, so keep a fallback.

string

Always sent. Field label.

readonly FormSelectFieldWidgetChoicesItem[]

Always sent. A list of FormSelectFieldWidgetChoicesItem. Select input options.

Show FormSelectFieldWidgetChoicesItem

string

Always sent. The readable label displayed to users.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. The value saved (as text) in the database. If not entered, the label will be used.

Readonly<Record<string, unknown>>

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Is this field required?

string

boolean

Sometimes sent: undefined when the site leaves it out. Allow multiple options to be selected.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Number of options in the list that should be visible. At least 0.

Readonly<Record<string, unknown>>

Show FormRadioFieldWidget

A @apostrophecms/form-radio-field widget: its type and its own fields. A field left out takes its default.

FormRadioFieldWidgetType

Always sent. The widget’s type: always @apostrophecms/form-radio-field. One of @apostrophecms/form-radio-field; a newer site may send others, so keep a fallback.

string

Always sent. Field label.

readonly FormRadioFieldWidgetChoicesItem[]

Always sent. A list of FormRadioFieldWidgetChoicesItem. Radio input options. At least 1 items.

Show FormRadioFieldWidgetChoicesItem

string

Always sent. The readable label displayed to users.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. The value saved (as text) in the database. If not entered, the label will be used.

Readonly<Record<string, unknown>>

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Is this field required?

string

boolean

Sometimes sent: undefined when the site leaves it out. Allow multiple options to be selected.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Number of options in the list that should be visible. At least 0.

Readonly<Record<string, unknown>>

Show FormCheckboxesFieldWidget

A @apostrophecms/form-checkboxes-field widget: its type and its own fields. A field left out takes its default.

FormCheckboxesFieldWidgetType

Always sent. The widget’s type: always @apostrophecms/form-checkboxes-field. One of @apostrophecms/form-checkboxes-field; a newer site may send others, so keep a fallback.

string

Always sent. Field label.

readonly FormCheckboxesFieldWidgetChoicesItem[]

Always sent. A list of FormCheckboxesFieldWidgetChoicesItem. Checkbox input options. At least 1 items.

Show FormCheckboxesFieldWidgetChoicesItem

string

Always sent. The readable label displayed to users.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. The value saved (as text) in the database. If not entered, the label will be used.

Readonly<Record<string, unknown>>

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Is this field required?

string

Readonly<Record<string, unknown>>

Show FormConditionalWidget

A @apostrophecms/form-conditional widget: its type and its own fields. A field left out takes its default.

FormConditionalWidgetType

Always sent. The widget’s type: always @apostrophecms/form-conditional. One of @apostrophecms/form-conditional; a newer site may send others, so keep a fallback.

string

Always sent. Form field to check.

string

Always sent. Value that activates this group.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

FormConditionalContentsArea

Sometimes sent: undefined when the site leaves it out. A FormConditionalContentsArea. aposForm:conditionalContentsHelp Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show FormConditionalContentsArea

AfterContentAreaMetaType

Sometimes sent: undefined when the site leaves it out. Always area. One of area; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The area’s id, set by the site: leave it out when you write one.

readonly FormConditionalContentsAreaItem[]

Sometimes sent: undefined when the site leaves it out. A list of FormConditionalContentsAreaItem. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). Its fields are listed under the first FormConditionalContentsAreaItem above.

Readonly<Record<string, unknown>>

Show FormGroupWidget

A @apostrophecms/form-group widget: its type and its own fields. A field left out takes its default.

FormGroupWidgetType

Always sent. The widget’s type: always @apostrophecms/form-group. One of @apostrophecms/form-group; a newer site may send others, so keep a fallback.

string

Always sent. Group Label.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

FormGroupContentsArea

Sometimes sent: undefined when the site leaves it out. A FormGroupContentsArea. aposForm:groupContentsHelp Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show FormGroupContentsArea

AfterContentAreaMetaType

Sometimes sent: undefined when the site leaves it out. Always area. One of area; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The area’s id, set by the site: leave it out when you write one.

readonly FormGroupContentsAreaItem[]

Sometimes sent: undefined when the site leaves it out. A list of FormGroupContentsAreaItem. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). Its fields are listed under the first FormGroupContentsAreaItem above.

Readonly<Record<string, unknown>>

Show FormDividerWidget

A @apostrophecms/form-divider widget: its type and its own fields. A field left out takes its default.

FormDividerWidgetType

Always sent. The widget’s type: always @apostrophecms/form-divider. One of @apostrophecms/form-divider; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

Readonly<Record<string, unknown>>

Show RichTextWidget

A @apostrophecms/rich-text widget: its type and its own fields. A field left out takes its default.

RichTextWidgetType

Always sent. The widget’s type: always @apostrophecms/rich-text. One of @apostrophecms/rich-text; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The widget’s id, unique on the page. Leave it out for a new widget (the site sets one); keep it to change a widget that is there.

MetaType

Sometimes sent: undefined when the site leaves it out. Always widget. One of widget; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The text as HTML, e.g. <h2>Our story</h2><p>It began with <strong>one</strong> idea.</p>. The site keeps the tags and styles this area’s editor offers (paragraphs, headings, bold, italic, links, lists…) and removes the rest.

CustomCSS | null

Readonly<Record<string, unknown>>

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Thank you message title.

RichTextArea

Sometimes sent: undefined when the site leaves it out. A RichTextArea. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show RichTextArea

AfterContentAreaMetaType

Sometimes sent: undefined when the site leaves it out. Always area. One of area; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The area’s id, set by the site: leave it out when you write one.

readonly RichTextWidget[]

Sometimes sent: undefined when the site leaves it out. A list of RichTextWidget. The widgets, top to bottom. Each is an object with its type and that widget’s own fields; _id and metaType may be left out (the site sets them). Its fields are listed under the first RichTextWidget above.

Readonly<Record<string, unknown>>

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Enable this to send a message to the person who submits this form.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Enter the “name” value of the field where people with enter their email address. For best results, make sure this field only accepts email addresses.

readonly FormEmailsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of FormEmailsItem. Email Address(es) for Results.

Show FormEmailsItem

string

Always sent. Email Address for Results. Format: an email address.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

readonly FormEmailsItemConditionsItem[]

Sometimes sent: undefined when the site leaves it out. A list of FormEmailsItemConditionsItem. For example, if you only notify this email address if the “country” field is set to “Austria”. All conditions must be met. Add the email again with another conditional set if needed.

Show FormEmailsItemConditionsItem

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

string

Sometimes sent: undefined when the site leaves it out. Only select (drop-down) and checkbox fields can be used for this condition.

string

Sometimes sent: undefined when the site leaves it out. Enter the value an end-user will enter to meet this conditional.

Readonly<Record<string, unknown>>

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Submit to Google Spreadsheets.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Google Spreadsheet ID.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. The name of the sheet tab in your Google spreadsheet where you want the submission appended. If not provided, the first sheet of the spreadsheet will be used.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Submit button label.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. To use, reCAPTCHA a site ID and secret key must be configured in website code or the website global settings.

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Enable query parameter capture.

readonly FormQueryParamListItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of FormQueryParamListItem. Create an array item for each query parameter value you wish to capture.

Show FormQueryParamListItem

string

Always sent. Key.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

number | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Enter a whole number to limit the length of the value saved. At least 1.

Readonly<Record<string, unknown>>

readonly FormFormActionsItem[] | null

Sometimes sent: undefined when the site leaves it out, and it can be null. A list of FormFormActionsItem. What happens to each submission, beyond being stored in the CMS. Add one row per destination; several can run for one form. Storage always happens regardless.

Show FormFormActionsItem

ActionType

Always sent. Action. One of webhook, emailNotify; a newer site may send others, so keep a fallback.

string

Sometimes sent: undefined when the site leaves it out. The row’s id, unique in its array.

boolean

Sometimes sent: undefined when the site leaves it out. Enabled.

readonly Readonly<Record<string, unknown>>[]

Sometimes sent: undefined when the site leaves it out. Where each submission is sent (⌘K → Webhook Destinations). It is signed with that destination’s secret, retried if the receiver is down, and listed on its Deliveries tab. The related webhook-destination documents, in order (empty when none). To set it, send a list of { "_id": "…" }, one per document (one at most); a document the site can’t find is left out. At most 1 items.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where a copy of each submission is emailed (sent through Connections → Email). Replying answers the visitor. When set, an email address; empty or null when not.

Readonly<Record<string, unknown>>

boolean | null

Sometimes sent: undefined when the site leaves it out, and it can be null. In the archive: kept, but out of every list and off the site until it is restored. false (or null) for a live document.

Sometimes sent: undefined when the site leaves it out, and it can be null. The draft’s preview share key, while its share link is on: the link is the draft’s _url with aposShareKey and aposShareId (the draft’s _id) in its query. Absent otherwise, and on published documents.

Errors

Nothing to catch: the SDK retries what is safe, and throws the rest as the classes below. Your exception handler turns them into your app’s own answers, once for every call (see Map SDK errors to responses); catch only what you want to react to here.

400

The site refused what was sent: errors lists each field’s problem, siteMessage the first.Retried first: No. Read: errors (field → messages), siteMessage.

401

The API key is missing or refused (malformed, revoked, expired), or a signature its signing mode needs is missing or stale.Retried first: No. Read: siteMessage, errorName, data.

403

The key may not do this: a scope it lacks, or an address outside its allowlist. siteMessage names it.Retried first: No. Read: siteMessage, errorName, data.

404

Nothing matches, or the caller may not see it.Retried first: No. Read: siteMessage, errorName, data.

500

The site failed. Its logs say why.Retried first: No: a write may have landed. Read: siteMessage, errorName, data.

no answer

No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Only when nothing reached the site (neverConnected()); never after a timeout, when it may have landed. Read: reason, neverConnected.

not sent

The client refused to send it (e.g. a path segment of ..); the site never saw it.Retried first: No. Read: reason (what to change).

any other

Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read: reason, status.

setup

sites.forSite('acme') named a slug config/attract.ts doesn’t list (with the keys in the database: no row in attract_api_keys).Retried first: No: nothing was sent. Read: message, slug.

setup

The site’s entry is wrong: a malformed baseUrl or key, a key filed under another slug, or no default site. node ace attract:check names the fix.Retried first: No: nothing was sent. Read: message (what to fix).

Behavior

Access: an API key with content:forms:write (or a master above it: content:forms:all, content:all, admin:all). In published mode (the default) it goes live too, so the key also needs content:forms:publish (or a master above it); send aposMode=draft to change only the draft. A signed-in person may call it as far as their own permissions allow; anyone else gets 403.
Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120); over it, 429 with Retry-After. The client waits and retries for you; you see RateLimited only if that runs out.
Retries: a write is sent again only after a 429 (refused before it acted) or when it never reached the site. After a timeout or a 5xx it may have landed: check before you send it again.
Timeout: 15 s per attempt by default; raise timeout (milliseconds) in config/attract.ts for longer.

Test it

It calls the controller above with the SDK faked: fakeAttract() puts the fake in the container for this one test, and it answers every call with a valid example, so nothing leaves your machine and no key is read. Save it as tests/unit/forms_create_form.spec.ts, then run your tests:

tests/unit/forms_create_form.spec.ts

import { test } from '@japa/runner'
import app from '@adonisjs/core/services/app'
import { fakeAttract } from '@fetchski/attract-cms-adonis/testing'
import CreateFormController from '#controllers/create_form_controller'

test('forms.createForm', async () => {
  const site = fakeAttract()

  const controller = await app.container.make(CreateFormController)
  await controller.handle()

  site.assertCalled('forms.createForm')
})

Terminal

node ace test

Answer with your own values: fake forms.createForm with factories.Form({...}), the fields you give over a valid example.

tests/unit/forms_create_form_answers.spec.ts

import { test } from '@japa/runner'
import { factories, fakeAttract } from '@fetchski/attract-cms-adonis/testing'

test('forms.createForm answers your values', async ({ assert }) => {
  const site = fakeAttract({
    'forms.createForm': factories.Form({ title: 'Your value' }),
  })

  const form = await site.forms().createForm({ title: 'Example title', visibility: 'public', email: 'jo@acme.example' })
  assert.containSubset(form, { title: 'Your value' })
})

List a form’s locales

site.forms().getFormLocales()

List forms

site.forms().listForms()

Get a form

site.forms().getForm()

Replace a form

site.forms().replaceForm()

Delete a form

site.forms().deleteForm()

Update a form

site.forms().updateForm()

POST /@apostrophecms/form

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.

import app from '@adonisjs/core/services/app'
import { SiteClient } from '@fetchski/attract-cms-sdk'

const site = await app.container.make(SiteClient)
const form = await site.forms().createForm({ title: 'Example title', visibility: 'public', email: 'jo@acme.example' })

{
  "title": "Example title",
  "contents": {
    "metaType": "area",
    "_id": "clx8m2k4p0000a1b2c3d4e5f6",
    "items": [
      {
        "type": "form-section",
        "_id": "clx8m2k4p0000a1b2c3d4e5f6",
        "metaType": "widget",
        "formFontOverrides": [],
        "formEyebrowEnabled": true,
        "formEyebrow": "Get in touch",
        "formEyebrowColor": "Example form eyebrow color",
        "formEyebrowColorLight": "Example form eyebrow color light",
        "formEyebrowWeight": "bold",
        "formEyebrowSize": "normal",
        "formHeading": "Send us a message",
        "formHeadingColor": "Example form heading color",
        "formHeadingColorLight": "Example form heading color light",
        "formHeadingWeight": "extrabold",
        "formHeadingSize": "normal",
        "formIntro": "Fill out the form below and we’ll get back to you shortly.",
        "formIntroColor": "Example form intro color",
        "formIntroColorLight": "Example form intro color light",
        "formIntroWeight": "normal",
        "formIntroSize": "normal",
        "formBand": "raised",
        "formAccentColor": "Example form accent color",
        "formAccentColorLight": "Example form accent color light",
        "formAlign": "center",
        "formWidth": "normal",
        "formLabelGap": "normal",
        "formBg": "transparent",
        "formBgCustom": "Example form bg custom",
        "formBgLight": "inherit",
        "formBgLightCustom": "Example form bg light custom",
        "formSubmitLabel": "Submit",
        "formSubmitVariant": "solid",
        "formSubmitSize": "normal",
        "formSubmitRadius": "slight",
        "formSubmitColor": "--fetchski-accent",
        "formSubmitColorLight": "Example form submit color light",
        "formSubmitTextColor": "--fetchski-ink",
        "formSubmitTextColorLight": "Example form submit text color light",
        "formSubmitHoverColor": "Example form submit hover color",
        "formSubmitHoverColorLight": "Example form submit hover color light",
        "formSubmitStyle": "sweep",
        "formSubmitShadowColor": "Example form submit shadow color",
        "formSubmitShadowColorLight": "Example form submit shadow color light",
        "formSubmitAnimation": "lift-scale",
        "formSubmitIcon": "Example form submit icon",
        "formSubmitIconFamily": "classic-regular",
        "formSubmitIconPosition": "before",
        "formSubmitIconNudge": false,
        "_form": [
          {}
        ],
        "sectionCss": {
          "slots": {
            "key": "Example value"
          },
          "css": "Example css",
          "mark": "Example mark"
        },
        "fields": {
          "metaType": "area",
          "_id": "clx8m2k4p0000a1b2c3d4e5f6",
          "items": [
            {}
          ]
        }
      }
    ]
  },
  "slug": "example-slug",
  "visibility": "public",
  "scheduledPublish": "Example scheduled publish",
  "scheduledUnpublish": "Example scheduled unpublish",
  "thankYouHeading": "Example thank you heading",
  "thankYouBody": {
    "metaType": "area",
    "_id": "clx8m2k4p0000a1b2c3d4e5f6",
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "_id": "clx8m2k4p0000a1b2c3d4e5f6",
        "metaType": "widget",
        "content": "<p>Hello from the API.</p>",
        "sectionCss": {
          "slots": {
            "key": "Example value"
          },
          "css": "Example css",
          "mark": "Example mark"
        }
      }
    ]
  },
  "sendConfirmationEmail": true,
  "emailConfirmationField": "jo@acme.example",
  "emails": [],
  "email": "jo@acme.example",
  "googleSheetSubmissions": true,
  "googleSpreadsheetId": "clx8m2k4p0000a1b2c3d4e5f6",
  "googleSheetName": "Example google sheet name",
  "submitLabel": "Example submit label",
  "enableRecaptcha": true,
  "enableQueryParams": true,
  "queryParamList": [],
  "formActions": [],
  "archived": false,
  "_id": "clx8m2k4p0000a1b2c3d4e5f6",
  "type": "Example type",
  "createdAt": "2026-10-24T09:30:00.000Z",
  "updatedAt": "2026-10-24T09:30:00.000Z",
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

Get started

Using the SDK

Going further

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

In your app

Behavior

Test it

List a form’s locales

List forms

Get a form

Replace a form

Delete a form

Update a form

POST /@apostrophecms/form

In your app

Behavior

Test it

Related

List a form’s locales

List forms

Get a form

Replace a form

Delete a form

Update a form

POST /@apostrophecms/form