Skip to main content
GET
/
posts
List All Posts
curl --request GET \
  --url https://api.buttercms.com/v2/posts/ \
  --header 'Authorization: <api-key>'
{
  "meta": {
    "count": 25,
    "next_page": 3,
    "previous_page": 1
  },
  "data": [
    {
      "url": "http://www.example.com/blog/this-is-a-blog-post",
      "created": "2020-10-08T18:29:19.987936Z",
      "updated": "2020-10-09T15:49:54.580309Z",
      "published": "2020-10-08T18:08:00Z",
      "author": {
        "first_name": "API",
        "last_name": "Test",
        "email": "apitest@buttercms.com",
        "slug": "api-test",
        "bio": "This is my bio.",
        "title": "API",
        "linkedin_url": "https://www.linkedin.com/in/API",
        "facebook_url": "https://www.facebook.com/API",
        "twitter_handle": "buttercmsapi",
        "profile_image": "https://buttercms.com/api.png"
      },
      "categories": [
        {
          "name": "test category",
          "slug": "test-category"
        }
      ],
      "tags": [
        {
          "name": "test tag",
          "slug": "test-tag"
        }
      ],
      "featured_image": null,
      "featured_image_alt": "",
      "slug": "this-is-a-blog-post",
      "title": "This is a blog post",
      "body": "<p class=\"\">This is a blog post to test the API.</p>",
      "summary": "This is a blog post to test the API.",
      "seo_title": "This is a blog post",
      "meta_description": "This is a blog post to test the API.",
      "status": "published"
    }
  ]
}
Retrieve a paginated list of all published blog posts, automatically sorted by publication date with the newest posts appearing first. This endpoint is ideal for building blog listing pages, RSS feeds, or content archives. Performance Optimization: Use the exclude_body=true parameter when building post listing pages to significantly reduce response size by excluding the full post content. This improves loading performance while still providing titles, summaries, metadata, and author information needed for listing displays.

Authorizations

Authorization
string
header
required

Set the Authorization header to Token your_read_api_token.

Example: Authorization: Token abc123def456

Note: The header value includes the Token prefix.

You can access your API token from your settings page.

Query Parameters

page
integer
default:1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: x >= 1
page_size
integer
default:10

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: 1 <= x <= 100
limit
integer
default:10

Maximum number of items to return for offset-based pagination.

Mutually exclusive with page/page_size parameters.

Required range: 1 <= x <= 100
offset
integer
default:0

Number of items to skip before starting to return results.

Mutually exclusive with page/page_size parameters.

Required range: x >= 0
preview
enum<integer>
default:0

Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1. If you are trying to view a scheduled page for which the most recent page version is published, you must pass the preview parameter to see the scheduled changes.

Set to 1 to access unpublished/draft collection items. Useful for staging environments.

Available options:
0,
1
exclude_body
boolean
default:false

When true, excludes the full post body from the response.

Performance benefit: Significantly reduces response size when displaying lists of blog posts.

author_slug
string

Filter posts by an author's slug.

category_slug
string

Filter posts by a category's slug.

tag_slug
string

Filter posts by a tag's slug.

auth_token
string

Your ButterCMS read API token

Response

Success - Blog Posts Retrieved

Returns a list of blog posts matching the specified criteria. Posts are sorted by publish date with the most recent posts first.

Blog posts response using page-based pagination (default)

meta
object
required
data
object[]
required

Array of blog post objects sorted by publish date (newest first)