Skip to main content

​
Blog Post filters

Filter blog posts using these built-in parameters:
ParameterDescriptionExample
author_slugFilter by author’s slugauthor_slug=john-doe
category_slugFilter by category slugcategory_slug=technology
tag_slugFilter by tag slugtag_slug=javascript
Examples: 
# Filter by author
/v2/posts/?author_slug=john-doe

# Filter by category
/v2/posts/?category_slug=technology

# Filter by tag
/v2/posts/?tag_slug=javascript

# Combine filters
/v2/posts/?author_slug=john-doe&category_slug=tutorials

# Full request with multiple filters
curl "https://api.buttercms.com/v2/posts/?author_slug=john-doe&category_slug=tutorials&page_size=10&auth_token=YOUR_TOKEN"

​
Page Type filters

Filter pages using field-based filtering and ordering: Field Filtering: 
# Filter pages where the 'featured' field equals 'true'
/v2/pages/landing-page/?fields.featured=true

# Filter pages by category reference
/v2/pages/blog-post/?fields.category=technology

# Multiple field filters
/v2/pages/product/?fields.in_stock=true&fields.category=electronics

# Full request
curl "https://api.buttercms.com/v2/pages/landing-page/?fields.featured=true&auth_token=YOUR_TOKEN"
Ordering: 
# Order by published date descending (newest first)
/v2/pages/landing-page/?order=-published

# Order by a custom field ascending
/v2/pages/landing-page/?order=title

# Full request
curl "https://api.buttercms.com/v2/pages/landing-page/?order=-published&auth_token=YOUR_TOKEN"
Ordering Options: You can order by page-level fields like published or updated, or by any content field of the Page Type. Prepend - for descending order (e.g., -published for newest first).

​
Collection filters

Filter collection items using dynamic field filtering: 
# Filter collection by field
/v2/content/?keys=products&fields.category=software

# Filter by multiple fields
/v2/content/?keys=team-members&fields.department=engineering&fields.active=true

# Full request
curl "https://api.buttercms.com/v2/content/?keys=categories&fields.name=Technology&auth_token=YOUR_TOKEN"
JavaScript SDK: 
// Filter collection items
const result = await butter.content.retrieve(['products'], {
  'fields.category': 'software',
  'fields.in_stock': true
});

​
Combining filters with pagination

For optimal performance, combine filtering with pagination to fetch exactly what you need: 
const butter = Butter('YOUR_API_TOKEN');

// Fetch page 1 of tutorials by a specific author
const response = await butter.post.list({
  page: 1,
  page_size: 10,
  author_slug: 'john-doe',
  category_slug: 'tutorials',
  exclude_body: true
});
See Pagination for page-based and offset-based pagination options.