***

title: Collections
description: 'How to create, manage, and retrieve collections in AISquare.'
---------------------------------------------------------------------------

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

| Parameter         | Description                        |
| ----------------- | ---------------------------------- |
| `ordering`        | Field to order results             |
| `owner`           | Filter by owner                    |
| `publication`     | Filter by publication ID           |
| `publication_url` | Filter by publication URL          |
| `search`          | Search term                        |
| `tags`            | Filter by tags                     |
| `visibility`      | `public`, `private`, `team`, `org` |
| `page`            | Page number                        |
| `page_size`       | Results per page                   |

### 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

| Status | Meaning            |
| ------ | ------------------ |
| `201`  | Collection created |
| `400`  | Invalid input      |
| `401`  | Unauthorized       |

***

## Retrieve collection details

### Endpoint

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

### Path parameters

| Parameter | Description   |
| --------- | ------------- |
| `id`      | Collection ID |

### 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

| Status | Meaning              |
| ------ | -------------------- |
| `204`  | Deleted successfully |

***

## 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

```json
{
  "url": "ai-research-studio"
}
```

### 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

| Status | Meaning                                |
| ------ | -------------------------------------- |
| `400`  | Missing or invalid URL                 |
| `401`  | Authentication required                |
| `404`  | Publication not found or access denied |

***

## 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

| Parameter         | Description      |
| ----------------- | ---------------- |
| `experience_type` | Filter by type   |
| `search`          | Search term      |
| `page`            | Page number      |
| `page_size`       | Results per page |

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

***

## Visibility options

| Value     | Description  |
| --------- | ------------ |
| `public`  | Public       |
| `private` | Private      |
| `team`    | Team         |
| `org`     | Organization |

***

## Notes

* Collections are scoped to a publication — see [AI Studios](/docs/product/ai-studios)
* Ordering of experiences is preserved
* Only eligible experiences can be added

***

## Related pages

* [Core Concepts](/docs/getting-started/core-concepts) — collections in the entity hierarchy
* [AI Studios](/docs/product/ai-studios) — publication-scoped data
* [Authentication](/docs/getting-started/authentication) — required for all endpoints
* [Permissions and access control](/docs/data-ux-guides/permissions-and-access-control) — visibility and access rules
* [Search, filtering, and pagination](/docs/data-ux-guides/search-filtering-and-pagination) — filtering collections
* [Errors](/docs/reference/errors) — handle 400, 401, 404 responses