Airogel CMS Docs

Assets are uploaded files, such as images, documents, video and audio. They are organized into folders by path. Entries reference them from image fields by asset ID or by path.

Operations

GET /v1/accounts/:account_id/assets - List assets
GET /v1/accounts/:account_id/assets/:id - Get one asset
POST /v1/accounts/:account_id/assets - Create a asset
PUT / PATCH /v1/accounts/:account_id/assets/:id - Update a asset
DELETE /v1/accounts/:account_id/assets/:id - Delete a asset (returns 204)

:id must be the asset's actast_ prefix ID. Assets have no handle. Lists are sorted by path, then filename.

Uploading

Multipart form data is best for binary files:

POST /v1/accounts/:account_id/assets
Content-Type: multipart/form-data

file=<binary>
path=uploads/2026/09
replace=false

Base64 JSON is also accepted. The body must be wrapped in asset:

POST /v1/accounts/:account_id/assets
Content-Type: application/json

{
  "asset": {
    "filename": "photo.jpg",
    "content_type": "image/jpeg",
    "path": "uploads/2026/09",
    "data": "/9j/4AAQSkZJRgABAQ...",
    "replace": false
  }
}

Uploading from a URL, chunked uploads, direct-to-storage uploads and browser upload sessions for very large files are available only through MCP and the dashboard.

Duplicates

An asset is identified by path plus filename. If you upload a file whose name already exists at that path, the response is 409 Conflict with the existing asset, and nothing is changed. Send replace=true to swap in the new file instead. The asset keeps its ID, and entries that use it get the new file. The response is then 200.

Parameters

Name	Type	Required	Description
`account_id`	string	Required	Path. Your account prefix ID (`acct_...`).
`id`	string	Optional	Path, for show/update/delete. Asset `actast_` prefix ID. Handles are not supported.
`path`	string	Optional	Query, list only. Exact folder path, for example `uploads/2026/09`.
`filename`	string	Optional	Query, list only. Case-insensitive substring match on the filename.
`content_type`	string	Optional	Query, list only. Exact MIME type, or a wildcard such as `image/*`.
`page`	integer	Optional	Query, list only. Page number, starting at 1. The page size is fixed at 20.
`file`	file	Optional	Body (multipart). The file to upload. On update, replaces the asset's file.
`path`	string	Optional	Body. Folder path (`asset.path` in JSON). On update, moves the asset.
`replace`	boolean	Optional	Body, create only (`asset.replace` in JSON). Replace an existing file with the same path and filename instead of returning 409.
`asset.filename`	string	Optional	Body (JSON). Filename. Required for base64 uploads.
`asset.content_type`	string	Optional	Body (JSON). MIME type, for example `image/png`.
`asset.data`	string	Optional	Body (JSON). Base64-encoded file content. On update, replaces the file.

Request Example

# List images in one folder
curl "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/assets?path=uploads/2026/09&content_type=image/*" \
  -H "Authorization: Bearer $API_TOKEN"

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

# Replace an existing file at the same path
curl -X POST "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/assets" \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "file=@photo.jpg" \
  -F "path=uploads/2026/09" \
  -F "replace=true"

# Base64 JSON upload
curl -X POST "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/assets" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": {
      "filename": "logo.png",
      "content_type": "image/png",
      "path": "brand",
      "data": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  }'

# Move an asset to another folder
curl -X PATCH "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/assets/actast_5hTq2Wm" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "images/blog"}'

# Delete
curl -X DELETE "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/assets/actast_5hTq2Wm" \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

// Single asset (show, create, update) is wrapped in "asset"
{
  "asset": {
    "id": "actast_5hTq2Wm",
    "filename": "photo.jpg",
    "path": "uploads/2026/09",
    "content_type": "image/jpeg",
    "byte_size": 245678,
    "width": 1600,
    "height": 900,
    "alt": null,
    "caption": null,
    "credit": null,
    "license": null,
    "created_at": "2026-09-15T09:58:00Z",
    "updated_at": "2026-09-15T09:58:00Z",
    "full_path": "uploads/2026/09/photo.jpg",
    "url": "https://api.airogelcms.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsi.../photo.jpg",
    "checksum": "k3J8f0pX2m9QwZr1bT4uYg=="
  }
}

// List
{
  "data": [
    {
      "id": "actast_5hTq2Wm",
      "filename": "photo.jpg",
      "path": "uploads/2026/09",
      "content_type": "image/jpeg",
      "byte_size": 245678,
      "width": 1600,
      "height": 900,
      "alt": null,
      "caption": null,
      "credit": null,
      "license": null,
      "created_at": "2026-09-15T09:58:00Z",
      "updated_at": "2026-09-15T09:58:00Z",
      "full_path": "uploads/2026/09/photo.jpg",
      "url": "https://api.airogelcms.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsi.../photo.jpg",
      "checksum": "k3J8f0pX2m9QwZr1bT4uYg=="
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}

// 409 - same path and filename already exists (no replace)
{
  "error": "An asset with this filename already exists at this path",
  "created": false,
  "asset": { "id": "actast_5hTq2Wm", "filename": "photo.jpg", "path": "uploads/2026/09", "...": "..." }
}

// 422
{
  "errors": ["Filename can't be blank"]
}

Additional Notes

Using assets in entries. Set an image field to the asset's actast_ ID or its path/filename, for example "featured_image": "uploads/2026/09/photo.jpg". In entry responses, image values come back as the image's URL path, not the asset object. See Entries.

What update can change. PUT/PATCH can move an asset (path) or replace its file (file or asset.data). Descriptive metadata (alt, caption, credit, license) appears in responses but is edited in the dashboard or through MCP.

Response fields. url is an absolute URL to the file. full_path is path/filename. width and height are set for images once they have been analyzed and are null otherwise. checksum is the stored file's checksum, useful for detecting changes.

Error shape. Unlike most resources, asset validation errors are a flat list, {"errors": [...]}.

File types. Common image, document, audio and video formats are all accepted.