Collections API

Overview

The Collections API manages user-specific item collections like favorites, recent items, bookmarks, and pins.

Collection Types

Type Description
FAVR Favorites - user’s favorite items
RCNT Recent - recently accessed items
BKMK Bookmarks - saved references
PIND Pinned - pinned items for quick access

Endpoints

List Collection Items

GET /api/collections/{coll_type}

List all items in a collection.

Authentication: Required

Path Parameters:

  • coll_type - Collection type: FAVR, RCNT, BKMK, or PIND

Query Parameters:

  • limit - Maximum items to return (default: 20)
  • cursor - Opaque cursor for pagination

Response:

{
  "data": [
    {
      "itemId": "f1~abc123",
      "addedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "cursorPagination": {
    "nextCursor": "eyJzIjoiYWRkZWRfYXQiLCJ2IjoxNzA1MzE1ODAwfQ",
    "hasMore": false
  },
  "time": "2025-01-15T10:30:00Z"
}

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/collections/FAVR?limit=20"

Add Item to Collection

POST /api/collections/{coll_type}/{item_id}

Add an item to a collection.

Authentication: Required

Path Parameters:

  • coll_type - Collection type: FAVR, RCNT, BKMK, or PIND
  • item_id - ID of the item to add (file ID or action ID)

Response:

{
  "data": {
    "itemId": "f1~abc123",
    "addedAt": "2025-01-15T10:30:00Z"
  },
  "time": "2025-01-15T10:30:00Z"
}

Example:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/collections/FAVR/f1~abc123"

Remove Item from Collection

DELETE /api/collections/{coll_type}/{item_id}

Remove an item from a collection.

Authentication: Required

Path Parameters:

  • coll_type - Collection type: FAVR, RCNT, BKMK, or PIND
  • item_id - ID of the item to remove

Response:

{
  "data": "ok",
  "time": "2025-01-15T10:30:00Z"
}

Example:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://cl-o.alice.cloudillo.net/api/collections/FAVR/f1~abc123"

Client SDK Usage

import { createApiClient } from '@cloudillo/core'

const api = createApiClient({ idTag: 'alice.cloudillo.net', authToken: token })

// List favorites
const favorites = await api.collections.list('FAVR', { limit: 20 })

// Add to bookmarks
await api.collections.add('BKMK', 'file_abc123')

// Remove from pins
await api.collections.remove('PIND', 'file_abc123')

// Shorthand for files
await api.files.favorite('file_abc123')
await api.files.unfavorite('file_abc123')

Use Cases

Favorites

Store user’s favorite files for quick access.

// Add file to favorites
await api.files.favorite(fileId)

// List favorite files
const favs = await api.files.listFavorites({ limit: 50 })

Recent Items

Track recently accessed files (managed automatically by the system).

// List recent files
const recent = await api.files.listRecent({ limit: 20 })

Bookmarks

Save references for later.

// Add bookmark
await api.collections.add('BKMK', actionId)

// List bookmarks
const bookmarks = await api.collections.list('BKMK')

Pinned Items

Pin important items for quick access.

// Pin a file
await api.files.setPinned(fileId, true)

// List pinned items
const pinned = await api.collections.list('PIND')

See Also