Entries API
https://api.airogelcms.com/v1/accounts/:account_id/collections/:collection_id/entries
Entries are the individual content items in a collection, such as one blog post or one page. Each entry has a few core fields plus one value per field of its blueprint. Blueprint values are sent and returned as top-level keys on the entry.
Operations
- GET
/v1/accounts/:account_id/collections/:collection_id/entries- List entries - GET
/v1/accounts/:account_id/collections/:collection_id/entries/:id- Get one entry - POST
/v1/accounts/:account_id/collections/:collection_id/entries- Create a entry - PUT / PATCH
/v1/accounts/:account_id/collections/:collection_id/entries/:id- Update a entry - DELETE
/v1/accounts/:account_id/collections/:collection_id/entries/:id- Delete a entry (returns204)
:collection_id is the collection's clctn_ ID or handle. :id is the entry's cnety_ ID or handle. Handles are unique within a collection. Lists are sorted newest first by creation date.
Core fields
| Field | Type | Required | Description |
|---|---|---|---|
handle | string | yes | URL slug, unique within the collection. POST with an existing handle updates that entry. |
title | string | on create | Display title. Optional on update. |
published | boolean | no | Publicly visible. Default true. |
published_at | datetime | see description | ISO 8601. Required when the collection's routing uses :year, :month or :day. An unparseable value returns 422. |
include_in_sitemap | boolean | no | Default true |
position | integer | no | Manual sort order. Default 0. Always ascending: lower values come first. |
blueprint_handle | string | no | Create only. Which of the collection's blueprints to use. Defaults to the collection's first blueprint. |
template_handle | string | no | Override the collection's template. Unknown handle returns 422. |
layout_handle | string | no | Override the collection's layout. Unknown handle returns 422. |
<field_handle> | varies | no | One key per blueprint field. See the value formats below. |
Field value formats
| Field type | Send | Returned as |
|---|---|---|
text, raw_html | String | String |
rich_text | HTML string | HTML string |
number | Number | Number |
toggle | true / false | Boolean |
enumerate | One of the field's enumerations | String |
image | Asset actast_ ID, filename, path/filename (for example uploads/2026/09/photo.jpg) or /assets/path/filename | Image URL path, for example /rails/active_storage/blobs/redirect/.../photo.jpg |
gallery | Array of {type, url, id, thumbnail, filename, width, height} | Same array |
video | Video URL string, or {url, video_id, thumbnail} | Object {url, video_id, thumbnail} |
entity | Entry cnety_ ID, "collection_handle:entry_handle" or an entry handle. For fields with multiple: an array of cnety_ IDs. | The referenced entry expanded as an object {id, title, handle, ...fields, content_path, published_at}, or an array of these for multiple |
list | Array | Array |
dictionary | Object | Object |
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id
|
string | Required |
Path. Your account prefix ID (acct_...).
|
collection_id
|
string | Required |
Path. Collection clctn_ ID or handle.
|
id
|
string | Optional |
Path, for show/update/delete. Entry cnety_ ID or handle.
|
handle
|
string | Optional | Query, list only. Return only the record with exactly this handle. |
published
|
boolean | Optional |
Query, list only. true or false to filter by published status.
|
page
|
integer | Optional | Query, list only. Page number, starting at 1. The page size is fixed at 20. |
handle
|
string | Required | Body. URL slug, unique in the collection. POST with an existing handle updates it. |
title
|
string | Required | Body. Required on create, optional on update. |
published
|
boolean | Optional |
Body. Default true.
|
published_at
|
datetime | Optional | Body. ISO 8601. Required for date-based routing. |
include_in_sitemap
|
boolean | Optional |
Body. Default true.
|
position
|
integer | Optional | Body. Manual sort order, ascending. Default 0. |
blueprint_handle
|
string | Optional | Body, create only. Defaults to the collection's first blueprint. |
template_handle
|
string | Optional | Body. Template override. |
layout_handle
|
string | Optional | Body. Layout override. |
|
varies | Optional | Body. A value for each blueprint field, as a top-level key. |
Request Example
# List published entries
curl "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/collections/posts/entries?published=true" \
-H "Authorization: Bearer $API_TOKEN"
# Get one entry by handle
curl "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/collections/posts/entries/hello-world" \
-H "Authorization: Bearer $API_TOKEN"
# Create an entry (re-running with the same handle updates it)
curl -X POST "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/collections/posts/entries" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"handle": "hello-world",
"title": "Hello World",
"published": true,
"published_at": "2026-09-15T10:00:00Z",
"position": 0,
"body": "Our first post.
",
"excerpt": "Our first post",
"featured_image": "uploads/2026/09/photo.jpg",
"author": "authors:ada-lovelace",
"related_posts": ["cnety_2mQx8Lr", "cnety_9pKw3Nd"]
}'
# Update only some values (PUT or PATCH)
curl -X PATCH "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/collections/posts/entries/hello-world" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"excerpt": "A shorter summary", "featured_image": "actast_5hTq2Wm"}'
# Delete
curl -X DELETE "https://api.airogelcms.com/v1/accounts/$ACCOUNT_ID/collections/posts/entries/hello-world" \
-H "Authorization: Bearer $API_TOKEN"
Response Example
// Single entry (show, create, update)
{
"id": "cnety_7vBn4Kq",
"handle": "hello-world",
"title": "Hello World",
"published": true,
"published_at": "2026-09-15T10:00:00Z",
"content_path": "/blog/hello-world",
"collection_handle": "posts",
"blueprint_handle": "blog_post",
"template_handle": null,
"layout_handle": null,
"routing_override": null,
"include_in_sitemap": true,
"position": 0,
"created_at": "2026-09-15T10:02:13Z",
"updated_at": "2026-09-15T10:02:13Z",
"body": "Our first post.
",
"excerpt": "Our first post",
"featured_image": "/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsi.../photo.jpg",
"author": {
"id": "cnety_4dLp9Xs",
"title": "Ada Lovelace",
"handle": "ada-lovelace",
"bio": "Mathematician and writer.",
"content_path": "/authors/ada-lovelace"
},
"related_posts": [
{ "id": "cnety_2mQx8Lr", "title": "Second Post", "handle": "second-post", "content_path": "/blog/second-post", "published_at": "2026-09-16T09:00:00Z" },
{ "id": "cnety_9pKw3Nd", "title": "Third Post", "handle": "third-post", "content_path": "/blog/third-post", "published_at": "2026-09-17T09:00:00Z" }
]
}
// List
{
"data": [
{ "id": "cnety_7vBn4Kq", "handle": "hello-world", "title": "Hello World", "...": "same fields as above" }
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 1,
"total_pages": 1,
"next_page": null,
"prev_page": null
}
}
// 422 - collection routing needs a date
{
"error": "Validation failed",
"details": [
{ "path": "published_at", "message": "required for date routing" }
]
}
Additional Notes
Content paths. The entry's URL is generated from the collection's routing pattern and returned as content_path. It changes automatically when the handle or date changes.
Blueprint selection. If you leave out blueprint_handle on create, the entry uses the collection's first blueprint. If the collection has no blueprint, the request fails with 422 (path: "blueprint_handle", "has no blueprint attached"). The blueprint cannot be changed with PUT/PATCH.
Unknown keys are ignored. Only keys that match a field handle on the entry's blueprint are saved. A misspelled field name is dropped silently, so check the response.
Ordering. Collection listings on the site sort by position (ascending), then by date as set by the collection's orderable. The REST list endpoint itself always returns newest-created first.
Read-only values. content_path, collection_handle and routing_override are returned but not writable through REST. Set routing_override in the dashboard or through MCP. For single-field patches and structured queries, also use MCP.
Match errors on path rather than on message text, which may change. See Field Types Reference for more about each field type.