Overview

The Airogel CMS API v1 provides RESTful JSON endpoints for programmatically managing content, templates, assets, and site structure. This API is designed to support external integrations such as content importers, headless CMS clients, and automation tools.

Base URL: https://api.airogelcms.com/v1/accounts/:account_id

Import Order of Operations

When importing content from external sources (e.g., WordPress), follow this order:

Create Blueprint(s) - Define field structures first
Create Collection(s) - Reference existing blueprints via blueprint_handle
Upload Assets - Images, videos, and other media files
Create Entries - Content items referencing collections and blueprints
Create Navigation - Menu structures (optional)
Upload Templates - Liquid templates for rendering
Create Globals - Site-wide settings (optional)

This order ensures all dependencies are resolved when creating content.

Authentication

All API requests require token-based authentication via the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

API tokens can be created in the Airogel CMS dashboard under Settings > API Tokens.

Authentication Errors

Status	Description
401 Unauthorized	Missing or invalid API token
404 Not Found	Account not found or user doesn't have access

Response Format

Successful Responses

Single resource:

{
  "id": "prefix_abc123",
  "handle": "my-resource",
  "title": "My Resource",
  "created_at": "2025-01-08T12:00:00Z",
  "updated_at": "2025-01-08T12:00:00Z"
}

List with pagination:

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 47,
    "per_page": 20,
    "next_page": 2,
    "prev_page": null
  }
}

Error Responses

Validation errors (422):

{
  "error": "Validation failed",
  "details": {
    "handle": ["can't be blank", "has already been taken"],
    "name": ["can't be blank"]
  }
}

Not found (404): Empty response body

Unauthorized (401): Empty response body

Resource IDs

Resources can be referenced by either:

Prefix ID: A unique identifier like clctn_abc123, cnety_xyz789
Handle: A URL-friendly slug like posts, my-first-post

Both work interchangeably in all endpoints that accept an :id parameter.

Available Endpoints

The API is organized into the following resource categories:

Blueprints - Define field schemas for content
Collections - Group and organize content entries
Entries - Individual content items
Assets - File uploads and media
Templates - Liquid templates for rendering
Navigations - Menu structures
Globals - Site-wide settings
Forms - Form configurations

Quick Start Example

WordPress Import Workflow

Here's a complete example of importing content from WordPress:

1. Upload Assets

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "file=@photo.jpg" \
  -F "path=uploads/2024/03" \
  "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/assets"

2. Create Blueprint

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "WordPress Post",
    "fields": [
      {"handle": "body", "display": "Body", "type": "rich_text", "position": 1},
      {"handle": "excerpt", "display": "Excerpt", "type": "text", "position": 2},
      {"handle": "featured_image", "display": "Featured Image", "type": "image", "position": 3}
    ]
  }' \
  "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/blueprints"

3. Create Collection

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog Posts",
    "handle": "posts",
    "routing": "blog/:handle",
    "blueprint_handle": "wordpress-post"
  }' \
  "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/collections"

4. Create Entry

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "my-post-slug",
    "title": "My WordPress Post",
    "published": true,
    "published_at": "2024-03-15T10:00:00Z",
    "body": "Post content here...",
    "excerpt": "Post summary",
    "featured_image": "uploads/2024/03/photo.jpg"
  }' \
  "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/collections/posts/entries"

Rate Limits

Currently no rate limits are enforced, but this may change in the future. Please be respectful with API usage.

Changelog

2026-02-09: Added position field for manual entry ordering in orderable collections
2026-01-10: Added Collection Index Pages with pagination support
2025-01-08: Added Forms endpoint for managing form configurations
2025-01-08: Added date-based routing support (:year, :month, :day placeholders)
2025-01-08: Initial release with core endpoints