V1 API MCQ Actions

Source: OpenAPI 3.1.0 spec + src/api/v1/mcq_attrs/routes.py, src/api/v1/mcq_attrs/schemas.py Tag: MCQ Actions - Attempt, bookmark, reactions on MCQs.

All endpoints require Bearer Token authentication. All mutation endpoints return encrypted empty payload. User ID is extracted from JWT claims.

---

POST /mcqs_attrs/reactions

Summary: Like/Dislike MCQ

Bulk like/dislike interactions on MCQs.

Parameters

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

Request Body

{
  "reactions": [
    {
      "mcq_id": "60d5ec49f1b2c72e4c8b4567",
      "reaction_status": 1
    },
    {
      "mcq_id": "60d5ec49f1b2c72e4c8b4568",
      "reaction_status": 3
    }
  ]
}

Field	Type	Required	Description
reactions	array	required	Array of reaction operations
reactions[].mcq_id	ObjectId	required	MCQ to react to
reactions[].reaction_status	integer	required	LIKE=1, DISLIKE=2, NONE=3 (removes reaction)

Success Response

{
  "status": "success",
  "is_data_encrypted": 0,
  "data": null,
  "error": null,
  "app_actions": null
}

---

GET /mcqs_attrs/sync

Summary: List MCQ Reactions

Retrieve a paginated list of the user’s MCQ attributes (reactions, bookmarks, attempts) with forward-only pagination based on updated_at timestamp.

Parameters

Name	In	Required	Constraints	Description
course_id	query	required	CourseEnum	Course ID
limit	query	optional	1-120, default 10	Number of results to return
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": "60d5ec49f1b2c72e4c8baaaa",
      "mcq_id": "60d5ec49f1b2c72e4c8b4567",
      "last_attempt_option": "option_2",
      "guessed": false,
      "bookmark_status": 1,
      "bookmark_collection_ids": [
        "60d5ec49f1b2c72e4c8bcccc",
        "60d5ec49f1b2c72e4c8bdddd"
      ],
      "bookmarked_at": 1714400000000,
      "like_status": 1,
      "root_taxonomy_id": "60d5ec49f1b2c72e4c8b0001",
      "taxonomy_ids": [
        "60d5ec49f1b2c72e4c8b0001",
        "60d5ec49f1b2c72e4c8b0002",
        "60d5ec49f1b2c72e4c8b0003"
      ],
      "year": 2023
    }
  ],
  "error": null,
  "app_actions": null,
  "pagination": {
    "next_cursor": "eyJ1cGRhdGVkX2F0IjoxNzE0NDAwMDAwMDAwfQ==",
    "prev_cursor": null,
    "limit": 10,
    "has_more": true
  }
}

Field	Type	Description
last_attempt_option	string/null	Most recent attempt: "option_1" through "option_4", or null if never attempted
guessed	boolean	Whether the latest attempt was marked as guessed
bookmark_status	integer	BOOKMARKED=1, NOT_BOOKMARKED=2
bookmark_collection_ids	array	Collection IDs this MCQ is bookmarked into. Empty if not bookmarked
bookmarked_at	integer/null	Epoch ms when bookmarked. Independent of updated_at. null if never bookmarked
like_status	integer	LIKE=1, DISLIKE=2, NONE=3
root_taxonomy_id	ObjectId/null	Denormalized L1 taxonomy from the MCQ
taxonomy_ids	array/null	[L1, L2, L3] denormalized from the MCQ
year	integer/null	MCQ year, denormalized from the MCQ

---

POST /mcqs_attrs/bookmark

Summary: Bookmark MCQ

Bulk bookmark MCQs into collections.

Parameters

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

Request Body

{
  "bookmarks": [
    {
      "mcq_id": "60d5ec49f1b2c72e4c8b4567",
      "bookmark_status": 1,
      "collection_ids": ["60d5ec49f1b2c72e4c8bcccc"]
    },
    {
      "mcq_id": "60d5ec49f1b2c72e4c8b4568",
      "bookmark_status": 2,
      "collection_ids": ["60d5ec49f1b2c72e4c8bcccc"]
    }
  ]
}

Field	Type	Required	Description
bookmarks	array	required	Array of bookmark operations
bookmarks[].mcq_id	ObjectId	required	MCQ to bookmark
bookmarks[].bookmark_status	integer	required	BOOKMARKED=1, NOT_BOOKMARKED=2
bookmarks[].collection_ids	array	conditional	Collection IDs to add/remove from

Conditions:

• When bookmark_status=1 (BOOKMARKED): collection_ids can be omitted or empty (defaults to “All Bookmarks” collection)
• When bookmark_status=2 (NOT_BOOKMARKED): collection_ids must be provided and non-empty; error 1006 (VALIDATION_FAILED) if missing

Success Response

{
  "status": "success",
  "is_data_encrypted": 0,
  "data": null,
  "error": null,
  "app_actions": null
}

---

POST /mcqs_attrs/attempt

Summary: Attempt MCQ

Submit MCQ attempt answers (bulk). Records the user’s selected option for each MCQ.

Parameters

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

Request Body

{
  "attempts": [
    {
      "mcq_id": "60d5ec49f1b2c72e4c8b4567",
      "selected_option": "option_2",
      "guessed": false
    },
    {
      "mcq_id": "60d5ec49f1b2c72e4c8b4568",
      "selected_option": -1,
      "guessed": null
    }
  ]
}

Field	Type	Required	Description
attempts	array	required	Array of attempt operations
attempts[].mcq_id	ObjectId	required	MCQ being attempted
attempts[].selected_option	string or integer	required	"option_1" through "option_4", or -1 for skipped
attempts[].guessed	boolean/null	optional	true = user marked as guess, null = do not update existing value

Success Response

{
  "status": "success",
  "is_data_encrypted": 0,
  "data": null,
  "error": null,
  "app_actions": null
}