> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List all Posts
> Returns a list of published Posts. This endpoint is only available in Spree 5.2 or later.
## OpenAPI
````yaml /api-reference/storefront.yaml get /api/v2/storefront/posts
openapi: 3.0.3
info:
version: 2.0.0
title: Storefront API
description: >-
Storefront API is a modern REST API based on the [JSON API
spec](https://jsonapi.org/) which provides you with all the necessary
endpoints to build amazing user interfaces either in JavaScript frameworks
or native mobile libraries.
Import to
[Postman](https://raw.githubusercontent.com/spree/spree/main/docs/api-reference/storefront.yaml)
contact:
name: Vendo Connect Inc.
url: https://spreecommerce.org
email: hello@spreecommerce.org
license:
name: BSD-3-Clause
url: https://github.com/spree/spree/blob/main/LICENSE.md
servers:
- url: https://demo.spreecommerce.org
description: demo
- url: http://localhost:3000
description: localhost
security: []
tags:
- name: Account
- name: Account / Address
- name: Account / Credit Cards
- name: Account / Orders
- name: Cart
- name: Cart / Line Items
- name: Cart / Coupons
- name: Cart / Other
- name: Checkout
- name: Checkout / State
- name: Checkout / Shipments
- name: Checkout / Payments
- name: Checkout / Store Credit
- name: Stripe
- name: Adyen
- name: Countries
- name: Digital Downloads
- name: Order Status
- name: Products
- name: Variants
- name: Stores
- name: Policies
- name: Taxons
- name: Vendors
- name: Wishlists
- name: Wishlists / Wished Items
paths:
/api/v2/storefront/posts:
get:
tags:
- Posts
summary: List all Posts
description: >-
Returns a list of published Posts. This endpoint is only available in
Spree 5.2 or later.
operationId: posts-list
parameters:
- $ref: '#/components/parameters/FilterByIds'
- in: query
name: filter[title]
schema:
type: string
example: Hello World
description: Filter Posts by title
- in: query
name: filter[post_category_id]
schema:
type: string
example: '1'
description: Filter Posts by Post Category ID
- in: query
name: filter[post_category_slug]
schema:
type: string
example: news
description: Filter Posts by Post Category slug
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PerPageParam'
- in: query
name: sort
schema:
type: string
enum:
- id
- '-id'
- title
- '-title'
- published_at
- '-published_at'
- created_at
- '-created_at'
- updated_at
- '-updated_at'
example: '-published_at'
description: >-
Sort posts by attribute. Prefix with "-" for descending order.
Available options: id, title, published_at, created_at, updated_at
- in: query
name: include
schema:
type: string
example: post_category
description: 'Include related resources (available: post_category)'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Post'
meta:
$ref: '#/components/schemas/ListMeta'
links:
$ref: '#/components/schemas/ListLinks'
examples:
success:
value:
data:
- id: '1'
type: post
attributes:
title: Hello World
slug: hello-world
published_at: '2025-08-11T21:03:00.000Z'
meta_title: ''
meta_description: ''
created_at: '2025-08-11T21:03:00.128Z'
updated_at: '2025-08-27T10:09:23.007Z'
excerpt: null
content: This is a test post
content_html: >-
\n
description: This is a test post
shortened_description: This is a test post
author_name: Spree Admin
post_category_title: News
tags: []
image_url: null
relationships:
post_category:
data:
id: '3'
type: post_category
meta:
count: 1
total_count: 1
total_pages: 1
links:
self: http://localhost:3000/api/v2/storefront/posts
next: http://localhost:3000/api/v2/storefront/posts?page=1
prev: http://localhost:3000/api/v2/storefront/posts?page=1
last: http://localhost:3000/api/v2/storefront/posts?page=1
first: http://localhost:3000/api/v2/storefront/posts?page=1
components:
parameters:
FilterByIds:
in: query
name: filter[ids]
schema:
type: string
example: 1,2,3
description: Fetch only resources with corresponding IDs
PageParam:
name: page
in: query
description: Number of requested page when paginating collection
schema:
type: integer
example: 1
PerPageParam:
name: per_page
in: query
description: Number of requested records per page when paginating collection
schema:
type: integer
example: 25
schemas:
Post:
type: object
title: Post
description: >-
Post represents a blog post or news article that can be displayed on the
storefront.
properties:
id:
type: string
example: '1'
type:
type: string
default: post
attributes:
type: object
properties:
title:
type: string
example: Hello World
description: Title of the post
slug:
type: string
example: hello-world
description: URL-friendly identifier for the post
published_at:
type: string
format: date-time
example: '2025-08-11T21:03:00.000Z'
description: Date and time when the post was published
nullable: true
meta_title:
type: string
example: ''
description: SEO meta title
nullable: true
meta_description:
type: string
example: ''
description: SEO meta description
nullable: true
created_at:
$ref: '#/components/schemas/Timestamp'
updated_at:
$ref: '#/components/schemas/Timestamp'
excerpt:
type: string
example: null
description: Short excerpt of the post content
nullable: true
content:
type: string
example: This is a test post
description: Plain text content of the post
nullable: true
content_html:
type: string
example: |
description: HTML formatted content of the post
nullable: true
description:
type: string
example: This is a test post
description: Description of the post
nullable: true
shortened_description:
type: string
example: This is a test post
description: Shortened description of the post
nullable: true
author_name:
type: string
example: Spree Admin
description: Name of the post author
nullable: true
post_category_title:
type: string
example: News
description: Title of the associated post category
nullable: true
tags:
type: array
items:
type: string
example: []
description: List of tags associated with the post
image_url:
type: string
example: null
description: URL of the post's featured image
nullable: true
relationships:
type: object
properties:
post_category:
type: object
properties:
data:
type: object
properties:
id:
type: string
example: '3'
type:
type: string
example: post_category
required:
- title
- slug
- created_at
- updated_at
required:
- id
- type
- attributes
ListMeta:
type: object
x-internal: false
title: Pagination Meta
properties:
count:
type: number
example: 7
description: Number of items on the current listing
total_count:
type: number
example: 145
description: Number of all items matching the criteria
total_pages:
type: number
example: 10
description: Number of all pages containing items matching the criteria
ListLinks:
x-internal: false
type: object
title: Pagination Links
properties:
self:
type: string
description: URL to the current page of the listing
next:
type: string
description: URL to the next page of the listing
prev:
type: string
description: URL to the previous page of the listing
last:
type: string
description: URL to the last page of the listing
first:
type: string
description: URL to the first page of the listing
Timestamp:
type: string
format: date-time
example: '2020-02-16T07:14:54.617Z'
x-internal: false
title: Time Stamp
x-examples:
example-1: '2020-02-16T07:14:54.617Z'
````