Skip to main content

​
List collections

GET /api/v1/collections
Returns all your collections with titles, descriptions, and item counts. Scope: read 
curl https://api.animus.so/api/v1/collections \
  -H "Authorization: Bearer anm_your_key"
Response 200 
{
  "collections": [
    {
      "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,
  "hasMore": false
}

​
Get collection

GET /api/v1/collections/:id
Returns a single collection with its full metadata. Scope: read
ParameterTypeDescription
idstringCollection ID (path parameter)
curl https://api.animus.so/api/v1/collections/COLLECTION_ID \
  -H "Authorization: Bearer anm_your_key"
Response 200 
{
  "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

POST /api/v1/collections
Create a new collection. Scope: write
​
title
string
required
Collection title (1-40 characters).
​
short_description
string
Short description (up to 500 characters).
​
description
string
Detailed description.
​
icon
string
Emoji icon for the collection.
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.

​
Update collection

PUT /api/v1/collections/:id
Update a collection’s title, description, or icon. All fields are optional. Scope: write 
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.

​
Delete collection

DELETE /api/v1/collections/:id
Permanently delete a collection. Content items in the collection are not deleted. Scope: write 
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

GET /api/v1/collections/:id/items
Returns content items within a specific collection. Scope: read
ParameterTypeDefaultDescription
limitinteger50Items per page
offsetinteger0Offset for pagination
orderBystringpositionSort field
orderDirectionstringascSort direction: asc or desc
curl "https://api.animus.so/api/v1/collections/COLLECTION_ID/items?limit=10" \
  -H "Authorization: Bearer anm_your_key"
Response 200 
{
  "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
}
Each item wraps the content inside a content field, alongside collection-specific metadata like position and addedAt.

​
Add item to collection

POST /api/v1/collections/:id/items
Add a content item to a collection. Scope: write
​
user_content_id
string
required
The content item ID to add.
​
position
integer
Optional position in the collection ordering.
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 
{
  "id": "uuid",
  "collection_id": "uuid",
  "user_content_id": "uuid",
  "position": 0,
  "added_at": "2025-01-12T14:00:00.000Z"
}

​
Remove item from collection

DELETE /api/v1/collections/:id/items/:itemId
Remove a content item from a collection. The content itself is not deleted. Scope: write 
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