Publishing

Share a blog post’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:blog:write (or a master above it: content:blog: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

blog

{_id}

cURL

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

{
  "title": "",
  "publishedAt": "2023-12-25",
  "_id": "<string>",
  "type": "<string>",
  "_author": [
    {}
  ],
  "_category": [
    {}
  ],
  "slug": "",
  "visibility": "public",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "excerpt": "",
  "featuredImage": {
    "items": []
  },
  "main": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "afterContent": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "postFontOverrides": [],
  "seoTitle": "",
  "seoDescription": "",
  "seoImage": {
    "items": []
  },
  "archived": false,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "_url": "<string>",
  "_parentUrl": "<string>",
  "_parentSlug": "<string>",
  "_parent": {},
  "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:blog:write

Path Parameters

_id

string

required

The draft’s exact _id (…:en:draft).

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.

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

publishedAt

string<date>

required

The post’s publication date (YYYY-MM-DD, e.g. 2026-10-21): the date it shows, and its place in the blog list, newest first.

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

_author

Author · object[] | null

Credited author. Pick from the Authors collection — their profile photo shows alongside the post. The related author 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.

Maximum array length: 1

_category

Category · object[] | null

The post’s category. Manage the list (and each badge color) under Blog Categories. The related blog-category 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.

Maximum array length: 1

slug

string | null

default:""

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

visibility

enum<string> | null

default:public

Select whether this content is public or private

Available options:

public,

loginRequired,

null

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.

excerpt

string | null

default:""

Short teaser shown on the blog index and homepage. 1–2 sentences.

featuredImage

Featured image · 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": [] }

main

Body · 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 @apostrophecms/rich-text.

Show child attributes

Example:

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

afterContent

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

postFontOverrides

Typeface for this post · object[] | null

Optional. Leave empty to follow the blog’s Reading settings (and, through them, the site fonts). Adding a row here replaces the blog-wide choice for this post only.

Maximum array length: 4

Show child attributes

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

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.

createdAt

string<date-time> | null

read-only

When it was created (ISO 8601).

updatedAt

string<date-time> | null

read-only

When it last changed (ISO 8601).

_url

string<uri> | null

The document’s page on the site.

_parentUrl

string<uri> | null

The page that lists it (the blog page).

_parentSlug

string | null

That page’s slug.

_parent

object

That page, briefly (_id, title, slug, type, path, level).

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 POST \
  --url https://{host}/api/v1/@apostrophecms/blog/{_id}/share \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "share": true
}'

{
  "title": "",
  "publishedAt": "2023-12-25",
  "_id": "<string>",
  "type": "<string>",
  "_author": [
    {}
  ],
  "_category": [
    {}
  ],
  "slug": "",
  "visibility": "public",
  "scheduledPublish": "<string>",
  "scheduledUnpublish": "<string>",
  "excerpt": "",
  "featuredImage": {
    "items": []
  },
  "main": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "afterContent": {
    "items": [
      {
        "type": "@apostrophecms/rich-text",
        "content": "<p>Hello from the API.</p>"
      }
    ]
  },
  "postFontOverrides": [],
  "seoTitle": "",
  "seoDescription": "",
  "seoImage": {
    "items": []
  },
  "archived": false,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "_url": "<string>",
  "_parentUrl": "<string>",
  "_parentSlug": "<string>",
  "_parent": {},
  "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)

Share a blog post’s draft

Authorizations

Scopes

Path Parameters

Body

Response