---
title: "Watermark Detection API Guide"
description: "This document explains how to request watermark detection and receive the result via DoveRunner API specification."
---
> For the complete documentation index, see [llms.txt](https://docs.doverunner.com/llms.txt).
DoveRunner automated watermark detection operates using a `blind` detection approach.
During detection, the system analyzes video frames to identify the embedded watermark pattern and decrypts the watermark payload using the secret key that was used at the time of watermark insertion.
If a valid watermark payload is successfully extracted, the detection service queries the session database to locate the session record associated with the extracted payload. The corresponding session information is then returned as the detection result.
```mermaid
sequenceDiagram
box Content Service
participant A as Service site
end
box DoveRunner
participant B as DoveRunner service
end
A ->> B: Suspicious content
Note right of B: Detect watermark (payload)
B -->> B: Analyze video frames
opt Watermark detected
Note right of B: Session database
B -->> B: Find session data
end
B ->> A: Report detection result
```
## Requirements for Detection
:::note
For watermark detection, a continuous recorded video of at least 5 minutes is required. The DoveRunner Forensic Watermarking solution is designed to be robust against common attacks, including video resizing.
However, the watermark detection success rate can vary depending on the quality of the input video, such as resolution, bitrate, camera shake, and other recording conditions.
The minimum recommended input specification for reliable detection is 480p resolution at 1 Mbps or higher. In practice, most videos with a resolution of 720p or above can be successfully detected.
Incase there is lot of distortion and auto detection fails, as Doverunner supports non-blind detection as well
the original video or even some snapshots of original content is provided through support ticket the expert team would try to extract the embedded watermark information.
:::
The detailed requirements for watermark detection are as follows:
| Item | Description |
| :--- | :-- |
| Minimum video length | In order to detect watermarks, continuous recorded video without repeating sections with a length of at least 5 minutes is required |
| Video quality | At least 480p with 1Mbps is required for detection. 720p or higher quality recommended |
| Video stability | Requires fixed recorded video without shaking. Undetectable if the screen is shaken due to shooting with a handheld camera or smartphone |
| Buffering or freezing | There must be a section that was played normally without buffering or screen freezing for at least 5 minutes |
## DoveRunner HTTP API Specification
The HTTP API requests used by the DoveRunner service follow the specifications below.
> Please find the API request sample code in [Sample Download page](https://docs.doverunner.com/content-security/forensic-watermarking/getting-started/fwm-downloads/).
### Request
|Name|Value|
|---|---|
|pallycon-apidata|base64 Encoding ( JSON string )|
#### Request Data JSON Format
```json
{
"data":"{aes256 cbc encryption of 'API data' for each API, and base64 encoding}",
"timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
"hash":"{sha256 hash of 'message format' in base64 string}"
}
```
**Request Data Specification**
| Name
| Value
| Required
| Description |
| ---- | ----- | ---- | -------------- |
| `data` | String | Y | AES encryption on the JSON string generated by the specification for each API, and the result value is input as a base64 string. |
| `timestamp` | String | Y | Enter the time of the request at the GMT time zone in "yyyy-mm-ddThh: mm: ssZ" format. |
| `hash` | String | Y | Enter the hash value generated according to the following specification. |
**AES256 Encryption**
Aes256 encryption / decryption processing is performed as below using the site key value issued when joining DoveRunner service. (Check DoveRunner Console site)
- mode : CBC
- AES key : 32 byte (Site key issued from DoveRunner Console site)
- AES IV : fixed 16 byte (0123456789abcdef)
- padding : pkcs7
**SHA256 message Format**
The input value of the SHA256 hash is a combination of the following strings.
```txt
[site access key] + [site_id] + [json.data] + [json.timestamp]
```
- site access key: It is the access key value that is issued when creating DoveRunner cloud service site. It can be checked on the DoveRunner Console page.
- The resulting value of the sha256 hash function must be input to the base64 function as a binary data, not as a string.
## JWT Authorization Specification
You can call the Session API by setting the data issued through the token api in the `Authorization` header.
### Authentication Token
When calling the Session API, you need to set an authentication token issued by the process below.
**Step 1: Generate the base64 encoded Authorization parameter**
1. Open the [Base64 encoder / decoder](https://lab.doverunner.com/playground/common-tools#base64) in the DoveRunner Lab Playground.
2. While `Encrypt` option is selected, enter the `AccountID:AccessKey` value in the left text field.
3. Base64 encoded output will be displayed as the screenshot below.
4. Copy the output value to use in the next step.
> You need to input the `AccountID` and `AccessKey` values for your DoveRunner service account.
**Step 2: Use the parameter value to generate the Authorization token.**
Call the token API URL with base64 encoded value in the `Authorization` request header.
- URL: https://wm-detection.doverunner.com/api/token/[SITE_ID]/
- Method: GET
#### Path Parameter
| Parameter | Format | Description |
| --- | --- | --- |
| siteId | four alphanumeric characters | Your DoveRunner Site ID shown on Console |
#### Request Header
| Name | Description |
| --- | --- |
| Authorization | Basic Auth : Basic base64encode(accountId:accessKey) |
**Sample Request**
```
GET /api/v2/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: wm-detection.doverunner.com
```
#### Response Data Fields
| Field Name | Type | Info |
| --- | --- | --- |
| error_code | String | error code |
| error_message | String | error message |
| data.token | String | api auth token |
**Sample Response**
```json
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 112
{
"error_code" : "0000",
"error_message" : "Success.",
"data" : {
"token" : "Bearer valid-token"
}
}
```
### API Request Header
You can call the Session API by setting the data issued through the token api in the authorization header.
#### Common Response Specifications
**Response Status**
| HTTP Status Code | Description |
| --- | --- |
| Error code | Description |
| 401 | Incorrect JWT Token specification or user information not found |
| 403 | You do not have permission to use the API. |
| 200 | Success |
**Response Data Fields**
| **Key** | **type** | **Value** |
| --- | --- | --- |
| error_code | String | 0000: Success / Other values indicate failure |
| error_message | String | Error message |
| data | Json | Api result |
## Detection request registration API using URL
This API is for requesting a watermark detection using url.
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/url
* method : POST
* content type : application/json;charset=UTF-8
### Path Varibales
| variable | description |
|--------------|------------------------------------------------------------------------------------|
| SITE_ID | SITE ID |
| SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
### API Data JSON Format
```json
{
"title": "title",
"file_path": "aaa.mp4",
"demo_contents": false,
"metadata": {
"{key}": "{value}"
}
}
```
### API Data Specification
| Key | type | required | description |
|:--------------|:--------|:---------|:-------------------------------------------------------------------------------|
| title | String | Y | Content title |
| file_path | String | Y | Download link for detection target video |
| demo_contents | Boolean | N | `DoveRunner demo contents` flag. default: false |
| metadata | Object | N | Optional key-value pairs (String to String) stored with the detection request. |
### Response Data JSON Format
```json
{
"error_code": "{error code}",
"error_message": "{error message}",
"detection_id": "detection id"
}
```
### Response Data Specification
|Key | type |description|
|:----| :-----| :----------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| detection_id | Number | ID for the detection request generated by DoveRunner system |
## Detection request registration API using URL (live)
This API is for requesting a watermark live detection using url.
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/live
* method : POST
* content type : application/json;charset=UTF-8
### Path Varibales
| variable | description |
|--------------|--------------------------------------------------------|
| SITE_ID | SITE ID |
| SERVICE_CODE | product code in detection service request. FWM - PD002 |
### API Data JSON Format
```json
{
"title": "title",
"file_path": "https://example.cdn.com/live/stream/playlist.m3u8",
"demo_contents": false,
"metadata": {
"{key}": "{value}"
}
}
```
### API Data Specification
| Key | type | required | description |
|:--------------|:--------|:---------|:-------------------------------------------------------------------------------|
| title | String | Y | Content title |
| file_path | String | Y | HLS (.m3u8) live stream manifest URL |
| demo_contents | Boolean | N | `DoveRunner demo contents` flag. default: false |
| metadata | Object | N | Optional key-value pairs (String to String) stored with the detection request. |
### Response Data JSON Format
```json
{
"error_code": "{error code}",
"error_message": "{error message}",
"detection_id": "detection id"
}
```
### Response Data Specification
| Key | type | description |
|:--------------|:-------|:------------------------------------------------------------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| detection_id | Number | ID for the detection request generated by DoveRunner system |
## Signed url issuance API for requesting detection by file upload
A detection request can also be requested by uploading a file directly.
This is an api that issues AWS S3 signed url for file upload.
When uploading a file to the issued url, a detection request is made.
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/token
* method : POST
* content type : application/json;charset=UTF-8
### Path Varibales
| variable | description |
|--------------|-----------------------------------------------------------------------------------|
| SITE_ID | SITE ID |
| SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
### API Data JSON Format
```json
{
"title": "title",
"file_extension": "mp4",
"demo_contents": false,
"metadata": {
"{key}": "{value}"
}
}
```
### API Data Specification
| Key | type | required | description |
|:---------------|:--------|:---------|:-------------------------------------------------------------------------------|
| title | String | Y | Content title |
| file_extension | String | Y | File extension (mp4, mkv, mov) |
| demo_contents | Boolean | N | `DoveRunner demo contents` flag. default: false |
| metadata | Object | N | Optional key-value pairs (String to String) stored with the detection request. |
### Response Data JSON Format
```json
{
"error_code": "error code",
"error_message": "error message",
"upload_url": "upload url"
}
```
### Response Data Specification
| Key | type | description |
|:--------------|:-------|:---------------------------------------------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| upload_url | String | Signed url that can be uploaded for 1 minute |
:::caution[Upload immediately]
`upload_url` expires **1 minute** after issuance. Start the file upload immediately after receiving the response — if you delay (e.g. queueing the upload, or issuing the URL well ahead of use), the upload will fail and you'll need to request a new signed URL.
:::
### File upload sample (curl)
```txt
curl -v --upload-file {filename.mp4} {signed upload url}
```
## Receiving Detection List
This API is for getting watermark detection list and each result.
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/list
* method : GET
* content type : application/json;charset=UTF-8
### Path Varibales
| variable | description |
|--------------|-----------------------------------------------------------------------------------|
| SITE_ID | SITE ID |
| SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
### API Data JSON Format
```json
{
"search_keyword": "{search keyword}",
"search_condition": "{search condition}",
"detect_status": "FD001",
"from": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
"to": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
"page_unit": "{long value}",
"page_index": "{long value}",
"time_zone": "{hh:mm}",
"site_id": "{site id}",
"req_types": ["url", "file", "stream"]
}
```
### API Data Specification
| Key | type |required| description |
|:-----------------| :-----| :------|:---------------------------------------------------------|
| search_keyword | String | N | Keyword for search condition |
| search_condition | String | N | Search condition (`title`, `detectionId`). default: `title` |
| detect_status | String | N | Detection status code (FD001 ~ FD005) |
| from | String | N | Creation time search condition |
| to | String | N | Creation time search condition |
| page_unit | Int | N | Number of search items. default : 25 |
| page_index | Int | N | Page index. default : 1 |
| time_zone | String | N | Time zone |
| site_id | String | N | Site id |
| req_types | Array | N | Search condition (type: url, file, stream) |
### Response Data JSON Format
```json
{
"error_code": "{error code}",
"error_message": "{error message}",
"total_count": "total count",
"time_zone": "{hh:mm}",
"data": [{
"detection_id" : "{detection id}",
"site_id" : "{site id}",
"title": "{title}",
"demo_contents": "{demo contents}",
"detect_status" : "{detect status}",
"file_id" : "{file id}",
"file_path": "{file path}",
"region_code": "{region code}",
"service_code": "{service code}",
"wm_key": "{wm key}",
"wm_data": "{wm data}",
"reg_date" : "{register date}",
"update_date": "{update date}"
}]
}
```
### Response Data Specification
| Key | type | description |
|:----------------------------|:-------|:-------------------------------------------------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error Message |
| total_count | String | total list count |
| time_zone | String | Time Zone |
| data.detection_id | Number | Detection ID |
| data.site_id | String | Site ID |
| data.title | String | Content title |
| data.demo_contents | String | `DoveRunner demo contents` flag |
| data.file_id | Number | Anti-Piracy: Takedown ID, FWM Service: Detection target file ID |
| data.file_path | String | file path |
| data.region_code | String | region code |
| data.service_code | String | product code(DWM-PD006, FWM-PD002) |
| data.wm_key | String | fwm -fwm key, dwm - dwmId |
| data.wm_data | String | fwm -fwm data, dwm - recipient |
| data.reg_date | String | registration date |
| data.update_date | String | update date |
## Receiving Detection Detail
This API is for getting watermark detection detail.
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/detail
* method : GET
* content type : application/json;charset=UTF-8
### Path Varibales
| variable | description |
|--------------|-----------------------------------------------------------------------------------|
| SITE_ID | SITE ID |
| SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
### API Data JSON Format
```json
{
"detection_id": "{detection id}",
"site_id": "{site id}"
}
```
### API Data Specification
| Key | type | required | description |
|:-------------|:-------|:---------|:-------------|
| detection id | Number | Y | detection ID |
| site_id | String | N | site ID |
### Response Data JSON Format
```json
{
"error_code": "{error code}",
"error_message": "{error message}",
"data": {
"detection_id" : "{detection id}",
"site_id" : "{site id}",
"title": "{title}",
"req_type": "{req_ ype}",
"demo_contents": "{demo contents}",
"detect_status" : "{detect status}",
"detect_progress_status": "{detect progress status}",
"file_path": "{file path}",
"file_id" : "{file id}",
"service_code": "{service code}",
"wm_key": "{wm key}",
"wm_data": "{wm data}",
"wm_seed_key": "{wm seed key}",
"error_code": "{error code}",
"error_message": "{error message}",
"reg_date" : "{register date}",
"update_date": "{update date}",
"sha256": "{sha256 hash}",
"metadata": {
"{key}": "{value}"
},
"detection_location": [
{
"frame_index": { "start": 12288, "end": 12671 },
"timestamp": { "start": "512000", "end": "527999" }
}
]
}
}
```
:::note[Absent fields]
Fields inside `data` that have no value are left out of the response rather than returned as `null`. `sha256`, `metadata` and `detection_location` in particular appear only once the detection has produced them, so treat a missing key as "not available yet" rather than coding against an explicit `null`.
:::
### Response Data Specification
| Key | type | description |
|:--------------------------------------------|:-------|:--------------------------------------------------------------------------------------------------------------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error Message |
| data.detection_id | Number | detection ID |
| data.site_id | String | Site ID |
| data.title | String | Content title |
| data.req_type | String | detection request type(url, file) |
| data.demo_contents | String | `DoveRunner demo contents` flag |
| data.detect_status | String | detection status code(FD001 ~ FD007) |
| data.detect_progress_status | String | detection progress status code(FD100 ~ FD700) |
| data.file_id | Number | Anti-Piracy: Takedown ID, FWM Service: Detection target file ID |
| data.file_path | String | file path |
| data.service_code | String | product code(DWM-PD006, FWM-PD002) |
| data.wm_key | String | fwm -fwm key, dwm - dwmId |
| data.wm_data | String | fwm -fwm data, dwm - recipient |
| data.wm_seed_key | String | only ADMIN |
| data.reg_date | String | registration date |
| data.update_date | String | update date |
| data.error_code | String | internal error code |
| data.error_message | String | initernal error description |
| data.sha256 | String | SHA-256 hash of the analysed video, in hexadecimal. |
| data.metadata | Object | The `metadata` sent with the detection request, returned as a key-value object in the order it was submitted. |
| data.detection_location | Array | Segments of the video in which the watermark was found. Absent when no segments were stored |
| data.detection_location[].frame_index.start | Number | First frame index of the segment |
| data.detection_location[].frame_index.end | Number | Last frame index of the segment |
| data.detection_location[].timestamp.start | String | Start of the segment, reported by the detector as a string |
| data.detection_location[].timestamp.end | String | End of the segment, reported by the detector as a string |
## Receiving Detection Status History
This API is for getting the status history of a detection request as a timeline.
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/history
* method : GET
* content type : application/json;charset=UTF-8
### Path Variables
| variable | description |
|----------|-------------|
| SITE_ID | SITE ID |
### Query Parameters
| Key | type | required | description |
|:-------------|:-------|:---------|:------------------------------------------------------|
| detection_id | Number | Y | Detection ID to look up, within the requested SITE_ID |
### Response Data JSON Format
```json
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"detection_id": 12345,
"histories": [
{ "detect_status": "FD001", "reg_date": "20260703090000" },
{ "detect_status": "FD002", "reg_date": "20260703090230" },
{ "detect_status": "FD003", "reg_date": "20260703091015" },
{ "detect_status": "FD004", "reg_date": "20260703094512" }
]
}
}
```
### Response Data Specification
| Key | type | description |
|:-------------------------------|:-------|:-------------------------------------------------------------------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error Message |
| data.detection_id | Number | Detection ID of the requested detection |
| data.histories | Array | Status history entries. Never empty in a success response |
| data.histories[].detect_status | String | detection status code(FD001 ~ FD007) |
| data.histories[].reg_date | String | Time the status was first recorded, UTC in `yyyyMMddHHmmss` format |
The entries of `data.histories` use the `detect_status` vocabulary listed in [Detection Status Codes](#detection-status-codes), not the `detect_progress_status` vocabulary.
### Error Codes
| Error Code | HTTP Status | Description |
|:-----------|:------------|:-----------------------------------------------------------------------------|
| A4041 | 404 | No status history exists for the requested detection. |
| A1000 | 402 | The `detection_id` value could not be read as a number |
| E9006 | 403 | The Site ID of the credential does not match the SITE_ID in the request path |
## Request Detection Stop
request detection stop API
* url : https://wm-detection.doverunner.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/stop
* method : PUT
* content type : application/json;charset=UTF-8
### Path Varibales
| variable | description |
|--------------|-----------------------------------------------------------------------------------|
| SITE_ID | SITE ID |
| SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
### API Data JSON Format
```json
{
"detection_id": "{detection id}"
}
```
### API Data Specification
| Key | type | required | description |
|:-------------|:-------|:---------|:-------------|
| detection id | Number | Y | detection ID |
### Response Data JSON Format
```json
{
"error_code": "{error code}",
"error_message": "{error message}",
"data": "{detection id}"
}
```
### Response Data Specification
| Key | type | description |
|:---------------------------|:-------|:------------------------------------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error Message |
| data | Number | Detection ID |
## Detection Status Notification API
Configure an AWS SNS topic so that DoveRunner can notify your service when a detection reaches a final state. One message is published per detection, whether it succeeded or failed, so you can automate follow-up actions such as revoking the sessions of a leaked watermark.
### Path Variables
All Detection Status Notification APIs use the following path variables:
| Variable | Description |
|----------|-------------|
| SITE_ID | Your DoveRunner Site ID (four alphanumeric characters) |
| NOTI_ID | Notification ID (used in detail, update, and delete operations) |
### Notification Message
When a detection reaches a final state, DoveRunner publishes the following JSON message to the registered SNS topic.
```json
{
"detection_id": 12345,
"detection_status": "FD004",
"forensic_mark": "0123456789abcdef",
"watermark_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"error_code": null,
"error_message": null
}
```
| Key | type | description |
|:-----------------|:-------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
| detection_id | Number | Detection ID the message refers to |
| detection_status | String | Final detection status code: `FD004` (completed), `FD006` (error) or `FD007` (failed). See [Detection Status Codes](#detection-status-codes) |
| forensic_mark | String | Extracted watermark payload. Present only when the detection completed successfully |
| watermark_token | String | Watermark token matching the extracted payload, for use with the session revocation flow. Present only when the detection completed successfully |
| error_code | String | Error code of the failure. Present only when the detection failed |
| error_message | String | Error message of the failure. Present only when the detection failed |
### Register Notification
Register the AWS SNS topic that detection status notifications are published to.
:::caution[One notification per site]
Only **one** SNS notification can be registered per site. Calling this API again for a site that already has a registration returns error `A4029`. To change the target, update or delete the existing notification (see [Update Notification](#update-notification) / [Delete Notification](#delete-notification) below) instead of registering a new one.
:::
* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]
* method : POST
* content type : application/json;charset=UTF-8
#### API Data JSON Format
```json
{
"noti_name": "my_revoke_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
"aws_access_key": "AKIAEXAMPLEKEY123",
"aws_secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
```
#### API Data Specification
| Key | type | required | description |
|:----| :-----| :------|:---------------------------------------------|
| noti_name | String | Y | Notification name |
| aws_arn | String | Y | AWS ARN |
| aws_access_key | String | Y | AWS access key |
| aws_secret_key | String | Y | AWS secret key |
#### Response Data JSON Format
```json
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1
}
}
```
#### Response Data Specification
| Key | type | description |
|:----| :-----| :----------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| data.noti_id | Number | Notification ID |
### Get Notification List
Retrieve all registered notification lists for the site.
* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]
* method : GET
* content type : application/json;charset=UTF-8
#### Response Data JSON Format
```json
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"total_count": 1,
"noti_list": {
"noti_id": 1,
"noti_name": "my_revoke_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
"reg_time": "2025-07-20T09:00:00",
"update_time": "2025-07-21T13:00:00"
}
}
}
```
#### Response Data Specification
| Key | type | description |
|:----| :-----| :----------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| data.total_count | Number | Number of notifications |
| data.noti_list.noti_id | Number | Notification ID |
| data.noti_list.noti_name | String | Notification name |
| data.noti_list.aws_arn | String | AWS ARN |
| data.noti_list.reg_time | String | Registration date (UTC) |
| data.noti_list.update_time | String | Update date (UTC) |
### Get Notification Detail
Retrieve details of a specific notification.
* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]/[NOTI_ID]
* method : GET
* content type : application/json;charset=UTF-8
#### Response Data JSON Format
```json
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1,
"noti_name": "my_revoke_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
"reg_time": "2025-07-20T09:00:00",
"update_time": "2025-07-21T13:00:00"
}
}
```
#### Response Data Specification
| Key | type | description |
|:----| :-----| :----------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| data.noti_id | Number | Notification ID |
| data.noti_name | String | Notification name |
| data.aws_arn | String | AWS ARN |
| data.reg_time | String | Registration date (UTC) |
| data.update_time | String | Update date (UTC) |
### Update Notification
Update an existing notification configuration.
* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]/[NOTI_ID]
* method : PUT
* content type : application/json;charset=UTF-8
#### API Data JSON Format
```json
{
"noti_name": "updated_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:updated-sns",
"aws_access_key": "AKIAEXAMPLEKEY456",
"aws_secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
```
#### API Data Specification
| Key | type | required | description |
|:----| :-----| :------|:---------------------------------------------|
| noti_name | String | N | Notification name |
| aws_arn | String | N | AWS ARN |
| aws_access_key | String | N | AWS access key |
| aws_secret_key | String | N | AWS secret key |
#### Response Data JSON Format
```json
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1
}
}
```
#### Response Data Specification
| Key | type | description |
|:----| :-----| :----------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| data.noti_id | Number | Notification ID |
### Delete Notification
Delete a registered notification.
* url : https://wm-detection.doverunner.com/api/v2/noti/detect/[SITE_ID]/[NOTI_ID]
* method : DELETE
* content type : application/json;charset=UTF-8
#### Response Data JSON Format
```json
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1
}
}
```
#### Response Data Specification
| Key | type | description |
|:----| :-----| :----------|
| error_code | String | `0000`: Success, Other codes: Error |
| error_message | String | Error message |
| data.noti_id | Number | Notification ID |
## Status and Error Codes
### Detection Status Codes
**`detect_status` - overall detection status**
| Status Code | Description |
| :--- | :-- |
| FD001 | Ready |
| FD002 | Downloading |
| FD003 | Detecting |
| FD004 | Completed |
| FD005 | Detection canceled |
| FD006 | Error |
| FD007 | Detection failed |
**`detect_progress_status` - detailed progress reported while a detection runs**
| Status Code | Description |
| :--- | :-- |
| FD100 | Detection requested |
| FD110 | Checking media information |
| FD120 | Creating the auto-detection pod |
| FD210 | Download started |
| FD220 | Download completed |
| FD311 | Auto-detection started |
| FD312 | Auto-detection completed |
| FD321 | Manual detection started |
| FD322 | Failed to start Auto-detection |
| FD400 | Completed (progress) |
| FD520 | Cancel completed |
| FD600 | Error (progress) |
| FD601 | Media information check failed |
| FD700 | Failed (progress) |
### Detection Error Codes
| **Error Code** | **Description** | **Cause** | **Solution** |
|:---------------|:---------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------|
| A1000 | Invalid request parameter or `pallycon-apidata` | A required field is missing or malformed, a path or query parameter has the wrong type, or the `pallycon-apidata` value could not be decoded or is missing `encData` / `hash`. | Follow the API guide and send the correct parameters. The error message names the offending field after the colon. |
| A1002 | Invalid timestamp | The `timestamp` in `pallycon-apidata` is missing, or is not in an accepted format. | Send the timestamp in `yyyy-MM-ddTHH:mm:ssZ` format. |
| A1006 | Site key decryption failed | The Site Key or Access Key could not be decrypted, or `encData` could not be decrypted with the Site Key. | Check and apply the correct Site Key and Access Key values from the DoveRunner Console site. |
| A1007 | Hash verification failed | The hash value of the API request data was generated incorrectly. | Apply the correct hash value by referring to the API guide document. |
| A1108 | Not Service Status | Service is not used. | Request to Service. |
| A4001 | Service code is not supported | The requested service code is not supported by this API. | Use a supported service code (FWM or DWM for VOD detection, FWM only for live detection). |
| A4002 | Failed to register the detection request | An internal server error occurred while saving the detection request. | 1. Check the parameters of the request data and retry.
2. Create a ticket on our Helpdesk to ask for support. |
| A4006 | Failed to update detect status | Internal server error. | Create a ticket on our Helpdesk to ask for support. |
| A4009 | Cannot find detection information | The requested detection could not be found, or the detection ID does not belong to this site. | Check the detection ID and site ID, then retry. If the same error occurs, create a ticket on our Helpdesk. |
| A4010 | Cannot find the watermark key | No watermark key matches the requested key value for this site. | Check the watermark key and site ID, then retry. |
| A4016 | Failed to get dwmId list | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
| A4017 | Failed to get max dwm Id | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
| A4018 | Failed to detection list count | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
| A4019 | Detection request limit reached | The detection request limit was reached. A trial account is capped at 2 detections in total, and that quota does not reset. A commercial account is limited to 50 detections in progress at the same time. | On a commercial plan, wait until detections in progress finish and request again. On a trial plan the cap is final — contact the Helpdesk to move to a commercial plan. |
| A4020 | Failed to get detection detail in update | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
| A4022 | Cannot find detection information while issuing a download URL | The detection for the requested download could not be found. | Check the detection ID and retry. |
| A4023 | Invalid file extension | File Extension(mp4, mpk, mov) is not supported. | Try to check the valid File extension(mp4, mkv, mov) |
| A4025 | Updating is not possible with past status values | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
| A4026 | Fail to access Video File from S3 | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
| A4027 | Fail to access Log Files from S3 | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
| A4029 | Session revocation notification duplicate registration | Only one notification can be registered per site | Delete existing notification before registering new one or modify existing |
| A4030 | Invalid AWS SNS ARN registration | Invalid AWS ARN format or not an SNS ARN | Verify AWS SNS ARN format (arn:aws:sns:region:account:topic) |
| A4032 | Notification not found | The specified notification does not exist for this site. | Verify the notification ID and site ID, then request again with the correct values. |
| A4033 | AWS SNS connection failure | DoveRunner could not connect to the AWS SNS topic with the supplied credentials. | Check the AWS credentials, region settings, and network connectivity. |
| A4034 | SNS notification registration failure | Internal server error during notification registration | Create a ticket on our Helpdesk to ask for support. |
| A4035 | SNS notification update failure | Internal server error during notification update | Create a ticket on our Helpdesk to ask for support. |
| A4036 | SNS notification deletion failure | Internal server error during notification deletion | Create a ticket on our Helpdesk to ask for support. |
| A4040 | Invalid metadata | `metadata` has more than 20 entries, a key longer than 128 characters, a value longer than 2048 characters, or a key or value containing control characters. | Keep `metadata` within 20 entries, keys within 128 characters and values within 2048 characters, and remove control characters. |
| A4041 | Detection status history not found | No status history exists for the requested detection. | Check the detection ID and site ID, then request again. |
| A7001 | No watermark found | Detection finished successfully, but no watermark was found in the content. | This is an informational result, not a failure. It is returned in `data.error_code` of the detection detail. |
| A9998 | Method not allowed | The HTTP method is not allowed for the requested endpoint. | Use the HTTP method described for that endpoint in this guide. |
| A9999 | Undefined internal error | An unexpected internal error occurred while handling the request. | Create a ticket on our Helpdesk to ask for support. |
| E9000 | Authorization header is missing | No usable credential was sent, neither an `Authorization` header nor a `pallycon-apidata` value, or the endpoint does not accept the authentication method that was used. | Send a Bearer token in the `Authorization` header, or send a `pallycon-apidata` payload on endpoints that accept AES authentication. |
| E9001 | Token value is invalid | The `Authorization` header is malformed, or it does not use the Bearer scheme. | Send the header exactly as `Authorization: Bearer TOKEN`. |
| E9002 | Token payload value is invalid | The token was read, but its payload failed verification or is missing a required claim. | Reissue the token from the DoveRunner Console and retry. |
| E9003 | Token is expired | The token expiry time has passed. | Issue a new token and retry. |
| E9006 | Insufficient permission for your Site ID | The account is not permitted to act on the requested Site ID, or the endpoint requires an administrator account. | Check the siteId in the request path, and use an administrator account for admin-only endpoints. |
| E9008 | Account information not available | The account resolved from the token has no API token registered. | Check the account setup in the DoveRunner Console, or contact the Helpdesk. |
| E9015 | Invalid parameter in the decrypted request body | The decrypted `pallycon-apidata` body is not valid JSON. | Make sure the JSON you encrypt into `pallycon-apidata` is well formed. |
| E9996 | Authentication server unreachable | The account lookup service is temporarily unavailable. | Retry after a short wait. If the error persists, create a ticket on our Helpdesk. |
| E9997 | Failed to parse the server response | An unexpected error occurred while processing an internal server response. | Create a ticket on our Helpdesk to ask for support. |
| E9999 | Undefined internal error during account lookup | An unexpected error occurred while resolving the account for the request. | Create a ticket on our Helpdesk to ask for support. |
### Error Codes for Detection Failure
|Error Code|Descriptions|
| :--- | :--- |
|D000|Etc (undefined detection failure error)|
|D002|The length of the video is less than 5 minutes. |
| D003 | Video codec is not supported for detection. Supported codecs are H.264 (AVC), H.265 (HEVC), and Apple ProRes. |
|D004|The resolution is below 480P. |
|D005|Bitrate is less than 1 Mbps. |
|D010|The Extension should be in [.mp4, .mkv, .mov] |
|D011|Failed to get the media specification. |
| D017 | Video duration is too short for DWM detection. Minimum duration required is 30 seconds. |
| D018 | Detection request limit exceeded. Please check the maximum allowed number of detections. |
| D019 | Invalid stream URL extension: only .m3u8 files are supported for live detection. |
| D020 | Invalid stream URL format. Please provide a valid URI for live detection. |
| D021 | Invalid stream URL. Unable to retrieve the playlist (stream information) from the provided address. |
| D022 | Failed to retrieve a valid stream path from the master playlist. Ensure the playlist contains a .m3u8 stream reference. |
| D023 | DRM protected stream detected (SAMPLE-AES). Live detection cannot proceed on encrypted streams. |