> ## Documentation Index > Fetch the complete documentation index at: https://docs.fetchski-attract.com/llms.txt > Use this file to discover all available pages before exploring further. # Replace a form > Replaces the whole document: every field left out is reset to its default. PATCH changes only the fields sent. Update an existing form. **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` (or a draft `_id` and no `aposMode`) 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`. ## OpenAPI ````yaml /api-reference/openapi.yaml put /@apostrophecms/form/{_id} openapi: 3.1.0 info: title: Fetchski Attract CMS API description: >- Auto-generated OpenAPI spec for this Fetchski site instance. Authenticate machine-to-machine requests with an API key by sending the header `Authorization: ApiKey `. Keys are issued in the CMS (API Keys) and carry scopes that limit them to specific actions. Each key also has its own security policy, chosen when it is created: a signing mode (token only, signed writes, or every request signed with the key’s signing secret via `X-Fetchski-Timestamp` + `X-Fetchski-Signature`), an optional network allowlist, and reads/writes-per-minute limits (429 with `Retry-After` over them). Some routes require a signature from every key — see each route. version: 1.0.0 servers: - url: https://{host}/api/v1 description: 'Your site: set `host` to its host name.' variables: host: default: acme.example security: [] tags: - name: Authentication description: >- Sign in as a person to get a bearer token or a session cookie. Integrations use an API key instead: send `Authorization: ApiKey `. - name: SDK Packages description: >- The site’s own npm registry and Composer repository for the Attract SDKs, so an app installs them with one of the site’s API keys. Point npm, pnpm, Bun or Composer at them; the SDKs never call them. - name: Pages description: 'The page tree: each page’s content, place and URL.' - name: Global Content description: Site-wide content and settings every page shares. - name: Redirects description: Old URLs and where they now send visitors. - name: Internationalization description: The site’s locales. - name: Languages description: >- The site’s languages: the main language’s name and every further language’s name, code and Public switch. A save applies at once: a new language gets its home page and its own addresses (/fr/…), and its pages are then translated with each type’s localize routes. - name: Page Templates description: >- The site’s whole-page starting arrangements. They are not pages of the site (the Pages list leaves them out for API keys): read one, then make a page from it with Pages → create and `_copyingId` (`copyingId` in the SDKs). - name: Blog Posts description: The blog’s posts, and importing them from Markdown or MDX. - name: Blog Categories description: The categories posts are filed under. - name: Authors description: The people posts are credited to. - name: Team Members description: The people the Team section shows. - name: Testimonials description: Quotes from customers. - name: FAQ Items description: Questions and their answers. - name: FAQ Categories description: The groups questions are sorted into. - name: Google Reviews description: Reviews from the business’s Google profile, synced on a schedule. - name: Instagram Posts description: Posts from the connected Instagram account, synced on a schedule. - name: Service Areas description: The places the business serves, for the service map. - name: Cookies description: The cookies the consent banner declares. - name: Media description: The Images and Files libraries, and their tags. - name: Videos description: The Videos library. - name: Image Folders description: The folders that organize the Images library. - name: File Folders description: The folders that organize the Files library. - name: Video Folders description: The folders that organize the Videos library. - name: Photo Albums description: Hand-picked, ordered sets of photos for galleries. - name: Photo Feeds description: >- Feeds that collect photos from a connected photo source into the Images library on a schedule. - name: Attachments description: Uploading files and cropping images. - name: Fetchski Media description: >- Read-only discovery over the Images and Videos libraries: find what to reference in an MDX blog import, or which file to use, with its URLs. - name: Forms description: The site’s forms and their fields. - name: Form Submissions description: >- What visitors sent through the site’s forms. Submissions hold personal details: give a key `forms:read` only where it is needed. - name: Conversion Events description: >- The conversion event log — one record per conversion, with its attribution and consent snapshot and its delivery to each ad platform. Read it incrementally, post facts from other systems (a reservation purchase, a lead outcome), and adjust them (refunds, cancellations). One event ID travels everywhere as the platforms’ de-duplication key. - name: Visitor Attribution description: >- Per-visitor attribution on this site: first touch, last ad or campaign touch, and the ad platforms’ browser IDs. The join other systems use to attach a purchase to the marketing-site journey that led to it. - name: Ads Metrics description: >- Aggregates for dashboards: ad-click landings and conversions, by day, platform, campaign and more. - name: Conversions description: >- Conversion definitions — the visitor actions (a lead, a call click, a booking, a purchase) this site reports to the ad platforms, each with a row per platform. Managed by administrators in the CMS. - name: Webhooks description: >- Push notifications of form submissions and conversion-event changes to the site’s Webhook Destinations — signed with each destination’s own secret, retried for a day, at-least-once. Set destinations up in the CMS (Webhook Destinations, for people granted “Manage webhook destinations”): URL, events, optional filters and custom headers, and the signing secret shown once. - name: Request Log description: >- The page views the site captured (Connections → Tracking → Request log), and the query parameters on them: campaign tags and ad click IDs. paths: /@apostrophecms/form/{_id}: put: tags: - Forms summary: Replace a form description: >- Replaces the whole document: every field left out is reset to its default. PATCH changes only the fields sent. Update an existing form. **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` (or a draft `_id` and no `aposMode`) 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`. operationId: replaceForm parameters: - name: _id in: path required: true schema: type: string description: >- The document’s `_id`: a full id names its own locale and mode (the draft’s `…:en:draft`, the published one’s `…:en:published`; no `aposMode` needed), a bare `aposDocId` takes the request’s (`aposLocale`, `aposMode`). - $ref: '#/components/parameters/AposMode' - $ref: '#/components/parameters/AposLocale' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Form' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Form' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - ApiKeyAuth: - content:forms:write - BearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: >- import { createSiteClient } from '@fetchski/attract-cms-sdk'; const site = createSiteClient(); const form = await site.forms().replaceForm({ id: 'clx8m2k4p0000a1b2c3d4e5f6', title: 'Example title', visibility: 'public', email: 'jo@acme.example' }); - lang: php label: Laravel source: >- use Fetchski\AttractCmsLaravel\Facades\Attract; $form = Attract::forms()->replaceForm(id: 'clx8m2k4p0000a1b2c3d4e5f6', title: 'Example title', visibility: 'public', email: 'jo@acme.example'); components: parameters: AposMode: name: aposMode in: query description: >- `published` (the default) or `draft`. Drafts need a credential that may see them: an API key with the type’s write scope (`content::write`), or a signed-in editor. The public and a key with only the read scope get 403. required: false schema: type: string enum: - draft - published default: published example: published AposLocale: name: aposLocale in: query description: >- The locale to read or write, e.g. `en` (default: the site’s default locale). required: false schema: type: string example: fr schemas: Form: type: object properties: title: type: string title: Form name default: '' description: >- Its title: the name it goes by in every list, and the heading of its page where it has one. contents: title: Form contents description: >- 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`. allOf: - $ref: '#/components/schemas/FormSectionArea' slug: type: string description: >- The URL name: lowercase words joined by hyphens (letters outside a–z, even emoji, are kept). title: Slug default: '' x-fetchski-write-optional: Left out, it’s made from the title. visibility: type: string title: Visibility description: Select whether this content is public or private default: public enum: - public - loginRequired scheduledPublish: type: - string - 'null' description: An ISO 8601 date and time, e.g. `2026-10-21T14:30:00.000Z`. scheduledUnpublish: type: - string - 'null' description: An ISO 8601 date and time, e.g. `2026-10-21T14:30:00.000Z`. thankYouHeading: type: - string - 'null' title: Thank you message title default: '' description: Thank you message title. thankYouBody: title: Thank you message content description: >- Widgets, top to bottom: send `{ "items": [ … ] }`, one object per widget with its `type`. Writing it replaces the whole area. allOf: - $ref: '#/components/schemas/RichTextArea' sendConfirmationEmail: type: - boolean - 'null' title: Send a confirmation email description: Enable this to send a message to the person who submits this form. emailConfirmationField: type: - string - 'null' title: Which is your confirmation email field? description: >- 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. default: '' emails: type: - array - 'null' items: $ref: '#/components/schemas/FormEmailsItem' title: Email Address(es) for Results default: [] description: Email Address(es) for Results. email: type: string title: Primary internal email address description: >- 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. default: '' googleSheetSubmissions: type: - boolean - 'null' title: Submit to Google Spreadsheets description: Submit to Google Spreadsheets. googleSpreadsheetId: type: - string - 'null' title: Google Spreadsheet ID default: '' description: Google Spreadsheet ID. googleSheetName: type: - string - 'null' title: Google Spreadsheet Sheet Name description: >- 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. default: '' submitLabel: type: - string - 'null' title: Submit button label default: '' description: Submit button label. enableRecaptcha: type: - boolean - 'null' title: Enable reCAPTCHA on the form (spam prevention) description: >- To use, reCAPTCHA a site ID and secret key must be configured in website code or the website global settings. enableQueryParams: type: - boolean - 'null' title: Enable query parameter capture description: Enable query parameter capture. queryParamList: type: - array - 'null' items: $ref: '#/components/schemas/FormQueryParamListItem' title: Query parameter keys description: >- Create an array item for each query parameter value you wish to capture. default: [] formActions: type: - array - 'null' items: $ref: '#/components/schemas/FormFormActionsItem' title: Actions description: >- 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. default: [] archived: type: - boolean - 'null' title: Archived default: false description: >- In the archive: kept, but out of every list and off the site until it is restored. `false` (or null) for a live document. _id: type: string title: Document ID readOnly: true description: >- 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. type: type: string title: Document Type readOnly: true description: 'The document type’s name: always this type’s.' createdAt: type: string format: date-time title: Created At readOnly: true description: When it was created (ISO 8601). updatedAt: type: string format: date-time title: Updated At readOnly: true description: When it last changed (ISO 8601). aposShareKey: type: - string - 'null' description: >- 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. example: k3v9x2m7q1z8w4p6 readOnly: true required: - title - slug - visibility - email - _id - type - createdAt - updatedAt description: Form content type FormSectionArea: type: object description: >- Content made of widgets, as the site stores it: send `{ "items": [ … ] }`, one object per widget, top to bottom. It takes `form-section` widgets; an item of any other type is dropped. At most 1. Writing it replaces the whole area. properties: metaType: type: string enum: - area description: Always `area`. _id: type: string description: 'The area’s id, set by the site: leave it out when you write one.' items: type: array description: >- 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). items: $ref: '#/components/schemas/FormSectionWidget' maxItems: 1 additionalProperties: true example: items: - type: form-section RichTextArea: type: object description: >- Content made of widgets, as the site stores it: send `{ "items": [ … ] }`, one object per widget, top to bottom. It takes `@apostrophecms/rich-text` widgets; an item of any other type is dropped. Writing it replaces the whole area. properties: metaType: type: string enum: - area description: Always `area`. _id: type: string description: 'The area’s id, set by the site: leave it out when you write one.' items: type: array description: >- 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). items: $ref: '#/components/schemas/RichTextWidget' additionalProperties: true example: items: - type: '@apostrophecms/rich-text' content:

Hello from the API.

FormEmailsItem: type: object properties: _id: type: string description: The row’s id, unique in its array. email: type: string format: email title: Email Address for Results description: Email Address for Results. conditions: type: array items: $ref: '#/components/schemas/FormEmailsItemConditionsItem' title: Set Conditions for this Notification description: >- 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. default: [] required: - email additionalProperties: true FormQueryParamListItem: type: object properties: _id: type: string description: The row’s id, unique in its array. key: type: string title: Key default: '' description: Key. lengthLimit: type: - integer - 'null' title: Limit Saved Parameter Value Length (characters) description: Enter a whole number to limit the length of the value saved. minimum: 1 x-fetchski-clamped: true required: - key additionalProperties: true FormFormActionsItem: type: object properties: _id: type: string description: The row’s id, unique in its array. actionType: type: string title: Action enum: - webhook - emailNotify description: Action. enabled: type: boolean title: Enabled default: true description: Enabled. _destination: type: array items: type: object additionalProperties: true title: Webhook destination description: >- 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. maxItems: 1 notifyEmail: type: - string - 'null' title: Notify address description: >- 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. required: - actionType additionalProperties: true ApiError: type: object description: >- An error answer: the error’s name, a message saying what is wrong, and details by error. required: - name properties: name: type: string description: >- The error’s name: `invalid`, `required`, `unauthorized`, `forbidden`, `notfound`, `conflict`, `locked`, `tooManyRequests`, `error` (a server failure)… message: type: string description: What is wrong, and how to fix it. data: type: object additionalProperties: true description: >- Details, by error: `errors` (one entry per field problem, each with its `path`), `retryAfter` (seconds, on 429), `permission`… FormSectionWidget: type: object properties: type: type: string enum: - form-section description: 'The widget’s type: always `form-section`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. formFontOverrides: type: array items: $ref: '#/components/schemas/FormSectionWidgetFormFontOverridesItem' title: Font overrides description: >- Optional. Set part of this form in a different typeface. Leave empty to follow the site’s fonts (Site design → Typography). default: [] maxItems: 4 formEyebrowEnabled: type: boolean title: Show eyebrow default: true description: Show eyebrow. formEyebrow: type: string title: Eyebrow description: Small label shown above the title. default: Get in touch formEyebrowColor: type: - string - 'null' description: >- Optional. Overrides the eyebrow + its dash. Leave empty to use the secondary (mint) color. title: Eyebrow color (dark theme) formEyebrowColorLight: type: - string - 'null' description: >- Optional light-theme override. Falls back to the dark-theme color, then the mint default. title: Eyebrow color (light theme) formEyebrowWeight: type: - string - 'null' title: Eyebrow weight default: bold enum: - normal - medium - semibold - bold - extrabold - null description: Eyebrow weight. formEyebrowSize: type: - string - 'null' title: Eyebrow size default: normal enum: - small - normal - large - xlarge - null description: Eyebrow size. formHeading: type: string title: Heading default: Send us a message description: Heading. formHeadingColor: type: - string - 'null' description: Optional — leave empty to track the theme text color. title: Color (dark theme) formHeadingColorLight: type: - string - 'null' description: Optional light-theme override. Falls back to the dark-theme color. title: Color (light theme) formHeadingWeight: type: - string - 'null' title: Weight default: extrabold enum: - normal - medium - semibold - bold - extrabold - null description: Weight. formHeadingSize: type: - string - 'null' title: Size default: normal enum: - small - normal - large - xlarge - xxlarge - null description: Size. formIntro: type: string title: Intro description: Optional short sentence under the heading. default: Fill out the form below and we’ll get back to you shortly. formIntroColor: type: - string - 'null' description: Optional — leave empty to use the muted text color. title: Color (dark theme) formIntroColorLight: type: - string - 'null' description: Optional light-theme override. Falls back to the dark-theme color. title: Color (light theme) formIntroWeight: type: - string - 'null' title: Weight default: normal enum: - normal - medium - semibold - bold - extrabold - null description: Weight. formIntroSize: type: - string - 'null' title: Size default: normal enum: - small - normal - large - xlarge - xxlarge - null description: Size. formBand: type: - string - 'null' title: Band style description: >- Plain sits on the page; Raised is a contained card; Accent is a solid brand-color band. default: raised enum: - plain - raised - accent - null formAccentColor: type: - string - 'null' description: The accent band color. Leave empty to use the site accent color. title: Band color (dark theme) formAccentColorLight: type: - string - 'null' description: >- Optional light-theme override. Falls back to the dark-theme color, then the accent. title: Band color (light theme) formAlign: type: - string - 'null' title: Header alignment description: >- Alignment of the section header (the form fields stay left-aligned for legibility). default: center enum: - center - left - null formWidth: type: - string - 'null' title: Content width default: normal enum: - narrow - normal - wide - null description: Content width. formLabelGap: type: - string - 'null' title: Label spacing description: Vertical space between each field’s label and its input. default: normal enum: - compact - normal - roomy - spacious - null formBg: type: - string - 'null' title: Section background (dark theme) description: >- 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. default: transparent enum: - transparent - surface - raised - sunken - hill - accent-soft - custom - null formBgCustom: type: - string - 'null' description: Used when “Section background (dark theme)” is set to Custom color. title: Custom background (dark theme) formBgLight: type: - string - 'null' title: Section background (light theme) description: >- “Match dark theme” reuses the dark-theme choice; otherwise set the light-mode band independently. default: inherit enum: - inherit - transparent - surface - raised - sunken - hill - accent-soft - custom - null formBgLightCustom: type: - string - 'null' description: Used when “Section background (light theme)” is set to Custom color. title: Custom background (light theme) formSubmitLabel: type: string title: Button label description: The visible button text. Leave empty to hide the button. default: Submit formSubmitVariant: type: - string - 'null' title: Button style description: >- Solid fills with the color; Outline / Soft / Text link use it for the border + text. default: solid enum: - solid - outline - soft - link - null formSubmitSize: type: - string - 'null' title: Button size default: normal enum: - small - normal - large - null description: Button size. formSubmitRadius: type: - string - 'null' title: Corner radius default: slight enum: - pill - rounded - slight - square - null description: Corner radius. formSubmitColor: type: - string - 'null' description: >- Solid fill, or the border + text for the other styles. Defaults to the brand accent; CLEAR it for a transparent, outline-only button. title: Button color (dark theme) default: '--fetchski-accent' formSubmitColorLight: type: - string - 'null' description: >- Optional light-theme override. Falls back to the dark-theme color. (Brand tokens already flip per theme.) title: Button color (light theme) formSubmitTextColor: type: - string - 'null' description: >- The text/icon color. Clear it to derive from the button color (readable on solid fills). title: Label color (dark theme) default: '--fetchski-ink' formSubmitTextColorLight: type: - string - 'null' description: >- Optional light-theme override. Falls back to the dark-theme label color. title: Label color (light theme) formSubmitHoverColor: type: - string - 'null' description: >- Optional. Drives the hover treatment. Leave empty to derive it from the button color. title: Hover color (dark theme) formSubmitHoverColorLight: type: - string - 'null' description: >- Optional light-theme override. Falls back to the dark-theme hover color. title: Hover color (light theme) formSubmitStyle: type: - string - 'null' title: Hover surface description: >- The hover treatment: a soft shadow, a colored offset shadow, a glow, a fill sweep, or a thicker border. default: sweep enum: - none - single - dual - glow - sweep - thicken - null formSubmitShadowColor: type: - string - 'null' description: >- Optional. The offset-shadow or glow color on hover. Leave empty to use the site secondary color. title: Offset / glow color (dark theme) formSubmitShadowColorLight: type: - string - 'null' description: >- Optional light-theme override. Falls back to the dark-theme shadow color. title: Offset / glow color (light theme) formSubmitAnimation: type: - string - 'null' title: Hover motion default: lift-scale enum: - lift - scale - lift-scale - none - null description: Hover motion. formSubmitIcon: type: string title: Icon name description: >- Any Font Awesome icon name, e.g. star, bolt, arrow-left-to-bracket (no “fa-” prefix). Browse at fontawesome.com/icons. default: '' formSubmitIconFamily: type: - string - 'null' title: Icon family default: classic-regular enum: - classic-regular - duotone-regular - brands - jelly - jelly-duo - whiteboard - null description: Icon family. formSubmitIconPosition: type: - string - 'null' title: Icon position description: Which side of the label the icon sits on (when an icon name is set). default: before enum: - before - after - null formSubmitIconNudge: type: boolean title: Nudge icon on hover description: >- The icon slides toward its side on hover (e.g. an arrow edges outward). default: false _form: type: array items: type: object additionalProperties: true title: Submissions go to description: >- 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. maxItems: 1 sectionCss: type: - object - 'null' description: >- 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. properties: slots: type: object additionalProperties: type: string description: The CSS typed into each part slot, by slot name. css: type: string description: 'The compiled CSS (read only: rebuilt from `slots`).' mark: type: string description: The site’s check mark for `css` (read only). title: Custom CSS fields: title: Form fields description: >- 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. allOf: - $ref: '#/components/schemas/FormSectionFieldsArea' required: - type description: >- A `form-section` widget: its `type` and its own fields. A field left out takes its default. RichTextWidget: type: object properties: type: type: string enum: - '@apostrophecms/rich-text' description: 'The widget’s type: always `@apostrophecms/rich-text`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. content: type: string format: html description: >- The text as HTML, e.g. `

Our story

It began with one idea.

`. The site keeps the tags and styles this area’s editor offers (paragraphs, headings, bold, italic, links, lists…) and removes the rest. example:

Hello from the API.

sectionCss: type: - object - 'null' description: >- 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. properties: slots: type: object additionalProperties: type: string description: The CSS typed into each part slot, by slot name. css: type: string description: 'The compiled CSS (read only: rebuilt from `slots`).' mark: type: string description: The site’s check mark for `css` (read only). title: Custom CSS required: - type description: >- A `@apostrophecms/rich-text` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormEmailsItemConditionsItem: type: object properties: _id: type: string description: The row’s id, unique in its array. field: type: string title: Enter a field to use as your condition. description: >- Only select (drop-down) and checkbox fields can be used for this condition. default: '' value: type: string title: Enter the value an end-user will enter to meet this conditional. default: '' description: Enter the value an end-user will enter to meet this conditional. additionalProperties: true FormSectionWidgetFormFontOverridesItem: type: object properties: _id: type: string description: The row’s id, unique in its array. target: type: - string - 'null' title: Apply to description: >- 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. default: all enum: - all - heading - body - eyebrow - button - code - null source: type: - string - 'null' title: Typeface description: >- 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. default: slot enum: - slot - curated - cdn - upload - null slot: type: - string - 'null' title: Site typeface description: >- Set in Site design → Typography. Following the site’s own faces keeps a section on-brand and adds no download. default: display enum: - display - body - accent - null curated: type: - string - 'null' title: Curated pick description: >- Vetted families from Bunny Fonts and Fontshare, with their available weights already verified. default: archivo enum: - 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 - null cdnProvider: type: - string - 'null' title: Provider description: >- Where to browse for the family. Pick one, then follow the link below to find the exact name. default: bunny enum: - bunny - fontshare - null cdnFamily: type: string title: Family name description: >- 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. default: '' cdnWeights: type: string title: Weights description: >- 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. default: '' uploads: type: array items: $ref: >- #/components/schemas/FormSectionWidgetFormFontOverridesItemUploadsItem title: Font files description: >- One file per weight/style of the SAME typeface. woff2 strongly recommended (smallest, universally supported); woff/ttf/otf also accepted. default: [] maxItems: 4 fallback: type: - string - 'null' title: Fallback style description: >- Generic system font shown while this typeface loads (and if it fails). Curated picks set this automatically. default: sans enum: - sans - serif - mono - null additionalProperties: true FormSectionFieldsArea: type: object description: >- Content made of widgets, as the site stores it: send `{ "items": [ … ] }`, one object per widget, top to bottom. It 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` widgets; an item of any other type is dropped. Writing it replaces the whole area. properties: metaType: type: string enum: - area description: Always `area`. _id: type: string description: 'The area’s id, set by the site: leave it out when you write one.' items: type: array description: >- 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). items: $ref: '#/components/schemas/FormSectionFieldsAreaItem' additionalProperties: true example: items: - type: '@apostrophecms/rich-text' content:

Hello from the API.

FormSectionWidgetFormFontOverridesItemUploadsItem: type: object properties: _id: type: string description: The row’s id, unique in its array. file: type: object description: File attachment reference title: Font file weight: type: - string - 'null' title: Weight default: '400' enum: - '100' - '200' - '300' - '400' - '500' - '600' - '700' - '800' - '900' - null description: Weight. style: type: - string - 'null' title: Style default: normal enum: - normal - italic - null description: Style. required: - file additionalProperties: true FormSectionFieldsAreaItem: description: >- 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. oneOf: - $ref: '#/components/schemas/FormTextFieldWidget' - $ref: '#/components/schemas/FormTextareaFieldWidget' - $ref: '#/components/schemas/FormFileFieldWidget' - $ref: '#/components/schemas/FormBooleanFieldWidget' - $ref: '#/components/schemas/FormSelectFieldWidget' - $ref: '#/components/schemas/FormRadioFieldWidget' - $ref: '#/components/schemas/FormCheckboxesFieldWidget' - $ref: '#/components/schemas/FormConditionalWidget' - $ref: '#/components/schemas/FormGroupWidget' - $ref: '#/components/schemas/FormDividerWidget' - $ref: '#/components/schemas/RichTextWidget' discriminator: propertyName: type mapping: '@apostrophecms/form-text-field': '#/components/schemas/FormTextFieldWidget' '@apostrophecms/form-textarea-field': '#/components/schemas/FormTextareaFieldWidget' '@apostrophecms/form-file-field': '#/components/schemas/FormFileFieldWidget' '@apostrophecms/form-boolean-field': '#/components/schemas/FormBooleanFieldWidget' '@apostrophecms/form-select-field': '#/components/schemas/FormSelectFieldWidget' '@apostrophecms/form-radio-field': '#/components/schemas/FormRadioFieldWidget' '@apostrophecms/form-checkboxes-field': '#/components/schemas/FormCheckboxesFieldWidget' '@apostrophecms/form-conditional': '#/components/schemas/FormConditionalWidget' '@apostrophecms/form-group': '#/components/schemas/FormGroupWidget' '@apostrophecms/form-divider': '#/components/schemas/FormDividerWidget' '@apostrophecms/rich-text': '#/components/schemas/RichTextWidget' FormTextFieldWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-text-field' description: 'The widget’s type: always `@apostrophecms/form-text-field`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. fieldLabel: type: string title: Field label default: '' description: Field label. required: type: - boolean - 'null' title: Is this field required? description: Is this field required? fieldName: type: string description: >- 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. title: Field name default: '' inputType: type: - string - 'null' title: Input type description: >- If you are requesting certain formatted information (e.g., email, url, phone number), select the relevant input type here. If not, use "Text". default: text enum: - text - email - tel - url - date - password - null placeholder: type: string title: Placeholder description: >- Text to display in the field before someone uses it (e.g., to provide additional directions). default: '' required: - type - fieldLabel description: >- A `@apostrophecms/form-text-field` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormTextareaFieldWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-textarea-field' description: 'The widget’s type: always `@apostrophecms/form-textarea-field`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. fieldLabel: type: string title: Field label default: '' description: Field label. required: type: - boolean - 'null' title: Is this field required? description: Is this field required? fieldName: type: string description: >- 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. title: Field name default: '' placeholder: type: string title: Placeholder description: >- Text to display in the field before someone uses it (e.g., to provide additional directions). default: '' required: - type - fieldLabel description: >- A `@apostrophecms/form-textarea-field` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormFileFieldWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-file-field' description: 'The widget’s type: always `@apostrophecms/form-file-field`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. fieldLabel: type: string title: Field label default: '' description: Field label. required: type: - boolean - 'null' title: Is this field required? description: Is this field required? fieldName: type: string description: >- 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. title: Field name default: '' allowMultiple: type: boolean title: Allow multiple file attachments default: true description: Allow multiple file attachments. limitSize: type: boolean title: Limit file size? default: false description: Limit file size? maxSize: type: - integer - 'null' title: Max file attachment size description: In Bytes required: - type - fieldLabel description: >- A `@apostrophecms/form-file-field` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormBooleanFieldWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-boolean-field' description: 'The widget’s type: always `@apostrophecms/form-boolean-field`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. fieldLabel: type: string title: Field label default: '' description: Field label. required: type: - boolean - 'null' title: Is this field required? description: Is this field required? fieldName: type: string description: >- 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. title: Field name default: '' checked: type: - boolean - 'null' title: Default to pre-checked description: If "yes," the checkbox will start in the checked state. required: - type - fieldLabel description: >- A `@apostrophecms/form-boolean-field` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormSelectFieldWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-select-field' description: 'The widget’s type: always `@apostrophecms/form-select-field`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. fieldLabel: type: string title: Field label default: '' description: Field label. required: type: - boolean - 'null' title: Is this field required? description: Is this field required? fieldName: type: string description: >- 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. title: Field name default: '' choices: type: array items: $ref: '#/components/schemas/FormSelectFieldWidgetChoicesItem' title: Select input options default: [] description: Select input options. allowMultiple: type: boolean title: Allow multiple options to be selected default: false description: Allow multiple options to be selected. size: type: - integer - 'null' title: Number of options in the list that should be visible default: 0 minimum: 0 x-fetchski-clamped: true description: Number of options in the list that should be visible. required: - type - fieldLabel - choices description: >- A `@apostrophecms/form-select-field` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormRadioFieldWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-radio-field' description: 'The widget’s type: always `@apostrophecms/form-radio-field`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. fieldLabel: type: string title: Field label default: '' description: Field label. required: type: - boolean - 'null' title: Is this field required? description: Is this field required? fieldName: type: string description: >- 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. title: Field name default: '' choices: type: array items: $ref: '#/components/schemas/FormRadioFieldWidgetChoicesItem' title: Radio input options default: [] minItems: 1 description: Radio input options. allowMultiple: type: boolean title: Allow multiple options to be selected default: false description: Allow multiple options to be selected. size: type: - integer - 'null' title: Number of options in the list that should be visible default: 0 minimum: 0 x-fetchski-clamped: true description: Number of options in the list that should be visible. required: - type - fieldLabel - choices description: >- A `@apostrophecms/form-radio-field` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormCheckboxesFieldWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-checkboxes-field' description: 'The widget’s type: always `@apostrophecms/form-checkboxes-field`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. fieldLabel: type: string title: Field label default: '' description: Field label. required: type: - boolean - 'null' title: Is this field required? description: Is this field required? fieldName: type: string description: >- 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. title: Field name default: '' choices: type: array items: $ref: '#/components/schemas/FormCheckboxesFieldWidgetChoicesItem' title: Checkbox input options default: [] minItems: 1 description: Checkbox input options. required: - type - fieldLabel - choices description: >- A `@apostrophecms/form-checkboxes-field` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormConditionalWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-conditional' description: 'The widget’s type: always `@apostrophecms/form-conditional`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. conditionName: type: string title: Form field to check default: '' description: Form field to check. conditionValue: type: string title: Value that activates this group default: '' description: Value that activates this group. contents: title: Form contents description: >- aposForm:conditionalContentsHelp Widgets, top to bottom: send `{ "items": [ … ] }`, one object per widget with its `type`. Writing it replaces the whole area. allOf: - $ref: '#/components/schemas/FormConditionalContentsArea' required: - type - conditionName - conditionValue description: >- A `@apostrophecms/form-conditional` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormGroupWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-group' description: 'The widget’s type: always `@apostrophecms/form-group`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. label: type: string title: Group Label default: '' description: Group Label. contents: title: Group Contents description: >- aposForm:groupContentsHelp Widgets, top to bottom: send `{ "items": [ … ] }`, one object per widget with its `type`. Writing it replaces the whole area. allOf: - $ref: '#/components/schemas/FormGroupContentsArea' required: - type - label description: >- A `@apostrophecms/form-group` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormDividerWidget: type: object properties: type: type: string enum: - '@apostrophecms/form-divider' description: 'The widget’s type: always `@apostrophecms/form-divider`.' _id: type: string description: >- 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: type: string enum: - widget description: Always `widget`. required: - type description: >- A `@apostrophecms/form-divider` widget: its `type` and its own fields. A field left out takes its default. additionalProperties: true FormSelectFieldWidgetChoicesItem: type: object properties: _id: type: string description: The row’s id, unique in its array. label: type: string title: Option label description: The readable label displayed to users. default: '' value: type: string title: Option value description: >- The value saved (as text) in the database. If not entered, the label will be used. default: '' required: - label additionalProperties: true FormRadioFieldWidgetChoicesItem: type: object properties: _id: type: string description: The row’s id, unique in its array. label: type: string title: Option label description: The readable label displayed to users. default: '' value: type: string title: Option value description: >- The value saved (as text) in the database. If not entered, the label will be used. default: '' required: - label additionalProperties: true FormCheckboxesFieldWidgetChoicesItem: type: object properties: _id: type: string description: The row’s id, unique in its array. label: type: string title: Option label description: The readable label displayed to users. default: '' value: type: string title: Option value description: >- The value saved (as text) in the database. If not entered, the label will be used. default: '' required: - label additionalProperties: true FormConditionalContentsArea: type: object description: >- Content made of widgets, as the site stores it: send `{ "items": [ … ] }`, one object per widget, top to bottom. It 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-divider`, `@apostrophecms/rich-text` widgets; an item of any other type is dropped. Writing it replaces the whole area. properties: metaType: type: string enum: - area description: Always `area`. _id: type: string description: 'The area’s id, set by the site: leave it out when you write one.' items: type: array description: >- 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). items: $ref: '#/components/schemas/FormConditionalContentsAreaItem' additionalProperties: true example: items: - type: '@apostrophecms/rich-text' content:

Hello from the API.

FormGroupContentsArea: type: object description: >- Content made of widgets, as the site stores it: send `{ "items": [ … ] }`, one object per widget, top to bottom. It 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-divider`, `@apostrophecms/rich-text` widgets; an item of any other type is dropped. Writing it replaces the whole area. properties: metaType: type: string enum: - area description: Always `area`. _id: type: string description: 'The area’s id, set by the site: leave it out when you write one.' items: type: array description: >- 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). items: $ref: '#/components/schemas/FormGroupContentsAreaItem' additionalProperties: true example: items: - type: '@apostrophecms/rich-text' content:

Hello from the API.

FormConditionalContentsAreaItem: description: >- 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-divider`, `@apostrophecms/rich-text`: the one its `type` names. oneOf: - $ref: '#/components/schemas/FormTextFieldWidget' - $ref: '#/components/schemas/FormTextareaFieldWidget' - $ref: '#/components/schemas/FormFileFieldWidget' - $ref: '#/components/schemas/FormBooleanFieldWidget' - $ref: '#/components/schemas/FormSelectFieldWidget' - $ref: '#/components/schemas/FormRadioFieldWidget' - $ref: '#/components/schemas/FormCheckboxesFieldWidget' - $ref: '#/components/schemas/FormDividerWidget' - $ref: '#/components/schemas/RichTextWidget' discriminator: propertyName: type mapping: '@apostrophecms/form-text-field': '#/components/schemas/FormTextFieldWidget' '@apostrophecms/form-textarea-field': '#/components/schemas/FormTextareaFieldWidget' '@apostrophecms/form-file-field': '#/components/schemas/FormFileFieldWidget' '@apostrophecms/form-boolean-field': '#/components/schemas/FormBooleanFieldWidget' '@apostrophecms/form-select-field': '#/components/schemas/FormSelectFieldWidget' '@apostrophecms/form-radio-field': '#/components/schemas/FormRadioFieldWidget' '@apostrophecms/form-checkboxes-field': '#/components/schemas/FormCheckboxesFieldWidget' '@apostrophecms/form-divider': '#/components/schemas/FormDividerWidget' '@apostrophecms/rich-text': '#/components/schemas/RichTextWidget' FormGroupContentsAreaItem: description: >- 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-divider`, `@apostrophecms/rich-text`: the one its `type` names. oneOf: - $ref: '#/components/schemas/FormTextFieldWidget' - $ref: '#/components/schemas/FormTextareaFieldWidget' - $ref: '#/components/schemas/FormFileFieldWidget' - $ref: '#/components/schemas/FormBooleanFieldWidget' - $ref: '#/components/schemas/FormSelectFieldWidget' - $ref: '#/components/schemas/FormRadioFieldWidget' - $ref: '#/components/schemas/FormCheckboxesFieldWidget' - $ref: '#/components/schemas/FormConditionalWidget' - $ref: '#/components/schemas/FormDividerWidget' - $ref: '#/components/schemas/RichTextWidget' discriminator: propertyName: type mapping: '@apostrophecms/form-text-field': '#/components/schemas/FormTextFieldWidget' '@apostrophecms/form-textarea-field': '#/components/schemas/FormTextareaFieldWidget' '@apostrophecms/form-file-field': '#/components/schemas/FormFileFieldWidget' '@apostrophecms/form-boolean-field': '#/components/schemas/FormBooleanFieldWidget' '@apostrophecms/form-select-field': '#/components/schemas/FormSelectFieldWidget' '@apostrophecms/form-radio-field': '#/components/schemas/FormRadioFieldWidget' '@apostrophecms/form-checkboxes-field': '#/components/schemas/FormCheckboxesFieldWidget' '@apostrophecms/form-conditional': '#/components/schemas/FormConditionalWidget' '@apostrophecms/form-divider': '#/components/schemas/FormDividerWidget' '@apostrophecms/rich-text': '#/components/schemas/RichTextWidget' responses: BadRequest: description: 'The request is not valid: `message` says what to change.' content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: The credential is missing or not accepted. content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: The caller may not do this. content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: Nothing matches, or the caller may not see it. content: application/json: schema: $ref: '#/components/schemas/ApiError' InternalServerError: description: 'The site failed: `message` is the generic “An error occurred.”' content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- Paste your API key as the CMS showed it: `fsk___` (issued under API Keys). `ApiKey ` in front of it works too. Leave it empty to read as the public. BearerAuth: type: http scheme: bearer description: >- A person’s bearer token, from **Signing in (people)** → `POST /@apostrophecms/login/login`. Apps use an API key instead. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.