Blog Listing Page

This guide covers the API patterns for building a blog listing page, regardless of your framework. You will learn how to fetch blogs, paginate results, filter by category or tag, search by title, and combine multiple filters.

If you are using a specific framework, check the dedicated guides for complete implementations:

Fetching blogs

The blog listing endpoint returns a paginated array of published blog posts. By default, results are sorted by publishedAt in descending order (newest first).

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.wrytze.com/api/v1/blogs?website_id=ws_your_website_id"

The response contains two top-level fields:

Each blog object in the data array includes the fields listed in the Quickstart response reference.

Pagination

Control pagination with the page and limit query parameters.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.wrytze.com/api/v1/blogs?website_id=ws_abc&page=2&limit=12"

The pagination object in the response provides everything you need to build navigation controls:

{
  "pagination": {
    "page": 2,
    "limit": 12,
    "total": 42,
    "pages": 4
  }
}

Building pagination links

Use the pagination metadata to determine when to show previous and next links:

// Previous page exists when page > 1
const hasPreviousPage = pagination.page > 1
const previousPage = pagination.page - 1

// Next page exists when current page < total pages
const hasNextPage = pagination.page < pagination.pages
const nextPage = pagination.page + 1

Category filtering

Filter blogs by category using the category query parameter with the category slug.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.wrytze.com/api/v1/blogs?website_id=ws_abc&category=technology"

The pagination.total in the response reflects the filtered count, so your pagination links automatically adjust.

Tag filtering

Filter blogs by tag using the tag query parameter with the tag slug.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.wrytze.com/api/v1/blogs?website_id=ws_abc&tag=react"

Search

Search for blogs by title using the search query parameter. The search is case-insensitive and matches partial titles.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.wrytze.com/api/v1/blogs?website_id=ws_abc&search=getting%20started"

Combining filters

Multiple filters can be used together in a single request. All filters are applied with AND logic, meaning results must match every specified filter.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://app.wrytze.com/api/v1/blogs?website_id=ws_abc&category=technology&tag=react&search=hooks&page=1&limit=10"

Query parameter reference

Here is a summary of all query parameters accepted by the blog listing endpoint:

Building a complete listing UI

Here is a framework-agnostic example of how to construct a listing page URL from user selections:

function buildBlogListingUrl(filters: {
  page?: number
  category?: string
  tag?: string
  search?: string
}): string {
  const params = new URLSearchParams()

  if (filters.page && filters.page > 1) {
    params.set('page', String(filters.page))
  }
  if (filters.category) {
    params.set('category', filters.category)
  }
  if (filters.tag) {
    params.set('tag', filters.tag)
  }
  if (filters.search) {
    params.set('search', filters.search)
  }

  const queryString = params.toString()
  return `/blog${queryString ? `?${queryString}` : ''}`
}

// Examples:
buildBlogListingUrl({ category: 'technology' })
// → "/blog?category=technology"

buildBlogListingUrl({ category: 'technology', page: 3 })
// → "/blog?category=technology&page=3"

buildBlogListingUrl({ search: 'react hooks', tag: 'react' })
// → "/blog?search=react+hooks&tag=react"

Sorting

Results are sorted by publishedAt in descending order by default. The most recently published blogs appear first. This sort order is not currently configurable through query parameters.

Error handling

When the API returns an error, the response includes a JSON body with an error field:

{
  "error": {
    "message": "Invalid or missing API key. Provide a valid key in the X-API-Key header.",
    "status": 401
  }
}

Common errors for the listing endpoint:

Next steps