Skip to content

Import a blog post from a markdown file

POST
/stores/{storeRef}/blog/posts/import/markdown
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/blog/posts/import/markdown \
--header 'Content-Type: multipart/form-data' \
--header 'x-api-key: <x-api-key>' \
--form markdown_file=@file \
--form featured_image=@file \
--form inline_images=@file \
--form title=example \
--form slug=example \
--form status=draft \
--form should_publish=true

Creates a post from a markdown file with frontmatter, uploading the referenced images, converting the markdown to HTML, generating the table of contents, creating or linking categories and tags, and linking suggested products. A post with the same slug is updated instead of duplicated. In the response, categories_created and tags_created are currently always 0. The post is a draft unless status or should_publish says otherwise. Send the request as multipart/form-data.

Required scopes: write:blog

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typemultipart/form-data
object
markdown_file
required

The markdown file, with frontmatter.

string format: binary
featured_image

The featured image referenced by the frontmatter.

string format: binary
inline_images

Images referenced from the markdown body, up to 20.

Array<string>
<= 20 items
title

Overrides the title from the frontmatter.

string
slug

Overrides the slug from the frontmatter.

string
status

Publication status. Defaults to draft.

string
Allowed values: draft published
should_publish

Publishes the post immediately, overriding status.

boolean
Media typeapplication/json
object
blog_post
required

The imported post.

object
content

Post body as HTML, or null when empty.

string
nullable
toc

Table of contents generated from the headings in content.

Array<object>
nullable
object
id
required

Anchor ID of the heading.

string
level
required

Heading level, from 1 to 6.

number
textContent
required

Text of the heading.

string
pos
required

Position of the heading in the post content.

number
excerpt

Short summary shown in listings, or null.

string
nullable
featured_image_url

URL of the featured image, or null.

string
nullable
seo_metadata

SEO title and description. Present only when requested with include_seo_metadata.

object
meta_title
required

Page title for search engines, or null.

string
nullable
meta_description
required

Page description for search engines, or null.

string
nullable
status
required

Publication status. Only published posts are visible on the storefront list; unlisted posts are reachable by their link.

string
Allowed values: draft published scheduled unlisted
categories

Categories of the post.

Array<object>
object
id
required

ID.

number
name
required

Display name.

string
slug
required

URL slug, unique within the store.

string
description

Description. Present on categories only; null when none is set.

string
nullable
color

Hex colour such as #ff6600. Present on categories only; null when none is set.

string
nullable
sort_order

Manual position in the category list. Present on categories only.

number
nullable
created_at

When it was created, as an ISO 8601 timestamp.

string
nullable
updated_at

When it was last updated, as an ISO 8601 timestamp. Present on categories only.

string
nullable
tags

Tags of the post.

Array<object>
object
id
required

ID.

number
name
required

Display name.

string
slug
required

URL slug, unique within the store.

string
description

Description. Present on categories only; null when none is set.

string
nullable
color

Hex colour such as #ff6600. Present on categories only; null when none is set.

string
nullable
sort_order

Manual position in the category list. Present on categories only.

number
nullable
created_at

When it was created, as an ISO 8601 timestamp.

string
nullable
updated_at

When it was last updated, as an ISO 8601 timestamp. Present on categories only.

string
nullable
product_ids

IDs of the products recommended in the post, in display order. Present on single-post responses.

Array<number>
id
required

Post ID.

number
title
required

Title.

string
slug
required

URL slug, unique within the store.

string
is_featured

Whether the post is marked as featured.

boolean
scheduled_at

When a scheduled post will be published, as an ISO 8601 timestamp, or null.

string
nullable
published_at

When the post was published, as an ISO 8601 timestamp, or null while unpublished.

string
nullable
author_id

ID of the user who created the post, or null (for example when created with an API key).

string
nullable
author_name

Name or email of the author. Present when the author is known and, on lists, when include_author is set.

string
view_count

Number of storefront views.

number
nullable
reading_time

Estimated reading time in minutes.

number
nullable
created_at

When the post was created, as an ISO 8601 timestamp.

string
updated_at

When the post was last updated, as an ISO 8601 timestamp.

string
deleted_at

When the post was deleted, or null. Deleted posts are not returned.

string
nullable
missing_image_files
required

File names of the missing images.

Array<string>
images_uploaded
required

Number of new images uploaded.

number
images_reused
required

Number of existing images reused when an existing post was updated.

number
images_missing
required

Number of images referenced in the markdown that were not among the uploaded files.

number
categories_created
required

Number of categories created. Currently always 0, whatever the import created.

number
tags_created
required

Number of tags created. Currently always 0, whatever the import created.

number
message
required

A readable confirmation.

string

Example

{
"blog_post": {
"status": "draft"
}
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}