Skip to content

List blog posts

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

Returns a page of the store’s published blog posts, each with its categories and tags. Page with limit and offset, filter by category_slug, tag_slug, is_featured, search or a date range, and sort with sort_by and sort_order. Set include_author to add the author’s name and include_seo_metadata to add SEO fields. The response currently includes merchant-side fields such as author_id, view_count and deleted_at.

storeRef
required
string

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

id
number

Return only the post with this ID.

slug
string

Return only the post with this slug.

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

Media typeapplication/json
object
data
required
Array<object>
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
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

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