> ## Documentation Index
> Fetch the complete documentation index at: https://animus.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> Create and manage collections to organize your content

## List collections

```bash theme={null}
GET /api/v1/collections
```

Returns all your collections with titles, descriptions, and item counts.

**Scope:** `read`

```bash theme={null}
curl https://api.animus.so/api/v1/collections \
  -H "Authorization: Bearer anm_your_key"
```

**Response** `200`

```json theme={null}
{
  "items": [
    {
      "id": "uuid",
      "title": "Research Papers",
      "shortDescription": "Papers on ML architectures",
      "icon": null,
      "itemCount": 12,
      "privacy": "private",
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 8
}
```

***

## Get collection

```bash theme={null}
GET /api/v1/collections/:id
```

Returns a single collection with its full metadata.

**Scope:** `read`

| Parameter | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| `id`      | string | Collection ID (path parameter) |

```bash theme={null}
curl https://api.animus.so/api/v1/collections/COLLECTION_ID \
  -H "Authorization: Bearer anm_your_key"
```

**Response** `200`

```json theme={null}
{
  "id": "uuid",
  "title": "Research Papers",
  "shortDescription": "Papers on ML architectures",
  "description": "Detailed description of the collection",
  "icon": null,
  "itemCount": 12,
  "privacy": "private",
  "createdAt": "2025-01-10T09:00:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
```

***

## Create collection

```bash theme={null}
POST /api/v1/collections
```

Create a new collection.

**Scope:** `write`

<ParamField body="title" type="string" required>
  Collection title (1-40 characters).
</ParamField>

<ParamField body="short_description" type="string">
  Short description (up to 500 characters).
</ParamField>

<ParamField body="description" type="string">
  Detailed description.
</ParamField>

<ParamField body="icon" type="string">
  Emoji icon for the collection.
</ParamField>

```bash theme={null}
curl -X POST https://api.animus.so/api/v1/collections \
  -H "Authorization: Bearer anm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Research Papers", "short_description": "Papers on ML architectures"}'
```

**Response:** `201 Created`

Returns the created collection in the same shape as [get collection](#get-collection).

***

## Update collection

```bash theme={null}
PUT /api/v1/collections/:id
```

Update a collection's title, description, or icon. All fields are optional.

**Scope:** `write`

```bash theme={null}
curl -X PUT https://api.animus.so/api/v1/collections/COLLECTION_ID \
  -H "Authorization: Bearer anm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title"}'
```

**Response:** `200`

Returns the updated collection in the same shape as [get collection](#get-collection).

***

## Delete collection

```bash theme={null}
DELETE /api/v1/collections/:id
```

Permanently delete a collection. Content items in the collection are not deleted.

**Scope:** `write`

```bash theme={null}
curl -X DELETE https://api.animus.so/api/v1/collections/COLLECTION_ID \
  -H "Authorization: Bearer anm_your_key"
```

**Response:** `204 No Content`

***

## List collection items

```bash theme={null}
GET /api/v1/collections/:id/items
```

Returns content items within a specific collection.

**Scope:** `read`

| Parameter        | Type    | Default    | Description                     |
| ---------------- | ------- | ---------- | ------------------------------- |
| `limit`          | integer | `50`       | Items per page                  |
| `offset`         | integer | `0`        | Offset for pagination           |
| `orderBy`        | string  | `position` | Sort field                      |
| `orderDirection` | string  | `asc`      | Sort direction: `asc` or `desc` |

```bash theme={null}
curl "https://api.animus.so/api/v1/collections/COLLECTION_ID/items?limit=10" \
  -H "Authorization: Bearer anm_your_key"
```

**Response** `200`

```json theme={null}
{
  "items": [
    {
      "id": "uuid",
      "position": 0,
      "addedAt": "2025-01-12T14:00:00.000Z",
      "content": {
        "id": "uuid",
        "url": "https://example.com/article",
        "thumbnailUrl": null,
        "platform": "web",
        "savedAt": "2025-01-10T09:00:00.000Z",
        "tags": ["ml"],
        "isFavorite": false,
        "isArchived": false,
        "status": "ready",
        "title": "Article Title",
        "summary": "A brief summary...",
        "creator": null
      }
    }
  ],
  "total": 12,
  "hasMore": false
}
```

<Note>Each item wraps the content inside a `content` field, alongside collection-specific metadata like `position` and `addedAt`.</Note>

***

## Add item to collection

```bash theme={null}
POST /api/v1/collections/:id/items
```

Add a content item to a collection.

**Scope:** `write`

<ParamField body="user_content_id" type="string" required>
  The content item ID to add.
</ParamField>

<ParamField body="position" type="integer">
  Optional position in the collection ordering.
</ParamField>

```bash theme={null}
curl -X POST https://api.animus.so/api/v1/collections/COLLECTION_ID/items \
  -H "Authorization: Bearer anm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"user_content_id": "CONTENT_ID"}'
```

**Response:** `201 Created`

```json theme={null}
{
  "id": "uuid",
  "collection_id": "uuid",
  "user_content_id": "uuid",
  "position": 0,
  "added_at": "2025-01-12T14:00:00.000Z"
}
```

***

## Remove item from collection

```bash theme={null}
DELETE /api/v1/collections/:id/items/:itemId
```

Remove a content item from a collection. The content itself is not deleted.

**Scope:** `write`

```bash theme={null}
curl -X DELETE https://api.animus.so/api/v1/collections/COLLECTION_ID/items/ITEM_ID \
  -H "Authorization: Bearer anm_your_key"
```

**Response:** `204 No Content`