Skip to content
DoveRunner Docs

DoveRunner Piracy Guard ✨ Service API Guide

Piracy Guard exposes its data through RESTful Business APIs, making it easy for developers to integrate piracy intelligence directly into their workflows and tools. This guide walks through available endpoints, including the required request parameters and the structure of the response data. With these APIs, you can power anomaly detection and piracy analysis for DRM license activity.

These APIs make it possible to retrieve suspicious behavior logs, monitoring daily activity metrics, and surfacing the most suspicious users on your site for deeper investigation.

Authentication and Authorization

Section titled “Authentication and Authorization”

All Piracy Guard APIs require a valid JWT token in the Authorization HTTP request header. The token must be issued with your Service API Key and include the required payload fields.

DoveRunner Service API Guide - JWT Structure Details on creation of a JWT for authentication

Before calling these APIs, ensure that:

  1. Your account must be granted permission to use the Piracy Guard API

    Contact DoveRunner support via the Helpdesk to request access.

  2. You include the correct api_code for each endpoint in your request

    The api_code is validated against your account’s authorized permissions — requests with a missing or unauthorized api_code will be rejected.

    For requests, you can statically use UA003001040100.

Language Handling

Section titled “Language Handling”

Certain Piracy Guard REST APIs determine the response language using the following priority: Accept-Language header → lang query parameter → default en. The API first checks the Accept-Language header for the client’s preferred language. If it is not provided or unsupported, the lang query parameter is used instead. When neither is specified, the response defaults to English (en).

Service API

Section titled “Service API”

GET Log List

Section titled “ Log List”

Retrieves a list of anomaly detection logs for a given period.

GET /api/v2/drm/piracy-guard

HTTP Headers

Section titled “HTTP Headers”

Authorization (required)
Encoded JWT token. See the Authentication and Authorization for more details.

Accept-Language
Language for report. See the Language Handling section for more details.

Query Parameters

Section titled “Query Parameters”

api_code string (required)
Fixed code of the API (UA003001040100).

site_id string (required)
Unique identifier of the service site where the DRM request occurred (four-character alphanumeric code)

from string
Start date of search window. Calendar date based on the ISO 8601 standard following the YYYY-MM-DD format.

to string
End date of search window. Calendar date based on the ISO 8601 standard following the YYYY-MM-DD format. When no date is entered, search within the range of today’s date.

time_zone string (default: +00:00)
UTC offset based on the ISO 8601 standard following the ±[hh]:[mm] format.

search_condition string
Keyword search category

search_keyword string
Search value for the defined search_condition category

report_violation_primary_code string
Filter by violation type. Possible values are—

  • license_farming
  • bot_automation
  • token_replay
  • content_ripping
  • account_sharing

page_unit integer (default: 25, max: 1000)
Number of items to include in the response

page_index integer
Offset by this many pages, of the size of page_unit

lang string (default: en)
Language for report. See the Language Handling section for more details.

Example Request

Section titled “Example Request”
Terminal window
curl --L 'https://service.doverunner.com/api/v2/drm/piracy-guard?api_code=UA003001040100&site_id=DEMO&from=2026-01-01&to=2026-01-31' \
--H 'Authorization: Bearer <your_jwt_token>' \
--H 'Accept-Language: en'

Response

Section titled “Response”

count long
Total number of records

data array
List of Piracy Guard log entries

Expand for details

data[].anomaly integer
A numeric flag representing the anomaly detection result. This field carries the same value as anomaly_status, but expressed as an integer.

Possible values are—

FlagMeaning
0Entry is considered normal with no detected anomaly
1Entry is considered anomalous

data[].site_id string
Unique identifier of the service site where the DRM request occurred (four-character alphanumeric code)

data[].user_id string
Unique identifier of the end user who generated the DRM license requests

data[].unique_key string
A unique hash key generated from the combination of user_id and the aggregation period. Used to distinguish records for the same user across different time windows.

data[].start_date string
The start date of the aggregation period for this log entry. Formatted as YYYY-MM-DD per ISO 8601.

data[].end_date string
The end date of the aggregation period for this log entry. Formatted as YYYY-MM-DD per ISO 8601.

data[].log_date string
The timestamp at which this log record was generated, in YYYYMMDDhhmmss format

data[].license_cnt integer
Total number of DRM license requests made by the user within a 24-hour period. A count significantly exceeding typical viewing patterns may indicate automated mass requests or account sharing.

data[].req_unique_hour_cnt integer
Number of distinct hours (out of 24) during which DRM license requests were made. A high count suggests requests spread throughout the day, which may indicate automated or continuous access rather than normal viewing behavior.

data[].device_id_diversity_score float
A diversity score (0.0-1.0) reflecting how varied the device IDs are across license requests. 0.0 means all requests came from the same device; 1.0 means every request used a different device ID. Higher values may suggest access from multiple devices, potentially indicating account sharing.

data[].device_model_diversity_score float
A diversity score (0.0-1.0) measuring the variety of device models (e.g., iPhone 12, Galaxy S21) used across requests. A high score under a single account may point to abnormal access patterns.

data[].device_type_diversity_score float
A diversity score (0.0-1.0) reflecting the variety of device types (e.g., Phone, Tablet, TV, Mac) used. A high score from a single user may suggest simultaneous access across multiple device categories, consistent with account sharing.

data[].device_category_unique_cnt integer
Number of distinct device categories (PC, Mobile, TV, Others) observed across requests in a 24-hour period. The maximum value is 4. A higher count suggests access from a broader range of device environments.

data[].device_category_pc_ratio float
Proportion of DRM license requests originating from PC devices, ranging from 0.0 to 1.0

data[].device_category_mobile_ratio float
Proportion of DRM license requests originating from mobile devices (smartphones, tablets, etc.), ranging from 0.0 to 1.0

data[].device_category_tv_ratio float
Proportion of DRM license requests originating from TV devices, ranging from 0.0 to 1.0

data[].device_category_others_ratio float
Proportion of DRM license requests originating from device types not classified as PC, Mobile, or TV, ranging from 0.0 to 1.0

data[].drm_type_unique_cnt integer
Number of distinct DRM types (Widevine, FairPlay, PlayReady) used within a 24-hour period. Since different platforms use different DRM systems (e.g., iOS uses FairPlay, Android uses Widevine), multiple DRM types can reflect legitimate multi-device usage.

data[].drm_type_widevine_ratio float
Proportion of license requests using Widevine DRM, ranging from 0.0 to 1.0

data[].drm_type_fairplay_ratio float
Proportion of license requests using FairPlay DRM, ranging from 0.0 to 1.0

data[].drm_type_playready_ratio float
Proportion of license requests using PlayReady DRM, ranging from 0.0 to 1.0

data[].os_type_unique_cnt integer
Number of distinct operating systems observed across DRM license requests in a 24-hour period. A value of 3 (e.g., iOS, Android, Windows) is not inherently abnormal and may simply reflect legitimate multi-device usage.

data[].os_type_ios_ratio float
Proportion of DRM license requests originating from iOS devices, ranging from 0.0 to 1.0

data[].os_type_android_ratio float
Proportion of DRM license requests originating from Android devices, ranging from 0.0 to 1.0

data[].os_type_mac_ratio float
Proportion of DRM license requests originating from macOS devices, ranging from 0.0 to 1.0

data[].os_type_windows_ratio float
Proportion of DRM license requests originating from Windows devices, ranging from 0.0 to 1.0

data[].os_type_web_ratio float
Proportion of DRM license requests originating from web browser environments (web runtime), ranging from 0.0 to 1.0

data[].os_type_others_ratio float
Proportion of DRM license requests from operating systems not classified as iOS, Android, macOS, Windows, or Web, ranging from 0.0 to 1.0

data[].region_unique_cnt integer
Number of distinct AWS regions from which DRM license requests originated (e.g., Seoul, Frankfurt). A higher count indicates geographically distributed access, which may be a sign of account sharing via VPN or proxy.

data[].cid_diversity_score float
A diversity score (0.0-1.0) reflecting the variety of Content IDs requested. 0.0 means all requests were for the same content; 1.0 means every request targeted a different Content ID. A low score combined with a high request count may suggest repeated license harvesting for specific content.

data[].scheme_unique_cnt integer
Number of distinct URI schemes (e.g., http, https) used in DRM license request URLs. The maximum value is 2. Generally, the value should be 1 for it to be normal.

data[].path_unique_cnt integer
Number of unique URL paths sent to the DoveRunner Multi-DRM license server within a 24-hour period. A higher count indicates access to a wider range of license endpoints.

data[].ip_pattern_unique_cnt integer
Number of unique IP hop patterns observed in the network paths of DRM license requests (e.g., a 4-hop path and a 5-hop path count as 2 distinct patterns). A higher count suggests access from multiple network environments or routing through proxies.

data[].security_level_unique_cnt integer
Number of distinct DRM security levels observed across license requests in a 24-hour period. Each DRM type defines its own security tiers (e.g., Widevine L1/L3, PlayReady SL150/SL3000). A higher count may indicate access from multiple device types or environments under the same account.

data[].security_policy_diversity_score float
A diversity score (0.0-1.0) reflecting the variety of DRM security policy configurations applied across requests. A value near 0.0 is common in services with standardized policies and is not, by itself, an indicator of abnormal behavior.

data[].playback_policy_diversity_score float
A diversity score (0.0-1.0) reflecting the variety of DRM playback policy configurations applied across requests. Similar to security policy, a low score is expected when the service applies standardized playback policies across all content and users.

data[].token_avg_time_diff float
Average time (in seconds) between DRM license token creation and the actual license request. In normal client behavior, this gap is typically a few seconds due to sequential processing. A value significantly above 10 seconds may indicate delayed reuse, consistent with token harvesting or replay attacks.

data[].req_avg_time_diff float
Average time (in seconds) between consecutive DRM license requests from the same user within a 24-hour period. Typical values fall around 5,000-6,000 seconds. Very short intervals may indicate bots or automated mass requests, although legitimately browsing or sampling multiple content items can also produce short gaps.

data[].hash_duplication_score float
A duplication score (0.0-1.0) measuring how often the same license token hash appears across requests. 0.0 means all hashes are unique; 1.0 means all requests used the same hash. Any value above 0.0 indicates token reuse, and higher values suggest a greater likelihood of token replay or license farming. Hash values are based on the Hash Message Format.

data[].session_id_duplication_score float
A duplication score (0.0-1.0) measuring the degree to which session IDs are reused across DRM license requests. 0.0 means all session IDs are unique; 1.0 means a single session ID was used for all requests. Higher values may indicate session reuse, consistent with automated access or session hijacking.

data[].anomaly_status string
A human-readable string representing the anomaly detection result. normal indicates no anomaly was detected; abnormal indicates the entry was flagged. This field carries the same value as the anomaly flag, expressed in a more readable format.

data[].report_incident_report string
A detailed incident summary generated from variable fact evidence generated by Piracy Guard. Explicitly references license_cnt and explains why the observed behavior deviates from normal patterns — for example, avg_delay_between_requests being far below the typical 5,000-6,000s range, multiple DRM types observed in a short window, or elevated region_unique_cnt.

data[].report_reasoning string
A list of key reasons behind the anomaly determination. Each element references a specific feature from the user statistics — such as abnormally high license_cnt, shortened avg_delay_between_requests, or elevated device_id_diversity_score — and explains its significance. Provided as a JSON array encoded as a string.

data[].report_risk_level string
The overall risk level of the detected anomalous activity. Possible values are high, medium, or low.

data[].report_violation_notes string
A concise technical note linking quantitative evidence to the identified violation type. Written by directly citing actual feature names and values from the input, for example:

avg_delay_between_requests=35s (bucketed to 40s), session_id_duplication_score=0.80, region_unique_cnt=3.

data[].report_violation_primary_code string
The code identifying the most likely violation type. Possible values are—

  • license_farming
  • bot_automation
  • token_replay
  • content_ripping
  • account_sharing

data[].report_violation_primary string
A JSON object (encoded as a string) containing detailed information about the primary violation type. Includes the violation code (code), English description (en), Korean description (ko), and confidence score (confidence). When no anomaly is detected, code is set to none and confidence to 0.0.

data[].report_violation_primary_confidence float
A confidence score (0.0-1.0) representing the model’s certainty in the primary violation classification. A higher value indicates greater confidence in the assigned violation type. This value is set to 0.0 when no anomaly is detected.

GET Daily Statistics

Section titled “ Daily Statistics”

Retrieves a list of daily suspicious activity statistics for the specified month. If requesting for the current month, results returned will include items from the first of the current month through yesterday.

GET /api/v2/drm/piracy-guard/statistics

HTTP Headers

Section titled “HTTP Headers”

Authorization (required)
Encoded JWT token. See the Authentication and Authorization for more details.

Query Parameters

Section titled “Query Parameters”

api_code string (required)
Fixed code of the API (UA003001040100)

site_id string (required)
Unique identifier of the service site where the DRM request occurred (four-character alphanumeric code)

target_date string (required)
Reference date. Calendar date based on the ISO 8601 standard following the YYYY-MM-DD format.

Example Request

Section titled “Example Request”
Terminal window
curl --L 'https://service.doverunner.com/api/v2/drm/piracy-guard/statistics?api_code=UA003001040100&site_id=DEMO&target_date=2025-11-01' \
--H 'Authorization: Bearer <your_jwt_token>'

Response

Section titled “Response”

count long
Total number of records

data array
List of Piracy Guard daily statistics entries

Expand for details

data[].target_date integer
Target day of the month

data[].site_suspicious_cnt long
Daily suspicious activity count

data[].risk_level_distribution object
Daily distribution by risk level. Keys with a zero value are not included in the response data.

Expand for details

data[].risk_level_distribution.high integer
Violations that were marked as high risk

data[].risk_level_distribution.medium integer
Violations that were marked as medium risk

data[].risk_level_distribution.low integer
Violations that were marked as low risk

data[].violation_type_distribution object
Daily distribution by violation type. Keys with a zero value are not included in the response data.

Expand for details

data[].risk_level_distribution.license_farming integer
Count of occurrences of license_farming violations

data[].risk_level_distribution.bot_automation integer
Count of occurrences of bot_automation violations

data[].risk_level_distribution.token_replay integer
Count of occurrences of token_replay violations

data[].risk_level_distribution.content_ripping integer
Count of occurrences of content_ripping violations

data[].risk_level_distribution.account_sharing integer
Count of occurrences of account_sharing violations

data[].site_suspicious_acc_cnt long
Monthly cumulative suspicious activity count

data[].risk_level_acc_distribution object
Monthly cumulative distribution by risk level. Keys with a zero value are not included in the response data.

Expand for details

data[].risk_level_distribution.high integer
Violations that were marked as high risk

data[].risk_level_distribution.medium integer
Violations that were marked as medium risk

data[].risk_level_distribution.low integer
Violations that were marked as low risk

data[].violation_type_acc_distribution object
Monthly cumulative distribution by violation type. Keys with a zero value are not included in the response data.

Expand for details

data[].violation_type_acc_distribution.license_farming integer
Count of occurrences of license_farming violations

data[].violation_type_acc_distribution.bot_automation integer
Count of occurrences of bot_automation violations

data[].violation_type_acc_distribution.token_replay integer
Count of occurrences of token_replay violations

data[].violation_type_acc_distribution.content_ripping integer
Count of occurrences of content_ripping violations

data[].violation_type_acc_distribution.account_sharing integer
Count of occurrences of account_sharing violations

GET Top Suspicious Users

Section titled “ Top Suspicious Users”

Retrieves the top users ranked by monthly suspicious activity count.

GET /api/v2/drm/piracy-guard/users/top

HTTP Headers

Section titled “HTTP Headers”

Authorization (required)
Encoded JWT token. See the Authentication and Authorization for more details.

Query Parameters

Section titled “Query Parameters”

api_code string (required)
Fixed code of the API (UA003001040100)

site_id string (required)
Unique identifier of the service site where the DRM request occurred (four-character alphanumeric code)

target_date string (required)
Reference date. Calendar date based on the ISO 8601 standard following the YYYY-MM-DD format.

Example Request

Section titled “Example Request”
Terminal window
curl --L 'https://service.doverunner.com/api/v2/drm/piracy-guard/users/top?api_code=UA003001040100&site_id=DEMO&target_date=2025-11-01' \
--H 'Authorization: Bearer <your_jwt_token>'

Response

Section titled “Response”

count long
Total number of records

data array
List of monthly top suspicious users

Expand for details

data[].user_id string
Unique identifier of the end user who generated the DRM license requests

data[].site_suspicious_cnt long
Number of suspicious activity occurrences