Bookmark Management

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

Go to Bookmark Management API v3 Reference→

Feature scope by version

• v1: Bookmark-related features are not supported.
• v2: Only bookmark list retrieval is supported, in a limited manner.
• v3: In addition to enhanced list retrieval, bookmark add/edit/delete features have been added.
• Common authentication: All API versions use a common authentication method via a query string parameter (?access_token=). For a common specification of error determination criteria, refer to the Core Changes section of the API v3 migration guide.

v2 error response specification (Laravel framework style)

Error handling for the v2 bookmark API differs from the typical VOD API, which returns an HTTP 200 status code with { "error": 1 } in the body. As shown in the examples below, it returns the actual corresponding HTTP status code along with a specific error object ({ message, errors }) structure.

• Invalid upload_file_key provided: HTTP 422 + { "message": "The given data was invalid.", "errors": {...} }
• Non-existent client_user_id provided: HTTP 404 + { "message": "Record not found" }

---

Retrieve bookmark list (by upload file key)

• Legacy (v1): Not supported
• Legacy (v2): GET /vod/bookmarks
• Changed (v3): GET /media-contents/{upload_file_key}/bookmarks

Changes

• Identifier parameter location change: upload_file_key, which was passed as a query parameter in v2, has been changed to a path parameter specification in v3.
• Additional response fields: Unique identifier (id) and time information (created_at, updated_at) fields have been added.

Request parameter and response structure details

Request query parameters

In v2, retrieval was also possible via media_content_key on the same endpoint, but in v3, a separate endpoint (/media-content-keys/{media_content_key}/bookmarks) that uses media_content_key as a path parameter has been introduced, so only retrieval by upload_file_key is supported.

• v2: media_content_key, upload_file_key, client_user_id
• v3: client_user_id

Response structure comparison

• v2

{
  "data": [
    {
      "kind": 0,
      "label": "bookmark_title",
      "position": 1,
      "value": "bookmark_content"
    }
  ]
}

• v3

{
  "data": [
    {
      "id": 1,
      "kind": 0,
      "label": "bookmark_title",
      "position": 120,
      "value": "bookmark_content",
      "created_at": "2026-02-27T06:34:22+00:00",
      "updated_at": "2026-02-28T06:34:22+00:00"
    }
  ]
}

---

Retrieve bookmark list (by media content key)

• Legacy (v1/v2): Not supported (v2 replaced this feature with a query parameter on the upload file key-based API above.)
• Changed (v3): GET /media-content-keys/{media_content_key}/bookmarks

New feature

This is a logically separated endpoint newly introduced in v3. It retrieves the bookmark list using the identifier media_content_key as a path parameter.

Request parameter and response structure details

Request query parameters

Parameter	Data Type	Required	Description
client_user_id	String	Required	customer user ID

Response structure specification

The response specification is identical to that of Retrieve bookmark list (by upload file key).

---

Add bookmark

• Legacy (v1/v2): Not supported
• Changed (v3): POST /media-contents/{upload_file_key}/bookmarks

Request body and response structure details

Request body

Field	Data Type	Required	Description
position	Integer	Required	Position to set the bookmark (sec)
value	String	Optional	Bookmark content

Response structure specification

{
  "data": ApiVodBookmark object,
  "status": "ok"
}

---

Edit bookmark

• Legacy (v1/v2): Not supported
• Changed (v3): PUT /media-contents/{upload_file_key}/bookmarks/{bookmark_id}

Request body and response structure details

Request body

Field	Data Type	Required	Description
value	String	Required	Bookmark content to update

Response structure specification

{
  "data": ApiVodBookmark object,
  "status": "ok"
}

---

Delete bookmark

• Legacy (v1/v2): Not supported
• Changed (v3): DELETE /media-contents/{upload_file_key}/bookmarks/{bookmark_id}

Response structure details

Response structure specification

{
  "data": [],
  "status": "ok"
}