Blog Posts

Import a post from Markdown or MDX

Creates a blog post from a Markdown or MDX document with front matter. Send JSON, the raw document (text/markdown, at most 5 MB by default), or a multipart upload with the file and its images.

Images: featuredImage in the front matter and every image in the body may be an https:// URL (fetched, at most 15 MB by default), a library image’s slug, a filename posted with the file (image, up to 10), or generate: <description> with generateImages (at most 4 per import).

Media on an API key: a new image (a URL, a posted file or generate:) needs content:images:write, a new video content:videos:write and content:videos:publish; a library slug needs content:images:read / content:videos:read. The blog scopes don’t cover media, and the refusal names the missing scope.

Publishing: publish=true publishes only when the caller may (a key needs content:blog:publish); otherwise the post is saved as a draft. An MDX import is always a draft.

Removing an import: delete the post by the draft _id the import answered. On an API key that needs content:blog:delete.

Access: an API key with content:blog:write, or content:blog:all, or content:all, or admin:all, or a signed-in user holding the blog:import-markdown permission. Other callers get 403.

Rate limit: the key’s own writes-per-minute limit, set when the key is created (default 120), and 30 imports and validations a minute per caller: whichever runs out first answers 429 with Retry-After.

POST

@apostrophecms

blog

from-markdown

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/blog/from-markdown \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "markdown": "---\ntitle: \"Our spring update\"\nexcerpt: \"What changed this season.\"\n---\n\n## What’s new\n\nThe body, in Markdown.\n"
}
'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const blogImportResult = await site.blogPosts().importBlogPost({ markdown: '---\ntitle: "Our spring update"\nexcerpt: "What changed this season."\n---\n\n## What’s new\n\nThe body, in Markdown.\n' });

use Fetchski\AttractCmsLaravel\Facades\Attract;

$blogImportResult = Attract::blogPosts()->importBlogPost(markdown: '---
title: "Our spring update"
excerpt: "What changed this season."
---

## What’s new

The body, in Markdown.
');

{
  "_id": "clx8k2m0a0011abcd1234efgh:en:draft",
  "type": "@apostrophecms/blog",
  "title": "Five things we learned this year",
  "slug": "five-things-we-learned-this-year",
  "_url": "https://www.example.com/blog/five-things-we-learned-this-year",
  "published": false
}

{
  "name": "invalid",
  "message": "Send the Markdown as `markdown` (a string).",
  "data": {}
}

{
  "name": "invalid",
  "message": "The API key is not valid.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: forms:read.",
  "data": {}
}

{
  "name": "invalid",
  "message": "An uploaded file is too large (max 15 MB per file)."
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "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

Query Parameters

format

enum<string>

Read a raw or JSON body as mdx.

Available options:

md,

mdx

publish

boolean

The same as the body’s publish.

generateImages

boolean

The same as the body’s generateImages.

_ai

boolean

The same as the body’s _ai.

Body

markdown

string

required

The whole document: YAML front matter between --- lines, then the Markdown body. title is the one required front matter key; slug, publishedAt, authorName (or authorEmail), category, excerpt, featuredImage (+ featuredImageAlt), seoTitle, seoDescription and splitDepth are optional (the Markdown template, getBlogMarkdownTemplate, names every key). Body headings start at ##: the title is the post’s only <h1>.

Example:

"---\ntitle: \"Our spring update\"\nexcerpt: \"What changed this season.\"\n---\n\n## What’s new\n\nThe body, in Markdown.\n"

format

enum<string>

default:md

How to read markdown: plain Markdown (md) or MDX (mdx).

Available options:

md,

mdx

publish

boolean

default:false

Publish the post when the caller may; otherwise (and by default) it is saved as a draft.

generateImages

boolean

default:false

Allow generate: image references (needs content:blog:generate-image on an API key). An import that generates images must finish them within 600 seconds, or it stops and leaves nothing behind (422 deadline).

_ai

boolean

default:false

Mark the post (and its generated images) as AI-written in its version history.

Response

The new post.

_id

string

required

type

string

required

Example:

"@apostrophecms/blog"

title

string

required

slug

string

required

published

boolean

required

False when it was saved as a draft.

_url

string

The post’s page.

cURL

curl --request POST \
  --url https://{host}/api/v1/@apostrophecms/blog/from-markdown \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "markdown": "---\ntitle: \"Our spring update\"\nexcerpt: \"What changed this season.\"\n---\n\n## What’s new\n\nThe body, in Markdown.\n"
}
'

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const blogImportResult = await site.blogPosts().importBlogPost({ markdown: '---\ntitle: "Our spring update"\nexcerpt: "What changed this season."\n---\n\n## What’s new\n\nThe body, in Markdown.\n' });

use Fetchski\AttractCmsLaravel\Facades\Attract;

$blogImportResult = Attract::blogPosts()->importBlogPost(markdown: '---
title: "Our spring update"
excerpt: "What changed this season."
---

## What’s new

The body, in Markdown.
');

{
  "_id": "clx8k2m0a0011abcd1234efgh:en:draft",
  "type": "@apostrophecms/blog",
  "title": "Five things we learned this year",
  "slug": "five-things-we-learned-this-year",
  "_url": "https://www.example.com/blog/five-things-we-learned-this-year",
  "published": false
}

{
  "name": "invalid",
  "message": "Send the Markdown as `markdown` (a string).",
  "data": {}
}

{
  "name": "invalid",
  "message": "The API key is not valid.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: forms:read.",
  "data": {}
}

{
  "name": "invalid",
  "message": "An uploaded file is too large (max 15 MB per file)."
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": {}
}

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Import a post from Markdown or MDX

Authorizations

Scopes

Query Parameters

Body

Response