Airogel CMS Docs

A blueprint is a field schema. It lists the fields an entry, global or navigation item has and the type of each field. Collections use blueprints for their entries, and globals embed one. See Content Modeling and the Field Types Reference.

Operations

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

:id is the blueprint's blprt_ ID or handle.

Blueprint fields

Field	Type	Required	Description
`title`	string	yes	Display name
`handle`	string	no	Generated from the title if you leave it out. A generated handle that collides gets `_2`, `_3` and so on appended. POST with an existing handle updates that blueprint.
`fields`	array	no	Field definitions (see below). This is the full list: fields you leave out are removed.

Field definition

Key	Type	Required	Description
`handle`	string	yes	Unique within the blueprint. This is the key used on entries and in Liquid.
`type`	string	yes	One of the 14 types below
`display`	string	no	Label. Defaults to the titleized handle. On update, leaving it out keeps the current label.
`position`	integer	no	Order in the editor. Defaults to the field's index in the array.
`options`	object	no	Type-specific settings (see below). On update, leaving it out keeps the field's existing options.

Field types

Type	Stores
`text`	Plain text
`rich_text`	Formatted HTML from the rich text editor
`raw_html`	Unprocessed HTML or embed code
`image`	One image asset
`video`	A video URL (for example YouTube or Vimeo) with optional ID and thumbnail
`gallery`	A list of images
`template`	A reference to a Liquid template
`entity`	A reference to one other entry, or several with `multiple`
`collection`	A dynamic list of entries from a collection
`toggle`	Boolean
`number`	Integer or decimal
`enumerate`	One choice from a fixed list (select or radio)
`list`	Repeatable list of values
`dictionary`	Key-value pairs

Responses always use these short names. Any other value returns 422 with path fields[i].type and the list of valid types.

Options

Type	Option	Description
`enumerate`	`enumerations`	Array of allowed values, for example `["draft", "review", "final"]`
`enumerate`	`display_as`	`select` (default) or `radio`
`entity`	`multiple`	`true` to allow several referenced entries. Default `false`.
`collection`	`collection_handle`	The collection to pull entries from
`collection`	`max_items`	Default 10
`collection`	`default_filter_field`, `default_filter_value`, `default_filter_operator`	Optional default filter
`number`	`number_type`	`decimal` (default) or `integer`
`number`	`decimal_places`	Rounding precision. Unset means unrestricted.
`list`, `dictionary`	`max_items`	Default 10
`gallery`	`max_items`	Default 20
any	`required`, `placeholder`, `help_text`, `input_type`	Used when the blueprint backs a form. See form_for.

Parameters

Name	Type	Required	Description
`account_id`	string	Required	Path. Your account prefix ID (`acct_...`).
`id`	string	Optional	Path, for show/update/delete. Blueprint `blprt_` ID or handle.
`handle`	string	Optional	Query, list only. Return only the record with exactly this handle.
`page`	integer	Optional	Query, list only. Page number, starting at 1. The page size is fixed at 20.
`title`	string	Required	Body. Display name.
`handle`	string	Optional	Body. Generated from the title if omitted. POST with an existing handle updates it.
`fields`	array	Optional	Body. Full list of field definitions `{handle, type, display, position, options}`. `[]` removes every field. Leave it out to keep the current fields.

Request Example

# List blueprints
curl "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/blueprints" \
  -H "Authorization: Bearer $API_TOKEN"

# Create a blueprint
curl -X POST "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/blueprints" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Blog Post",
    "handle": "blog_post",
    "fields": [
      {"handle": "body", "display": "Body", "type": "rich_text"},
      {"handle": "excerpt", "display": "Excerpt", "type": "text"},
      {"handle": "featured_image", "display": "Featured Image", "type": "image"},
      {"handle": "status", "display": "Status", "type": "enumerate",
       "options": {"enumerations": ["draft", "review", "final"], "display_as": "select"}},
      {"handle": "related_posts", "display": "Related Posts", "type": "entity",
       "options": {"multiple": true}}
    ]
  }'

# Update: send the COMPLETE field list. Fields left out are deleted with their values.
curl -X PUT "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/blueprints/blog_post" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {"handle": "body", "display": "Body", "type": "rich_text"},
      {"handle": "excerpt", "display": "Summary", "type": "text"},
      {"handle": "featured_image", "display": "Featured Image", "type": "image"},
      {"handle": "status", "display": "Status", "type": "enumerate"},
      {"handle": "related_posts", "display": "Related Posts", "type": "entity"},
      {"handle": "reading_time", "display": "Reading Time", "type": "number",
       "options": {"number_type": "integer"}}
    ]
  }'

# Rename without touching fields
curl -X PATCH "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/blueprints/blog_post" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Article"}'

Response Example

// Single blueprint (show, create, update)
{
  "id": "blprt_8xNw2Ls",
  "handle": "blog_post",
  "title": "Blog Post",
  "fields": [
    { "handle": "body", "display": "Body", "type": "rich_text", "position": 0, "options": {} },
    { "handle": "excerpt", "display": "Excerpt", "type": "text", "position": 1, "options": {} },
    { "handle": "featured_image", "display": "Featured Image", "type": "image", "position": 2, "options": {} },
    { "handle": "status", "display": "Status", "type": "enumerate", "position": 3,
      "options": { "enumerations": ["draft", "review", "final"], "display_as": "select" } },
    { "handle": "related_posts", "display": "Related Posts", "type": "entity", "position": 4,
      "options": { "multiple": true } }
  ],
  "created_at": "2026-09-01T14:00:00Z",
  "updated_at": "2026-09-01T14:00:00Z"
}

// List
{
  "data": [
    { "id": "blprt_8xNw2Ls", "handle": "blog_post", "title": "Blog Post", "fields": ["..."], "created_at": "2026-09-01T14:00:00Z", "updated_at": "2026-09-01T14:00:00Z" }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}

// 422 - bad field type
{
  "error": "Validation failed",
  "details": [
    { "path": "fields[1].type", "message": "\"richtext\" is not a field type; expected one of collection, dictionary, entity, enumerate, gallery, image, list, number, raw_html, rich_text, template, text, toggle, video" }
  ]
}

Additional Notes

fields is a full replacement. On update, fields are matched by handle. New handles are added and existing ones are updated. Any existing field not in the array is removed together with its stored values on every entry. Always fetch the blueprint first and send back every field you want to keep. "fields": [] removes all fields. Leaving fields out entirely leaves the schema untouched.

All or nothing. The title, handle and field list are validated before anything is written and saved in one transaction. A 422 means nothing changed.

Type names. Use the short names above. The long internal class names (for example BlueprintFieldRichText) are also accepted on input, but responses always use short names.

Deleting a blueprint deletes its fields and every value stored in them.

A blueprint can belong to only one collection, global or navigation. Attach it to a collection with blueprint_handle when you create the collection.