Collections

This guide explains how to create, manage, and retrieve collections in AISquare.

Overview

A collection is a group of experiences associated with a publication.

Collections allow you to:

• Organize experiences
• Control visibility
• Define ordering

List collections

Retrieve all collections accessible to the authenticated user.

Endpoint

GET /api/v1/collections/

Query parameters

Access control

• Requires authentication

Response

• Paginated list of collections

Create a collection

Endpoint

POST /api/v1/collections/

Request body

• Uses CollectionCreateUpdate schema
• Includes collection details and ordered experiences

Access control

• Requires authentication

Response

Retrieve collection details

Endpoint

GET /api/v1/collections/{id}/

Path parameters

Access control

• Requires authentication
• Returns 404 if not found

Response

• Collection details
• Includes ordered experiences

Update a collection

Endpoints

PUT /api/v1/collections/{id}/
PATCH /api/v1/collections/{id}/

Request body

• Uses CollectionCreateUpdate or patched schema

Access control

• Requires authentication
• Only owner can update

Delete a collection

Endpoint

DELETE /api/v1/collections/{id}/

Access control

• Requires authentication
• Only owner can delete

Response

Update collection experiences

Replace the ordered list of experiences in a collection.

Endpoint

PUT /api/v1/collections/{id}/experiences/

Request body

• Uses CollectionExperiencesUpdate schema

Access control

• Requires authentication
• Only published experiences from the same publication can be added

Collections by publication URL

Retrieve collections for a specific publication.

Endpoint

POST /api/v1/collections/by-url/

Request body

1
{
2
  "url": "ai-research-studio"
3
}

Optional filters

• search
• visibility
• tags
• owner

Access control

Depends on publication visibility:

• PUBLIC → accessible without authentication (public collections only)
• TEAM → requires authentication and workspace membership
• PRIVATE → requires authentication and appropriate role

Error responses

Supporting endpoints

List publications for collections

GET /api/v1/collections/publications/

• Returns publications user can manage
• Requires OWNER, ADMIN, or EDITOR role

List experiences for a publication

GET /api/v1/collections/publications/{publication_id}/experiences/

Query parameters

Note: Returns only published experiences. Each experience has exactly one type.

Visibility options

Notes

• Collections are scoped to a publication — see AI Studios
• Ordering of experiences is preserved
• Only eligible experiences can be added

Related pages

• Core Concepts — collections in the entity hierarchy
• AI Studios — publication-scoped data
• Authentication — required for all endpoints
• Permissions and access control — visibility and access rules
• Search, filtering, and pagination — filtering collections
• Errors — handle 400, 401, 404 responses