ApostropheCMS REST API

ApostropheCMS provides a comprehensive REST API for headless CMS functionality, enabling you to build modern applications with any frontend framework while managing content through Apostrophe's intuitive editing experience.

Getting Started

The REST API gives you programmatic access to all your content and media:

• Content Management: Create, read, update, and delete pages and pieces
• Media Operations: Upload, crop, and organize images and files
• Multilingual Support: Manage content across multiple locales
• Flexible Authentication: API keys for server-to-server, bearer tokens for client apps

Quick Start

All API endpoints follow RESTful conventions and return JSON responses. Most operations require authentication:

// Example: Fetch published articles
const response = await fetch('https://example.net/api/v1/article', {
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
});
const articles = await response.json();

Core API Documentation

Authentication

Learn about API keys, bearer tokens, and session cookies for authenticating your REST API requests.

Field Formats

Examples of how each field type appears in API responses, from simple strings to complex areas and relationships.

Content APIs

Piece Type REST API

Full CRUD operations for piece types with pagination, search, filtering, draft/publish workflows, and relationship queries.

Page Type REST API

Complete page management including tree navigation, publishing workflows, and page hierarchy operations.

Working with Rich Text

Handle rich text content including HTML filtering, inline images, and importing external content.

Media REST Endpoints

Upload, crop, and manage media files through dedicated endpoints for images, files, and attachments.

Internationalization

i18n REST Endpoints

Manage multilingual content with endpoints for locale information, cross-locale navigation, and document verification.

How to Use This Documentation

This REST API reference provides two complementary ways to work with the ApostropheCMS API:

Written Documentation (This Section)

The guides on this page and in the navigation are your comprehensive reference for understanding the API:

• Learn patterns and concepts with explanations and context
• Copy production-ready code examples into your application
• Understand field formats with detailed examples
• Read offline or on mobile when you need it

Start here if you're new to the API or building an integration.

API Explorer (Interactive Testing)

Once you understand the basics, use the API Explorer to test endpoints with your own data:

• Test live requests against your local or deployed ApostropheCMS instance
• Experiment with parameters and see real-time responses
• Validate your authentication setup before writing code
• Generate curl commands for quick testing

Open the API Explorer →

Tip: The written documentation and API Explorer show the same endpoints - use the written docs to learn, then the Explorer to test.

OpenAPI Specification

For advanced workflows, download our complete OpenAPI 3.0 specification:

• Import into your preferred API client (Insomnia, Bruno, HTTPie, etc.)
• Generate client libraries in any language
• Integrate with AI coding assistants
• Build custom tooling and automation

Download OpenAPI Spec

TIP

If Postman is your tool of choice, fork our collection to get started quickly with pre-configured requests and authentication.

Note: The OpenAPI specification and Postman collection cover the core ApostropheCMS API. As you add custom piece types to your project, you'll need to add corresponding endpoints. See the Piece Type REST API documentation for details on the endpoints available for your custom types.

Common Patterns

Querying Content

Retrieve published content with pagination and filtering:

const response = await fetch(
  'https://example.net/api/v1/article?page=1&perPage=10',
  {
    headers: { 'Authorization': 'Bearer your-token' }
  }
);

Creating Documents

Post new content with required fields:

const response = await fetch('https://example.net/api/v1/article', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    title: 'My New Article',
    slug: 'my-new-article'
  })
});

Working with Locales

Access content in specific locales using the aposLocale query parameter:

const response = await fetch(
  'https://example.net/api/v1/article?aposLocale=fr',
  {
    headers: { 'Authorization': 'Bearer your-token' }
  }
);

Need Help?

• Stack Overflow: Tag questions with apostrophe-cms
• Discord: Join our community chat
• GitHub: Report issues or contribute at apostrophecms/apostrophe

Ready to start building? Check out the authentication guide to set up your first API request.