A component collection is an area that holds a list of components: the sections of a page, the blocks of a guide page. Each operation is a key inside patchRevision on the record’s edit route, so it copies a revision, changes the collection and keeps every other area. Send originRevision with the live revision’s id and activeRevision: true, or the change is saved without going live.
Key
Does
areaCollectionElement(area, n)
Replaces element n
patchAreaCollectionElement(area, n)
Changes some areas of element n
insertAreaCollectionElement(area, n)
Inserts a new element at n
appendAreaCollectionElement(area)
Adds one element at the end
appendAreaCollectionElements(area)
Adds several at the end
removeAreaCollectionElement(area, n)
Removes element n
areaContent(area)
Replaces the whole collection, numbered from 1
Positions
Positions start at 1. Within one request, every position refers to the collection as it was before the request, so several operations can be combined without working out how each shifts the next. Between requests it is different: a removal does not renumber the elements after it. After a removal, rewrite the whole collection with areaContent(area) before addressing elements by position again.
Component ids are not stable either: every patch copies the components, so an element cannot be addressed by its id.
Replaces the element at a position with a new component. The component’s layout can differ from the old one.
Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
A message, with status 200. Ask for the new revision with properties={id,activeRevision{id}}.
Parameters
idpathrequired
integer
The page. The same keys work on any record whose revisions hold layout areas.
patchRevision.originRevisionbody
id
The revision to copy, normally the live one. Without it the newest revision is copied.
patchRevision.activeRevisionbody
boolean
true makes the new revision live.
areaCollectionElement(area, n)body
component
layout, name and areas of the new component. Not setAreaCollectionElement.
Positions drift after a removal. A removal does not renumber the elements after it, so in a later request, position n can address the element whose stored position is n rather than the n-th one, with status 200 and no error. On this site’s sandbox, removing 2 from A, B, C, D left A, C, D, and a later “remove 3” removed C. Make every position-based change in one request, or rewrite the whole collection with areaContent(area), which renumbers it.
Changes some areas of the element at a position and keeps the rest of it.
Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
A message, with status 200. Ask for the new revision with properties={id,activeRevision{id}}.
Parameters
idpathrequired
integer
The page. The same keys work on any record whose revisions hold layout areas.
patchRevision.originRevisionbody
id
The revision to copy, normally the live one. Without it the newest revision is copied.
patchRevision.activeRevisionbody
boolean
true makes the new revision live.
patchAreaCollectionElement(area, n)body
object
Either {"areas": {...}} or "areaContent(name)": value keys, as for the page itself.
Positions drift after a removal. A removal does not renumber the elements after it, so in a later request, position n can address the element whose stored position is n rather than the n-th one, with status 200 and no error. On this site’s sandbox, removing 2 from A, B, C, D left A, C, D, and a later “remove 3” removed C. Make every position-based change in one request, or rewrite the whole collection with areaContent(area), which renumbers it.
Example
Change the body of the second section
PUT /cdna-api/pages/page/1885?properties={id,activeRevision{id}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json
{
"patchRevision": {
"originRevision": 3270,
"activeRevision": true,
"patchAreaCollectionElement(pageSections, 2)": {
"areaContent(body)": "<p>Only the body changed</p>"
}
}
}
Response200 OK
{
"result": "success",
"data": {
"id": 1885,
"activeRevision": {
"id": 3271
}
},
"message": "The Page has been saved successfully."
}
Real response from the API sandbox page. Before: A · B (replaced) · C. After: A · B (replaced) · C.
Adds a new component at the end of the collection.
Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
A message, with status 200. Ask for the new revision with properties={id,activeRevision{id}}.
Parameters
idpathrequired
integer
The page. The same keys work on any record whose revisions hold layout areas.
patchRevision.originRevisionbody
id
The revision to copy, normally the live one. Without it the newest revision is copied.
patchRevision.activeRevisionbody
boolean
true makes the new revision live.
appendAreaCollectionElement(area)body
component
layout, name, areas, and optionally published: false. JSON cannot repeat a key, so a second append in the same request needs the plural form.
Example
Append one section
PUT /cdna-api/pages/page/1885?properties={id,activeRevision{id}} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json
{
"patchRevision": {
"originRevision": 3272,
"activeRevision": true,
"appendAreaCollectionElement(pageSections)": {
"layout": 40,
"name": "New last section",
"areas": {
"body": "<p>New last section</p>"
}
}
}
}
Response200 OK
{
"result": "success",
"data": {
"id": 1885,
"activeRevision": {
"id": 3273
}
},
"message": "The Page has been saved successfully."
}
Open in Postman docs ↗Real response from the API sandbox page. Before: new first · A · B (replaced) · C. After: new first · A · B (replaced) · C · new last.
Removes the elements at the positions given. Several removals in one request all refer to the collection as it was before the request, in any order.
Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
A message, with status 200. Ask for the new revision with properties={id,activeRevision{id}}.
Parameters
idpathrequired
integer
The page. The same keys work on any record whose revisions hold layout areas.
patchRevision.originRevisionbody
id
The revision to copy, normally the live one. Without it the newest revision is copied.
patchRevision.activeRevisionbody
boolean
true makes the new revision live.
removeAreaCollectionElement(area, n)body
true
One key per element to remove; the value is ignored.
Positions drift after a removal. A removal does not renumber the elements after it, so in a later request, position n can address the element whose stored position is n rather than the n-th one, with status 200 and no error. On this site’s sandbox, removing 2 from A, B, C, D left A, C, D, and a later “remove 3” removed C. Make every position-based change in one request, or rewrite the whole collection with areaContent(area), which renumbers it.
Combines collection operations, and other changes to the revision, in one request. Every position refers to the collection before the request, so the result does not depend on the order of the keys.
Access
Admin users and integrations, with an OAuth access token or an API key.
Returns
A message, with status 200. Ask for the new revision with properties={id,activeRevision{id}}.
Parameters
idpathrequired
integer
The page. The same keys work on any record whose revisions hold layout areas.
patchRevision.originRevisionbody
id
The revision to copy, normally the live one. Without it the newest revision is copied.
patchRevision.activeRevisionbody
boolean
true makes the new revision live.
namebody
string
Any other change to the revision can travel in the same request.