V1 API Bookmark Collections

Source: OpenAPI 3.1.0 spec + src/api/v1/bookmark_collections/routes.py, src/api/v1/bookmark_collections/schemas.py Tag: Bookmark Collections - CRUD for bookmark collections.

All endpoints require Bearer Token authentication. Response data is encrypted when feature flag is enabled.

---

POST /bookmark-collections

Summary: Create Bookmark Collection

Create a new bookmark collection for the authenticated user.

Parameters

Name	In	Required	Description
course_id	query	required	Course ID this collection belongs to
x-dev-time	header	optional	Epoch ms (13 digits)

Request Body

{
  "name": "Important Questions",
  "description": "Questions I need to review before the exam",
  "emoji": "📌"
}

Field	Type	Constraints	Description
name	string	required, 1 to MAX_COLLECTION_NAME_LENGTH chars	Collection name
description	string	optional, max MAX_COLLECTION_DESCRIPTION_LENGTH chars	Description
emoji	string	required, exactly 1 character	Single emoji representing the collection

Success Response

{
  "status": "success",
  "is_data_encrypted": 0,
  "data": {
    "id": "60d5ec49f1b2c72e4c8bcccc",
    "name": "Important Questions",
    "description": "Questions I need to review before the exam",
    "is_default": false,
    "course_id": 1,
    "emoji": "📌",
    "mcq_count": 0,
    "short_uid": "BC001",
    "is_deleted": false,
    "created_at": 1714400000000
  },
  "error": null,
  "app_actions": null
}

Field	Description
is_default	true only for the system-created “All Bookmarks” collection
mcq_count	Number of MCQs currently in this collection. Starts at 0
short_uid	Short identifier for sharing
created_at	Creation timestamp in UTC epoch ms

---

GET /bookmark-collections/sync

Summary: Sync Bookmark Collections

Get a paginated list of bookmark collections using cursor-based pagination.

Parameters

Name	In	Required	Constraints	Description
course_id	query	required	CourseEnum	Course ID to filter
limit	query	optional	1-120, default 10	Number of results
next_cursor	query	optional	base64 string	Forward pagination cursor
prev_cursor	query	optional	base64 string	Backward pagination cursor
x-dev-time	header	optional	13 digits	Epoch ms

Success Response

{
  "status": "success",
  "is_data_encrypted": 0,
  "data": [
    {
      "id": "60d5ec49f1b2c72e4c8bbbbb",
      "name": "All Bookmarks",
      "description": null,
      "is_default": true,
      "course_id": 1,
      "emoji": "📚",
      "mcq_count": 47,
      "short_uid": "BC000",
      "is_deleted": false,
      "created_at": 1714300000000
    },
    {
      "id": "60d5ec49f1b2c72e4c8bcccc",
      "name": "Important Questions",
      "description": "Questions I need to review before the exam",
      "is_default": false,
      "course_id": 1,
      "emoji": "📌",
      "mcq_count": 12,
      "short_uid": "BC001",
      "is_deleted": false,
      "created_at": 1714400000000
    }
  ],
  "error": null,
  "app_actions": null,
  "pagination": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoxNzE0NDAwMDAwMDAwLCJpZCI6IjYwZDVlYzQ5ZjFiMmM3MmU0YzhiY2NjYyJ9",
    "prev_cursor": null,
    "limit": 10,
    "has_more": false
  }
}

Note: The default “All Bookmarks” collection (is_default: true) is always present. It is auto-created on first login with a course_id.

---

PATCH /bookmark-collections/{collection_id}

Summary: Update Bookmark Collection

Update a bookmark collection’s name, description, or emoji.

Parameters

Name	In	Required	Description
collection_id	path	required	Collection ID to update (ObjectId)
x-dev-time	header	optional	Epoch ms (13 digits)

Request Body

{
  "name": "Must Revise",
  "description": "Critical questions for final revision",
  "emoji": "🔥"
}

Field	Type	Constraints	Description
name	string	optional, 1 to MAX chars	New name
description	string	optional, max chars	New description
emoji	string	optional, exactly 1 char	New emoji

All fields optional - only provided fields are updated.

Success Response

Returns updated BookmarkCollectionResponse (same shape as create response).

---

DELETE /bookmark-collections/{collection_id}

Summary: Delete Bookmark Collection

Delete a bookmark collection. All MCQs in the deleted collection are moved to “All Bookmarks”.

Parameters

Name	In	Required	Description
collection_id	path	required	Collection ID to delete (ObjectId)
course_id	query	required	Course ID this collection belongs to
x-dev-time	header	optional	Epoch ms (13 digits)

Business Logic

1. Validates the collection exists and belongs to the authenticated user
2. Moves all MCQ bookmarks from this collection to the default “All Bookmarks” collection
3. Soft-deletes the collection (is_deleted=true)

Success Response

{
  "status": "success",
  "is_data_encrypted": 0,
  "data": {
    "id": "60d5ec49f1b2c72e4c8bcccc",
    "message": "Operation completed successfully."
  },
  "error": null,
  "app_actions": null
}

Error Responses

Error Code	Condition
7600	Bookmark collection not found (BOOKMARK_BUCKET_NOT_FOUND)
7605	Deletion failed (BOOKMARK_BUCKET_DELETION_FAILED)