Interacting with AstroPress Headlessly: A Developer's Guide to the API

The AstroPress theme is designed as a complete, high-performance blogging solution. However, its power extends beyond the pre-built theme. At its core, AstroPress is a Git-based content management system that exposes a comprehensive, secure REST API. This allows developers to interact with all site content programmatically, opening the door for powerful headless implementations.

This guide is for developers who want to bypass the AstroPress CMS and interact directly with the content API. It’s important to note that the public-facing API endpoints described here are read-only. They are designed to allow you to fetch and display the published content from your live website, not to create or modify it. Content creation and updates are managed through the AstroPress CMS or by directly committing changes to the site’s Git repository.

Whether you want to build a custom frontend, integrate with mobile apps, or sync content with other systems, this API is your entry point.

Core Concepts: Security and Authentication

Before making any requests, it’s critical to understand the security model. The AstroPress API is protected and is not open to the public.

To authenticate your requests, you must include your secret API key in one of two ways:

1. Authorization Header (Recommended):

   Authorization: Bearer YOUR_API_KEY
   

2. X-API-Key Header:

   X-API-Key: YOUR_API_KEY
   

This key is the BLOG_API_KEY defined in your server environment variables. Never expose this key on the client-side. All API requests should originate from a secure server environment.

Failure to provide a valid key will result in a 401 Unauthorized error.

API Endpoint Reference

The API is organized logically around your content types. All endpoints return JSON and support standard HTTP methods. The API also supports CORS for cross-origin requests.

Blog Posts

• Endpoint: /api/posts.json

• Method: GET

• Description: Retrieves a paginated list of all blog posts. The data is incredibly rich, including fully resolved author, category, and tag objects, as well as metadata like reading time and internal link analysis.

• Query Parameters:

  • page (number, default: 1): The page number for pagination.
  • perPage (number, default: 10): The number of posts to return per page.
  • sortBy (string, default: ‘date’): Field to sort by. Options: date, title.
  • sortOrder (‘asc’ | ‘desc’, default: ‘desc’): The sort direction.
  • search (string): A search term to filter posts by title, description, or body content.
  • category (string): Filter posts by a specific category ID.
  • tag (string): Filter posts by a specific tag ID.
  • featured (‘true’ | ‘false’): Filter for featured posts.
  • status (‘published’ | ‘draft’, default: ‘published’): Filter by post status.

Static Pages

• Endpoint: /api/pages.json

• Method: GET

• Description: Retrieves a list of all static pages (e.g., ‘About’, ‘Contact’) and legal documents.

• Query Parameters:

  • search (string): Filter pages by title, description, slug, or ID.
  • published (‘true’ | ‘false’): Filter by publication status.
  • noindex (‘true’ | ‘false’): Filter by noindex status.
  • type (‘page’ | ‘legal’): Filter by the type of page.

Authors, Categories, and Tags

These endpoints provide access to your content taxonomies and authors, complete with metadata like post counts.

• Endpoint: /api/authors.json
• Endpoint: /api/categories.json
• Endpoint: /api/tags.json
• Method: GET
• Description: Each endpoint retrieves a full list of its respective content type. The response includes valuable metadata, such as the number of posts associated with each item, recent activity, and more.
• Query Parameters: All three endpoints support a rich set of query parameters for searching, sorting (name, postCount), and pagination.

Affiliate Content

The API also provides granular access to your monetization entities.

• Endpoint: /api/affiliate-categories.json

  • Method: GET
  • Description: Retrieves a list of your affiliate product categories, including a count of how many products are in each.

• Endpoint: /api/affiliate-products/[category].json

  • Method: GET
  • Description: Retrieves all affiliate products belonging to a specific category slug. For example, a request to /api/affiliate-products/coffee-grinders.json would return all products in that category.

• Endpoint: /api/affiliate-comparisons/[category].json

  • Method: GET
  • Description: Retrieves all product comparison tables associated with a specific category slug.

A Headless Use Case: Building a Custom Front-End

Imagine you want to use AstroPress as a headless CMS for a new mobile app or a website built with a different framework.

Here is a conceptual workflow:

1. Fetch Posts: Your server would make an authenticated GET request to https://yourdomain.com/api/posts.json to get the latest blog posts.

2. Render Content: The JSON response provides all the data needed to render a post list, including title, description, author name, and image URLs.

3. Fetch Single Post: While the current API is designed for fetching lists, you could extend it by creating a new endpoint like /api/posts/[slug].json that retrieves a single post by its slug and includes the full body content.

4. Display Content: Your application would then parse the Markdown/MDX from the body field and render it to the screen.

This headless approach allows you to completely decouple your content management from your presentation layer, giving you ultimate flexibility.

Conclusion

The AstroPress API transforms your blog from a simple website into a powerful, headless content repository. By leveraging these secure and well-structured endpoints, you can go beyond the included theme to build custom applications, syndicate content across platforms, and integrate your blog into a wider digital ecosystem.

While the AstroPress CMS provides a fantastic user experience, the underlying API ensures that developers are never limited by it, offering a robust foundation for any custom project you can envision.