Forms

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.

PUT

@apostrophecms

form

{_id}

cURL

curl --request PUT \
  --url https://{host}/api/v1/@apostrophecms/form/{_id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "",
  "slug": "",
  "visibility": "public",
  "email": ""
}
'

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' });

{
  "title": "",
  "slug": "",
  "visibility": "public",
  "email": "",
  "_id": "<string>",
  "type": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "contents": {
    "items": [
      {
        "type": "form-section"
      }
    ]
  },
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "thankYouHeading": "",
  "thankYouBody": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "sendConfirmationEmail": true,
  "emailConfirmationField": "",
  "emails": [],
  "googleSheetSubmissions": true,
  "googleSpreadsheetId": "",
  "googleSheetName": "",
  "submitLabel": "",
  "enableRecaptcha": true,
  "enableQueryParams": true,
  "queryParamList": [],
  "formActions": [],
  "archived": false,
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

Authorizations

Authorization

string

header

required

Paste your API key as the CMS showed it: fsk_<site>_<key id>_<secret> (issued under API Keys). ApiKey in front of it works too. Leave it empty to read as the public.

Scopes

content:forms:write

Path Parameters

_id

string

required

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).

Query Parameters

aposMode

enum<string>

default: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.

Available options:

draft,

published

aposLocale

string

The locale to read or write, e.g. en (default: the site’s default locale).

Example:

"fr"

Body

application/json

Form content type

title

string

default:""

required

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

slug

string

default:""

required

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

visibility

enum<string>

default:public

required

Select whether this content is public or private

Available options:

public,

loginRequired

string

default:""

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.

contents

Form contents · object

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 child attributes

Example:

{ "items": [{ "type": "form-section" }] }

scheduledPublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

scheduledUnpublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

thankYouHeading

string | null

default:""

Thank you message title.

thankYouBody

Thank you message content · object

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

Show child attributes

Example:

{
  "items": [
    {
      "type": "@apostrophecms/rich-text",
      "content": "<p>Hello from the API.</p>"
    }
  ]
}

sendConfirmationEmail

boolean | null

Enable this to send a message to the person who submits this form.

emailConfirmationField

string | null

default:""

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.

emails

Email Address(es) for Results · object[] | null

Email Address(es) for Results.

Show child attributes

googleSheetSubmissions

boolean | null

Submit to Google Spreadsheets.

googleSpreadsheetId

string | null

default:""

Google Spreadsheet ID.

googleSheetName

string | null

default:""

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.

submitLabel

string | null

default:""

Submit button label.

enableRecaptcha

boolean | null

To use, reCAPTCHA a site ID and secret key must be configured in website code or the website global settings.

enableQueryParams

boolean | null

Enable query parameter capture.

queryParamList

Query parameter keys · object[] | null

Create an array item for each query parameter value you wish to capture.

Show child attributes

formActions

Actions · object[] | null

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 child attributes

archived

boolean | null

default: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.

Response

Success

Form content type

title

string

default:""

required

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

slug

string

default:""

required

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

visibility

enum<string>

default:public

required

Select whether this content is public or private

Available options:

public,

loginRequired

string

default:""

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.

_id

string

required

read-only

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

string

required

read-only

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

createdAt

string<date-time>

required

read-only

When it was created (ISO 8601).

updatedAt

string<date-time>

required

read-only

When it last changed (ISO 8601).

contents

Form contents · object

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 child attributes

Example:

{ "items": [{ "type": "form-section" }] }

scheduledPublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

scheduledUnpublish

string | null

An ISO 8601 date and time, e.g. 2026-10-21T14:30:00.000Z.

thankYouHeading

string | null

default:""

Thank you message title.

thankYouBody

Thank you message content · object

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

Show child attributes

Example:

{
  "items": [
    {
      "type": "@apostrophecms/rich-text",
      "content": "<p>Hello from the API.</p>"
    }
  ]
}

sendConfirmationEmail

boolean | null

Enable this to send a message to the person who submits this form.

emailConfirmationField

string | null

default:""

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.

emails

Email Address(es) for Results · object[] | null

Email Address(es) for Results.

Show child attributes

googleSheetSubmissions

boolean | null

Submit to Google Spreadsheets.

googleSpreadsheetId

string | null

default:""

Google Spreadsheet ID.

googleSheetName

string | null

default:""

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.

submitLabel

string | null

default:""

Submit button label.

enableRecaptcha

boolean | null

To use, reCAPTCHA a site ID and secret key must be configured in website code or the website global settings.

enableQueryParams

boolean | null

Enable query parameter capture.

queryParamList

Query parameter keys · object[] | null

Create an array item for each query parameter value you wish to capture.

Show child attributes

formActions

Actions · object[] | null

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 child attributes

archived

boolean | null

default: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.

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"

cURL

curl --request PUT \
  --url https://{host}/api/v1/@apostrophecms/form/{_id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "",
  "slug": "",
  "visibility": "public",
  "email": ""
}
'

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' });

{
  "title": "",
  "slug": "",
  "visibility": "public",
  "email": "",
  "_id": "<string>",
  "type": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "contents": {
    "items": [
      {
        "type": "form-section"
      }
    ]
  },
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "thankYouHeading": "",
  "thankYouBody": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "sendConfirmationEmail": true,
  "emailConfirmationField": "",
  "emails": [],
  "googleSheetSubmissions": true,
  "googleSpreadsheetId": "",
  "googleSheetName": "",
  "submitLabel": "",
  "enableRecaptcha": true,
  "enableQueryParams": true,
  "queryParamList": [],
  "formActions": [],
  "archived": false,
  "aposShareKey": "k3v9x2m7q1z8w4p6"
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

{
  "name": "<string>",
  "message": "<string>",
  "data": {}
}

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Replace a form

Authorizations

Scopes

Path Parameters

Query Parameters

Body

Response