Skip to content

Get a blog post by slug

GET
/public/stores/{storeRef}/blog/posts/slug/{slug}
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/public/stores/example/blog/posts/slug/example?status=draft&sort_by=created_at&sort_order=asc&include_seo_metadata=false' \
--header 'x-store-preview: example' \
--header 'x-storefront-api-key: <x-storefront-api-key>'

Returns one published or unlisted post by its URL slug, with its categories, tags, recommended product IDs and metafields. The body is empty when no such post exists. Each request counts as a view of the post, except previews. A valid preview_token shows a post whatever its status and does not count a view. The response currently includes merchant-side fields such as author_id, view_count and deleted_at.

slug
required
string

The post’s URL slug.

storeRef
required
string

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

id
number

Return only the post with this ID.

status
string
Allowed values: draft published scheduled unlisted

Return only posts with this status.

category_id
number

Return only posts in the category with this ID.

category_slug
string

Return only posts in the category with this slug.

tag_id
number

Return only posts with the tag with this ID.

tag_slug
string

Return only posts with the tag with this slug.

is_featured
boolean

Return only featured (or only non-featured) posts.

search
string

Free-text search over title, content and excerpt.

date_from
string

Filter posts with any relevant date >= this value (ISO 8601)

date_to
string

Filter posts with any relevant date < this value (ISO 8601)

sort_by
string
Allowed values: created_at published_at title view_count

Field to sort by. The store list also accepts updated_at. Defaults to published_at.

sort_order
string
Allowed values: asc desc

Sort direction. Defaults to desc.

limit
number

Maximum number of posts to return. Defaults to 10.

offset
number

Number of posts to skip. Defaults to 0.

include_author
boolean

Include author details if available

include_seo_metadata
boolean

Example

true

Include SEO metadata in the response

preview_token
string

Signed preview token to bypass status filter for draft/scheduled posts

x-store-preview
required
string

The post, or an empty body when no post matches.

Media typeapplication/json
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>
metafields
required

The post’s metafields that are visible to the storefront, keyed by namespace.key.

object
key
additional properties
object
value
required

The value in the form its type defines. A reference type resolves to the referenced resource’s public data.

nullable
One of:
string
type
required

The metafield’s type, such as single_line_text_field or list.number_integer.

string
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

Example

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