Channel 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 Channel Management API v3 Reference

Feature scope by version

New in v3: Endpoints for channel-specific independent settings—such as callback URL configuration, security feature settings, referrer-based access control, and player skin association—are newly added features in v3.
Common authentication: APIs in all versions use a common authentication method via a query string parameter (?access_token=). For the common specification on error determination criteria, refer to the Core Changes section of the API v3 Migration Guide.

Retrieve channel list

Legacy (v1): GET /media/channel/index
Changed (v3): GET /channels

Changes

Response data structure change: The array location in the returned data has changed from the previous result.items[] structure to a data[] structure, and a pagination object has been added for paging.
Filter and pagination parameters added: v1 only supported the order parameter, but v3 adds kind, status, page, and per_page parameters.

Detailed mapping of request parameters and response fields

Request query parameters

Parameter	v1 support	v3 support	Description
`order`	Supported (combination of `created_at`/`position` and `asc`/`desc`, default: `position_asc`)	Supported (same Enum specification as v1)	Sort criteria
`kind`	Not supported	Supported	Filter by channel type
`status`	Not supported	Supported	Filter by channel activation status (`0`: inactive, `1`: active)
`page`	Not supported	Supported	Page number to retrieve
`per_page`	Not supported	Supported	Number of data items output per page

Response field mapping

The key, name, and position fields remain the same across all versions.

Field	v1 structure (`result.items[]`)	v3 structure (`data[]`, `ApiVodChannel` object)	Notes
Content count	`count_of_media_contents`	`count_of_contents`	Name simplified
Active status	`status` (integer, active if `1`)	`status` (Boolean)	Data type changed
Channel type	Returned as a top-level response attribute	Separated from the response body	-
Newly added fields	-	`description`, callback and security-related setting fields (`use_pingback`, `pingback_url`, etc.)	Additional fields added

Channel object specification

The ApiVodChannel object in the v3 response specification has the following structure.

{
  "key": "string",
  "name": "string",
  "description": "string",
  "use_pingback": true,
  "pingback_url": "string",
  "leave_pingback_url": "string",
  "play_callback_url": "string",
  "use_referer_check": 0,
  "referer_check_domains": "string",
  "referer_reject_domains": "string",
  "referer_empty_allow": true,
  "use_pc_download": true,
  "pc_download_callback_url": "string",
  "use_mobile_download": true,
  "mobile_download_callback_url": "string",
  "default": true,
  "is_shared": true,
  "is_encrypted": true,
  "disable_tvout": true,
  "count_of_contents": 0,
  "position": 0,
  "status": true,
  "created_at": "string",
  "updated_at": "string"
}

Create a new channel

Legacy (v1): POST /media/channel/create
Changed (v3): POST /channels

Changes

Setting fields separated: The pingback and playback control-related fields that existed in the v1 create API have been removed from the v3 create specification. In v3, these must be configured through a separate callback endpoint after channel creation is complete.
Unsupported field conversion: The media_player_policy and progress_plugin fields from v1 have been removed in v3 with no replacement fields.
Response data specification enhanced: In v1, only the created unique key information (result.key) was returned upon success, but in v3, the entire newly created channel object is returned along with an HTTP 201 Created status code.

Detailed request body and response structure

Request body

Field	Data type (v1)	Data type (v3)	Required	Description
`name`	String	String	Required	Name of the channel to create (up to 50 characters)
`is_shared`	Integer	Integer	Optional	Channel sharing policy setting (`0`(default): non-shared channel, `1`: shared channel)
`is_encrypted`	Integer	Integer	Optional	Channel security policy setting (`0`(default): standard channel, `1`: encrypted content-only channel)
`use_pingback`	Integer	-	-	Functionality moved to the v3-only callback endpoint
`pingback_url`	String	-	-	Functionality moved to the v3-only callback endpoint
`media_player_policy`	String	-	-	Field removed in v3
`progress_plugin`	Integer	-	-	Field removed in v3
`description`	-	String	Optional	Channel description (newly added in v3)

Response structure comparison

v1: Only a unique key form is returned upon success, and the response message contains a spelling error (sucessfully).

{ "error": 0, "message": "sucessfully", "result": { "key": "key_string" } }

v3: Returns the standard data structure.

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

Retrieve channel information

Legacy (v1/v2): Not supported (no single-item retrieval endpoint)
Changed (v3): GET /channels/{channel_key}

Detailed response structure

Response structure specification

The response fields are identical to the Retrieve channel list specification.

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

Update channel information

Legacy (v1/v2): Not supported
Changed (v3): PUT /channels/{channel_key}

Detailed request body and response structure

Request body

Field	Data type	Required	Description
`name`	String	Required	Channel name
`description`	String	Optional	Channel description
`use_realtime`	Integer	Optional	Whether to use real-time streaming (HLS) (`0`: not used, `1`: used)
`use_aes128`	Integer	Optional	Whether to use AES-128 encryption (`0`: not used, `1`: used)

Response structure specification

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

Delete a channel

Legacy (v1): POST /media/channel/delete/{channel_key}
Changed (v3): DELETE /channels/{channel_key}

Changes

HTTP method conversion: The HTTP method has changed from POST to DELETE.
Simplified response structure: The previous success response format has been simplified to return an empty array structure ("data": []) indicating that the deletion has been approved.

Retrieve content list by channel

Legacy (v1): GET /media/channel/media_content
Legacy (v2): GET /vod/channels/{media_package}/media-contents
Changed (v3): GET /channels/{channel_key}/media-contents

Changes

Path parameter conversion: The method of passing the channel identifier has been standardized from the query string structure in v1 to a URL path parameter structure. v2 used media_package as the path parameter name, but v3 has unified it as channel_key.
Filter parameters added: v3 adds a rich set of conditional query parameters, including sorting and paging as well as search and status filters.

Detailed request parameters and response structure

Request query parameters

order, page, per_page: Sort method and paging control for the retrieval
keyword, state, encryption, publish, content_type: Status value and type filters
exist_original, exist_subtitle: Filters for whether an original file or subtitle exists
start_date, end_date: Date range search filters

Response structure comparison

{ "error": 0, "result": { "count": 10, "order": "position_asc", "per_page": 20, "items": { "item": [] } } }

{ "data": [{ "transcoding_files": [], "subtitles": [] }] }

{ "data": [ApiVodMediaContent object], "pagination": { "current_page": 1, "per_page": 10, "total": 100 } }

Retrieve a single content item in a channel

Legacy (v1): GET /media/channel/media_content/{upload_file_key}
Changed (v3): Not supported (see API consolidation notice below)

API consolidation notice

In v3, the single-item retrieval API for content within a channel has been deprecated. It has instead been consolidated into the general-purpose content management single-item retrieval feature, GET /media-contents/{upload_file_key}, which guarantees the same data scope.

Attach channel to content

Legacy (v1): POST /media/channel/attach/{upload_file_key}
Changed (v3): POST /channels/{channel_key}/media-contents/{upload_file_key}/attach

Caution regarding identifier parameter mapping

In v1, only the content identifier (upload_file_key) was included in the URL path, while the target channel key (channel_key) was sent in the request body. In v3, however, both identifiers are placed sequentially in the URL path parameters.

If you mechanically substitute only the URL endpoint address based on the v1 implementation, the channel key and content key information in the path may become misaligned and incorrectly mapped, resulting in an unintended connection or a connection failure (404 Not Found). You must be sure to verify the parameter binding order.

Detailed request parameter transmission locations and response structure

Request parameter transmission location comparison

Category	v1	v3
`channel_key`	Request body	URL path parameter (placed first)
`upload_file_key`	URL path parameter	URL path parameter (placed second)

Response structure comparison

{ "error": 0, "message": "...", "result": { "media_content_key": "..." } }

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

Detach channel from content

Legacy (v1): POST /media/channel/detach/{upload_file_key}
Changed (v3): DELETE /channels/{channel_key}/media-contents/{upload_file_key}/detach

Changes

HTTP method conversion: The HTTP method has changed from POST to DELETE.
Parameter location change: The channel key (channel_key) item, which was previously included in the request body structure, is now included as a URL path parameter.
Response data standardization: Upon success, an empty array structure ("data": []) is returned instead of a text response value.

Attach channel to player skin

Legacy (v1/v2): Not supported
Changed (v3): POST /channels/{channel_key}/player-skins/{skin_id}/attach

Detailed response structure

Response structure specification

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

Detach channel from player skin

Legacy (v1/v2): Not supported
Changed (v3): DELETE /channels/{channel_key}/player-skins

Detailed response structure

Response structure specification

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

Configure callback URL - content add/remove/playback

Legacy (v1/v2): Not supported
Changed (v3): PUT /channels/{channel_key}/callback

New feature notice

The settings structure for pingback and playback control, which was previously handled collectively as attributes of the v1 create API, has been separated into an independent API.

Detailed request body and response structure

Request body

Field	Data type	Required	Description
`use_pingback`	Integer	Required	Enable callback feature (`0`: disabled, `1`: enabled)
`pingback_url`	String	Optional	Content channel addition callback URL
`leave_pingback_url`	String	Optional	Content channel deletion callback URL
`play_callback_url`	String	Optional	Playback callback URL

Response structure specification

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

Configure callback URL - download

Legacy (v1/v2): Not supported
Changed (v3): PUT /channels/{channel_key}/download-callback

Detailed request body and response structure

Request body

Field	Data type	Required	Description
`use_pc_download`	Integer	Required	Enable PC download feature (`0`: disabled, `1`: enabled)
`pc_download_callback_url`	String	Optional	PC download callback URL
`use_mobile_download`	Integer	Required	Enable mobile download feature (`0`: disabled, `1`: enabled)
`mobile_download_callback_url`	String	Optional	Mobile download callback URL

Response structure specification

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

Block external display output

Legacy (v1/v2): Not supported
Changed (v3): PUT /channels/{channel_key}/security

Detailed request body and response structure

Request body

Field	Data type	Required	Description
`disable_tvout`	Integer	Required	Block external display output setting (`0`: not blocked, `1`: blocked)

Response structure specification

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

Referrer-based access control

Legacy (v1/v2): Not supported
Changed (v3): PUT /channels/{channel_key}/referer

Detailed request body and response structure

Request body

Field	Data type	Required	Description
`use_referer_check`	Integer	Required	Referrer access control policy setting (`1`: allow specific domains, `2`: block specific domains)
`referer_check_domains[]`	Array	Optional	List of domain addresses allowed to play
`referer_reject_domains[]`	Array	Optional	List of domain addresses to block from playing
`referer_empty_allow`	Boolean	Optional	Whether to block requests with no referrer information

Response structure specification

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

Retrieve channel list​

Request query parameters​

Response field mapping​

Channel object specification​

Create a new channel​

Request body​

Response structure comparison​

Retrieve channel information​

Response structure specification​

Update channel information​

Request body​

Response structure specification​

Delete a channel​

Retrieve content list by channel​

Request query parameters​

Response structure comparison​

Retrieve a single content item in a channel​

Attach channel to content​

Request parameter transmission location comparison​

Response structure comparison​

Detach channel from content​

Attach channel to player skin​

Response structure specification​

Detach channel from player skin​

Response structure specification​

Configure callback URL - content add/remove/playback​

Request body​

Response structure specification​

Configure callback URL - download​

Request body​

Response structure specification​

Block external display output​

Request body​

Response structure specification​

Referrer-based access control​

Request body​

Response structure specification​

Retrieve channel list

Request query parameters

Response field mapping

Channel object specification

Create a new channel

Request body

Response structure comparison

Retrieve channel information

Response structure specification

Update channel information

Request body

Response structure specification

Delete a channel

Retrieve content list by channel

Request query parameters

Response structure comparison

Retrieve a single content item in a channel

Attach channel to content

Request parameter transmission location comparison

Response structure comparison

Detach channel from content

Attach channel to player skin

Response structure specification

Detach channel from player skin

Response structure specification

Configure callback URL - content add/remove/playback

Request body

Response structure specification

Configure callback URL - download

Request body

Response structure specification

Block external display output

Request body

Response structure specification

Referrer-based access control

Request body

Response structure specification