Publishing

Share a page’s draft

Turns the draft’s preview share link on or off. Takes the draft’s exact _id (…:en:draft). Answers the draft, with its aposShareKey while the link is on: the link is the draft’s _url with aposShareKey and aposShareId (the draft’s _id) in its query.

Access: an API key with content:pages:write (or a master above it: content:pages:all, content:all, admin:all). 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.

POST

@apostrophecms

page

{_id}

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/page/{_id}/share \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "share": true
}'

{
  "_id": "ckhdscx5900054z9k88uqs16w:en:published",
  "aposDocId": "ckhdscx5900054z9k88uqs16w",
  "aposLocale": "en",
  "updatedAt": "2024-12-18T14:20:00.000Z",
  "slug": "/about-us",
  "path": "/about-us",
  "level": 1,
  "visibility": "public",
  "type": "@apostrophecms/page",
  "title": "About Us",
  "aposMode": "published",
  "archived": false,
  "createdAt": "2023-01-15T10:30:00.000Z",
  "titleSortified": "about us",
  "rank": 0,
  "orphan": false,
  "parked": [],
  "main": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "_ancestors": "<array>",
  "_children": "<array>",
  "_url": "https://example.com/about-us",
  "_edit": true,
  "_publish": true,
  "copyOfId": "ckhdscx5900054z9k88uqs16w:en:published",
  "_publishedDoc": "<unknown>",
  "_draftDoc": "<unknown>",
  "aposShareKey": "k3v9x2m7q1z8w4p6",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "seoTitle": "",
  "seoDescription": "",
  "seoImage": {
    "items": []
  },
  "pageFontOverrides": [],
  "footerMarqueeMode": "inherit",
  "sections": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "comingSoonIcon": "sparkles",
  "comingSoonIconFamily": "classic-regular",
  "comingSoonIconColor": "<string>",
  "comingSoonIconAnimation": "none",
  "comingSoonIconSize": "5x",
  "comingSoonNote": "",
  "backLinkColor": "<string>",
  "backLinkColorLight": "<string>",
  "backLinkWeight": "semibold",
  "backLinkSize": "normal",
  "aboveSections": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "postList": {
    "items": [
      {
        "type": "blog-list"
      }
    ]
  },
  "belowSections": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "backButtonLabel": "Back to all posts",
  "backButtonVariant": "outline",
  "backButtonSize": "normal",
  "backButtonRadius": "slight",
  "backButtonColor": "--fetchski-accent",
  "backButtonColorLight": "<string>",
  "backButtonTextColor": "--fetchski-ink",
  "backButtonTextColorLight": "<string>",
  "backButtonHoverColor": "<string>",
  "backButtonHoverColorLight": "<string>",
  "backButtonStyle": "sweep",
  "backButtonShadowColor": "<string>",
  "backButtonShadowColorLight": "<string>",
  "backButtonAnimation": "lift-scale",
  "backButtonIcon": "arrow-left",
  "backButtonIconFamily": "classic-regular",
  "backButtonIconPosition": "before",
  "backButtonIconNudge": false,
  "postFontOverrides": [],
  "postTextSize": "normal",
  "postTextWeight": "normal",
  "postContentWidth": "normal",
  "postLineHeight": "normal",
  "postAccentColor": "<string>",
  "postAccentColorLight": "<string>",
  "postHeadingWeight": "bold",
  "postHeadingColor": "<string>",
  "postHeadingColorLight": "<string>",
  "blogPostCss": {
    "slots": {},
    "css": "<string>",
    "mark": "<string>"
  }
}

{
  "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:pages:write

Path Parameters

_id

string

required

Computed document ID (can optionally include mode and locale, e.g., id:en:published)

Pattern: ^\S+$

Example:

"ckitdo5oq004pu69kr6oxo6fr:en:published"

Body

application/json

Whether the draft can be previewed through a share link.

true adds a share key (aposShareKey) to the draft; false (the default) removes it.

Response

Done.

A page: the fields every page has, and each page type’s own (type says which page type it is; a field belongs only to the page types that define it).

_id

string

required

Unique document identifier, may include mode and locale (e.g., "id:en:published")

Example:

"ckhdscx5900054z9k88uqs16w:en:published"

aposDocId

string

required

Base document ID without mode/locale qualifiers

Example:

"ckhdscx5900054z9k88uqs16w"

aposLocale

string

required

Document locale code

Example:

"en"

updatedAt

string<date-time>

required

Page last update timestamp

Example:

"2024-12-18T14:20:00.000Z"

slug

string

required

URL slug for the page

Example:

"/about-us"

path

string

required

Full hierarchical path in the page tree

Example:

"/about-us"

level

integer

required

Depth level in the page tree (0 = root level)

Example:

1

visibility

enum<string>

default:public

required

Page visibility setting

Available options:

public,

loginRequired,

private

Example:

"public"

type

string

required

Page type module name

Example:

"@apostrophecms/page"

title

string

required

Page title

Maximum string length: 100

Example:

"About Us"

aposMode

enum<string> | null

Document mode (draft or published)

Available options:

draft,

published,

null

Example:

"published"

archived

boolean | null

default:false

Whether the page is archived

createdAt

string<date-time> | null

Page creation timestamp

Example:

"2023-01-15T10:30:00.000Z"

titleSortified

string | null

Sortable version of the page title

Example:

"about us"

rank

integer | null

Sort order within parent page

Example:

0

orphan

boolean | null

default:false

Whether page is orphaned (not in tree structure)

parked

string[] | null

Array of parking lot configurations if page is parked

Example:

[]

main

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>"
    }
  ]
}

_ancestors

array | null

The page’s ancestors, from the home page down (each without its own _ancestors and _children).

_children

array | null

Its child pages, each with its own _children where the request asked for more levels.

_url

string<uri> | null

Full URL to the page

Example:

"https://example.com/about-us"

_edit

boolean | null

Whether current user can edit this page

Example:

true

_publish

boolean | null

Whether current user can publish this page

Example:

true

copyOfId

string | null

The _id of the piece/page that was copied to create this document (only present if created via _copyingId)

Example:

"ckhdscx5900054z9k88uqs16w:en:published"

_publishedDoc

any

Published version of the page (when viewing drafts)

_draftDoc

any

Draft version of the page (when viewing published)

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"

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.

seoTitle

string | null

default:""

Overrides the document title in the browser tab and search results. Leave blank to use the regular title.

seoDescription

string | null

default:""

Shown in search results and link previews. Aim for 150–160 characters.

seoImage

Social share image · object

Used for Open Graph / social link previews. Recommended 1200×630. Widgets, top to bottom: send { "items": [ … ] }, one object per widget with its type. Writing it replaces the whole area.

Show child attributes

Example:

{ "items": [] }

pageFontOverrides

Typeface for this page · object[] | null

Optional. Set part of this page in a different typeface. Leave empty to follow the site’s fonts (Site design → Typography). Individual sections can still override this for themselves.

Maximum array length: 4

Show child attributes

footerMarqueeMode

enum<string> | null

default:inherit

The ribbon of phrases scrolling across the top of the footer. Its phrases and the site-wide default are set in Site design → Footer: Marquee.

Available options:

inherit,

on,

off,

null

sections

Page sections · 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 page-header.

Show child attributes

Example:

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

comingSoonIcon

string | null

default:sparkles

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

comingSoonIconFamily

enum<string> | null

default:classic-regular

Icon family.

Available options:

classic-regular,

duotone-regular,

brands,

jelly,

jelly-duo,

whiteboard,

null

comingSoonIconColor

string | null

Optional — leave empty to use the design’s own color rhythm.

comingSoonIconAnimation

enum<string> | null

default:none

Icon animation.

Available options:

none,

fa-beat,

fa-bounce,

fa-fade,

fa-beat-fade,

fa-flip,

fa-shake,

fa-spin,

null

comingSoonIconSize

enum<string> | null

default:5x

Relative to the component’s base icon size.

Available options:

default,

sm,

lg,

xl,

2xl,

2x,

3x,

4x,

5x,

null

comingSoonNote

string | null

default:""

Optional. Shown under the icon while this page has no content. Leave empty for a tasteful default line.

backLinkColor

string | null

Optional. Color of the "← back" link at the top of every post. Leave empty to use the site accent color.

backLinkColorLight

string | null

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

backLinkWeight

enum<string> | null

default:semibold

Back link weight.

Available options:

normal,

medium,

semibold,

bold,

extrabold,

null

backLinkSize

enum<string> | null

default:normal

Back link size.

Available options:

small,

normal,

large,

xlarge,

null

aboveSections

Page sections · 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 page-header.

Show child attributes

Example:

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

postList

Post list · 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 blog-list.

Show child attributes

Example:

{ "items": [{ "type": "blog-list" }] }

belowSections

Page sections · 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>"
    }
  ]
}

backButtonLabel

string | null

default:Back to all posts

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

backButtonVariant

enum<string> | null

default:outline

Solid fills with the color; Outline / Soft / Text link use it for the border + text.

Available options:

solid,

outline,

soft,

link,

null

backButtonSize

enum<string> | null

default:normal

Button size.

Available options:

small,

normal,

large,

null

backButtonRadius

enum<string> | null

default:slight

Corner radius.

Available options:

pill,

rounded,

slight,

square,

null

backButtonColor

string | null

default:--fetchski-accent

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

backButtonColorLight

string | null

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

backButtonTextColor

string | null

default:--fetchski-ink

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

backButtonTextColorLight

string | null

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

backButtonHoverColor

string | null

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

backButtonHoverColorLight

string | null

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

backButtonStyle

enum<string> | null

default:sweep

The hover treatment: a soft shadow, a colored offset shadow, a glow, a fill sweep, or a thicker border.

Available options:

none,

single,

dual,

glow,

sweep,

thicken,

null

backButtonShadowColor

string | null

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

backButtonShadowColorLight

string | null

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

backButtonAnimation

enum<string> | null

default:lift-scale

Hover motion.

Available options:

lift,

scale,

lift-scale,

none,

null

backButtonIcon

string | null

default:arrow-left

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

backButtonIconFamily

enum<string> | null

default:classic-regular

Icon family.

Available options:

classic-regular,

duotone-regular,

brands,

jelly,

jelly-duo,

whiteboard,

null

backButtonIconPosition

enum<string> | null

default:before

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

Available options:

before,

after,

null

backButtonIconNudge

boolean | null

default:false

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

postFontOverrides

Typeface for posts · object[] | null

Optional. Set part of every post in a different typeface. Leave empty to follow the site’s fonts (Site design → Typography). An individual post can replace this on its own Fonts tab.

Maximum array length: 4

Show child attributes

postTextSize

enum<string> | null

default:normal

Body text size.

Available options:

small,

normal,

large,

xlarge,

null

postTextWeight

enum<string> | null

default:normal

Body text weight.

Available options:

normal,

medium,

semibold,

null

postContentWidth

enum<string> | null

default:normal

Reading measure — how wide the article column gets. Posts that contain section widgets open to Full width automatically so the widgets have room.

Available options:

narrow,

normal,

wide,

xwide,

full,

null

postLineHeight

enum<string> | null

default:normal

Line height.

Available options:

tight,

normal,

relaxed,

null

postAccentColor

string | null

Links, the blockquote rule, and heading accents. Leave empty to use the site link color.

postAccentColorLight

string | null

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

postHeadingWeight

enum<string> | null

default:bold

Heading weight.

Available options:

normal,

medium,

semibold,

bold,

extrabold,

null

postHeadingColor

string | null

Optional. Overrides in-article heading color. Leave empty to track the theme’s text color.

postHeadingColorLight

string | null

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

blogPostCss

Post custom CSS · object | null

CSS for every blog post’s page: the title band, the article and its parts. It wins over Site design → Custom CSS → Blog post.

Show child attributes

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/page/{_id}/share \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "share": true
}'

{
  "_id": "ckhdscx5900054z9k88uqs16w:en:published",
  "aposDocId": "ckhdscx5900054z9k88uqs16w",
  "aposLocale": "en",
  "updatedAt": "2024-12-18T14:20:00.000Z",
  "slug": "/about-us",
  "path": "/about-us",
  "level": 1,
  "visibility": "public",
  "type": "@apostrophecms/page",
  "title": "About Us",
  "aposMode": "published",
  "archived": false,
  "createdAt": "2023-01-15T10:30:00.000Z",
  "titleSortified": "about us",
  "rank": 0,
  "orphan": false,
  "parked": [],
  "main": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "_ancestors": "<array>",
  "_children": "<array>",
  "_url": "https://example.com/about-us",
  "_edit": true,
  "_publish": true,
  "copyOfId": "ckhdscx5900054z9k88uqs16w:en:published",
  "_publishedDoc": "<unknown>",
  "_draftDoc": "<unknown>",
  "aposShareKey": "k3v9x2m7q1z8w4p6",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "seoTitle": "",
  "seoDescription": "",
  "seoImage": {
    "items": []
  },
  "pageFontOverrides": [],
  "footerMarqueeMode": "inherit",
  "sections": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "comingSoonIcon": "sparkles",
  "comingSoonIconFamily": "classic-regular",
  "comingSoonIconColor": "<string>",
  "comingSoonIconAnimation": "none",
  "comingSoonIconSize": "5x",
  "comingSoonNote": "",
  "backLinkColor": "<string>",
  "backLinkColorLight": "<string>",
  "backLinkWeight": "semibold",
  "backLinkSize": "normal",
  "aboveSections": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "postList": {
    "items": [
      {
        "type": "blog-list"
      }
    ]
  },
  "belowSections": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "backButtonLabel": "Back to all posts",
  "backButtonVariant": "outline",
  "backButtonSize": "normal",
  "backButtonRadius": "slight",
  "backButtonColor": "--fetchski-accent",
  "backButtonColorLight": "<string>",
  "backButtonTextColor": "--fetchski-ink",
  "backButtonTextColorLight": "<string>",
  "backButtonHoverColor": "<string>",
  "backButtonHoverColorLight": "<string>",
  "backButtonStyle": "sweep",
  "backButtonShadowColor": "<string>",
  "backButtonShadowColorLight": "<string>",
  "backButtonAnimation": "lift-scale",
  "backButtonIcon": "arrow-left",
  "backButtonIconFamily": "classic-regular",
  "backButtonIconPosition": "before",
  "backButtonIconNudge": false,
  "postFontOverrides": [],
  "postTextSize": "normal",
  "postTextWeight": "normal",
  "postContentWidth": "normal",
  "postLineHeight": "normal",
  "postAccentColor": "<string>",
  "postAccentColorLight": "<string>",
  "postHeadingWeight": "bold",
  "postHeadingColor": "<string>",
  "postHeadingColorLight": "<string>",
  "blogPostCss": {
    "slots": {},
    "css": "<string>",
    "mark": "<string>"
  }
}

{
  "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)

Share a page’s draft

Authorizations

Scopes

Path Parameters

Body

Response