Airogel CMS Docs

Globals are site-wide values available in every template, such as footer text, social links, contact details or a logo. Each global has its own blueprint (field schema) and one set of values.

Operations

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

:id is the global's stgbl_ ID or handle.

Writable fields

Field	Type	Required	Description
`name`	string	yes	Display name. The field is `name`, not `title`.
`handle`	string	yes	Identifier used in Liquid. Use snake_case, for example `site_settings`. POST with an existing handle updates that global.
`fields`	array	no	POST only. The global's field definitions, in the same format as blueprint fields, and a full replacement. May also be sent as `blueprint.fields`.
`<field_handle>`	varies	no	A value for each field, as a top-level key. The formats are the same as for entries.

Parameters

Name	Type	Required	Description
`account_id`	string	Required	Path. Your account prefix ID (`acct_...`).
`id`	string	Optional	Path, for show/update/delete. Global `stgbl_` 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.
`name`	string	Required	Body. Display name.
`handle`	string	Required	Body. snake_case identifier. POST with an existing handle updates it.
`fields`	array	Optional	Body, POST only. Full list of field definitions `{handle, type, display, position, options}`.
	varies	Optional	Body. The value for that field.

Request Example

# Create a global with its fields and values in one call
curl -X POST "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/globals" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Footer",
    "handle": "footer",
    "fields": [
      {"handle": "copyright", "display": "Copyright", "type": "text"},
      {"handle": "social_links", "display": "Social Links", "type": "dictionary"}
    ],
    "copyright": "2026 My Company",
    "social_links": {"mastodon": "https://mastodon.social/@example"}
  }'

# Update values only (PUT/PATCH ignores "fields")
curl -X PATCH "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/globals/footer" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"copyright": "2026 My Company, Inc."}'

# Change the schema: POST again with the same handle and the COMPLETE field list
curl -X POST "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/globals" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Footer",
    "handle": "footer",
    "fields": [
      {"handle": "copyright", "display": "Copyright", "type": "text"},
      {"handle": "social_links", "display": "Social Links", "type": "dictionary"},
      {"handle": "show_newsletter", "display": "Show Newsletter Signup", "type": "toggle"}
    ]
  }'

Response Example

// Single global (show, create, update). List items have the same shape.
{
  "id": "stgbl_9dKs4Tx",
  "handle": "footer",
  "name": "Footer",
  "blueprint_handle": "footer",
  "fields": {
    "copyright": "2026 My Company",
    "social_links": { "mastodon": "https://mastodon.social/@example" }
  },
  "created_at": "2026-09-12T10:00:00Z",
  "updated_at": "2026-09-12T10:00:00Z",
  "blueprint": {
    "id": "blprt_2wEr6Yu",
    "handle": "footer",
    "title": "Footer",
    "fields": [
      { "handle": "copyright", "display": "Copyright", "type": "text", "position": 0, "options": {} },
      { "handle": "social_links", "display": "Social Links", "type": "dictionary", "position": 1, "options": {} }
    ],
    "created_at": "2026-09-12T10:00:00Z",
    "updated_at": "2026-09-12T10:00:00Z"
  },
  "copyright": "2026 My Company",
  "social_links": { "mastodon": "https://mastodon.social/@example" }
}

// List
{
  "data": [ { "id": "stgbl_9dKs4Tx", "handle": "footer", "name": "Footer", "...": "same fields as above" } ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1,
    "next_page": null,
    "prev_page": null
  }
}

Additional Notes

Response layout. fields in a global response is an object of stored values keyed by field handle. It is not the list of field definitions. The definitions are in blueprint.fields. The same values are also repeated as top-level keys in rendered form. For image and entity fields, the rendered form is the URL or the expanded entry, while fields holds the raw stored value.

Schema changes. fields is read only on POST, and it replaces the whole list: fields you leave out are removed along with their values. PUT/PATCH changes name, handle and values only. To change the schema of an existing global, POST again with its handle, its name and the full field list.

Blueprint. When you create a global with fields, a blueprint is created for it. It is named after the global's handle, with _2 and so on appended if that handle is taken. Without fields, the global gets an empty blueprint.

Handles. The handle becomes a Liquid variable name, so use snake_case. A hyphenated handle cannot be referenced as a variable. REST converts spaces to hyphens (for example "Site Settings" becomes site-settings) but does not reject hyphens.

Unknown keys are ignored. Only keys matching a field handle are saved.

Common uses: site settings (logo, tagline, contact info), footer content, social links, analytics snippets (in a raw_html field) and feature toggles. See Liquid Templates for using globals in templates.