Page Collection
This allows you to group related pages or routes and analyze their performance collectively.
The Page Collections API allows you to group related pages and analyze their combined performance.
Collections can contain pages using either:
Explicit page IDs — map specific pages directly to a collection.
URL prefix patterns — automatically include pages whose URLs match a specified prefix.
For example, a collection can contain all pages under /ticketing, or specific pages identified by their page_id.
Base URL
All endpoints are available under:
/external/v1/page-collectionsAuthentication
Requests must be authenticated using your API key.
Include the API key in the X-API-Key header:
X-API-Key: YOUR_API_KEYExample:
curl -X GET "https://api.cuoral.com/external/v1/page-collections" \
-H "X-API-Key: YOUR_API_KEY"Replace
https://api.cuoral.comwith your API's base URL.
Endpoints
GET
/external/v1/page-collections
List all page collections
POST
/external/v1/page-collections
Create a page collection
GET
/external/v1/page-collections/pages
List registry pages
GET
/external/v1/page-collections/{collection_id}
Get collection analytics
PUT
/external/v1/page-collections/{collection_id}
Update a collection
DELETE
/external/v1/page-collections/{collection_id}
Delete a collection
POST
/external/v1/page-collections/{collection_id}/map-pages
Map pages to a collection
DELETE
/external/v1/page-collections/{collection_id}/pages/{page_id}
Remove a page mapping
DELETE
/external/v1/page-collections/{collection_id}/patterns/{url_pattern}
Remove a URL pattern mapping
List Page Collections
Returns all page collections belonging to the authenticated organization.
Endpoint
Authentication
Requires X-API-Key.
Query Parameters
None.
Example Request
Response
200 OK
Response Fields
collections
array
List of collections
collection_id
string
Unique identifier for the collection
name
string
Collection name
description
string
Collection description
member_pages_count
integer
Number of pages currently in the collection
created_at
string
Collection creation timestamp
updated_at
string
Last update timestamp
Create Page Collection
Creates a new collection for grouping related pages.
Pages can be added using explicit page_ids, URL prefix rules, or both.
Endpoint
Authentication
Requires X-API-Key.
Request Body
Request Fields
name
string
Yes
Name of the collection
description
string
No
Description of the collection
page_ids
array of strings
No
Explicit page IDs to include
url_patterns
array of strings
No
URL prefix rules used to include pages
URL Patterns
URL patterns are treated as prefixes.
For example:
can match pages such as:
Example Request
Response
200 OK
Validation Error
422 Unprocessable Entity
List Registry Pages
Returns the organization's page registry.
Use this endpoint to retrieve available page_id values before mapping pages to a collection.
Endpoint
Query Parameters
search
string
No
—
Search by title, canonical URL, or display URL
page
integer
No
1
Page number. Must be >= 1
limit
integer
No
100
Maximum number of results. Range: 1–200
Example Request
Response
200 OK
Response Fields
pages
array
Matching registry pages
pages[].page_id
string
Unique page identifier
pages[].title
string
Page title
pages[].canonical_url
string
Canonical page URL
pages[].display_url
string
Display URL
pagination.page
integer
Current page number
pagination.limit
integer
Number of results requested
pagination.total
integer
Total number of matching pages
search
string
Search term used for the request
Pagination Example
To retrieve the second page of results:
Get Page Collection Analytics
Returns consolidated analytics across all pages belonging to a collection.
Endpoint
Path Parameters
collection_id
string
Yes
Unique collection identifier
Query Parameters
start
date
No
—
Start date in YYYY-MM-DD format
end
date
No
—
End date in YYYY-MM-DD format
interval
string
No
daily
Trend interval
Supported intervals:
hourlydailyweeklymonthly
Example Request
Response
200 OK
Analytics Fields
total_visits
number
Total visits across collection pages
unique_users
number
Number of unique users
avg_time_seconds
number
Average time spent on pages, in seconds
engagement_score
number
Collection engagement score
friction_score
number
Collection friction score
error_count
number
Number of recorded errors
rage_click_count
number
Number of rage-click events
drop_off_rate
number
Drop-off rate
member_pages
number
Number of pages belonging to the collection
Trend Intervals
Use interval to control the granularity of trend data:
For example:
Update Page Collection
Updates the name and/or description of an existing collection.
Endpoint
Path Parameters
collection_id
string
Yes
Unique collection identifier
Request Body
Request Fields
name
string
No
Updated collection name
description
string
No
Updated collection description
Example Request
Response
200 OK
Delete Page Collection
Deletes a collection and its mappings.
Important: Deleting a collection does not delete the underlying pages or their analytics data.
Endpoint
Path Parameters
collection_id
string
Yes
Unique collection identifier
Example Request
Response
200 OK
Map Pages to Collection
Adds pages and/or URL prefix rules to an existing collection.
You can use this endpoint to add mappings after a collection has already been created.
Endpoint
Path Parameters
collection_id
string
Yes
Unique collection identifier
Request Body
Request Fields
page_ids
array of strings
No
Page IDs to explicitly add
url_patterns
array of strings
No
URL prefix rules to add
Both fields can be used together.
Example Request
Response
200 OK
Unmap Page from Collection
Removes an explicit page mapping from a collection.
The page itself is not deleted, and its analytics data remains unchanged.
Endpoint
Path Parameters
collection_id
string
Yes
Unique collection identifier
page_id
string
Yes
Page to remove from the collection
Example Request
Response
200 OK
Note: This only removes the explicit page mapping. If the page also matches a URL prefix pattern, it may remain a member of the collection through that pattern.
Unmap URL Pattern from Collection
Removes a URL prefix rule from a collection.
Removing a pattern causes pages matched exclusively by that pattern to leave the collection. The underlying pages and their analytics data remain untouched.
Endpoint
Path Parameters
collection_id
string
Yes
Unique collection identifier
url_pattern
string
Yes
URL prefix pattern to remove
URL Pattern Format
A leading / is optional.
Both of the following are valid:
Patterns can also contain nested paths:
Example Request
Response
200 OK
Common Error Response
Endpoints that accept path, query, or body parameters may return a 422 Unprocessable Entity response when validation fails.
422 Unprocessable Entity
Error Fields
detail
List of validation errors
loc
Location of the invalid parameter
msg
Human-readable validation message
type
Validation error type
input
Value supplied in the request
Recommended Workflow
A typical workflow for creating and managing a page collection is:
1. Retrieve available pages
Use:
Search for the pages you want to include and collect their page_id values.
2. Create the collection
Use:
Provide the collection name and optionally include page_ids and/or url_patterns.
3. Add additional mappings
If needed, use:
4. View collection analytics
Use:
Specify start, end, and interval to control the analytics period and trend granularity.
5. Remove mappings
Remove individual pages with:
Or remove URL prefix rules with:
6. Update or delete the collection
Update collection metadata with:
Delete the collection with:
Deleting a collection does not delete the underlying pages or analytics data.
Page Mapping Behavior
Page Collections support two types of mappings:
Explicit Page Mapping
An explicit mapping references a specific page_id.
Example:
This is useful when you want precise control over which pages belong to a collection.
URL Prefix Mapping
A URL pattern includes pages whose URLs begin with the specified prefix.
Example:
This can include:
URL patterns are useful when a collection should automatically cover an entire section of your application.
Combining Both
You can use explicit page IDs and URL patterns together:
This allows a collection to contain both specifically selected pages and pages discovered through URL rules.
Last updated