Transcoding & Packaging API Guide

This document guides how to use DoveRunner Transcoding & Packaging (T&P) service through HTTP API.

Tutorial Video and Sample Codes

You can integrate T&P service with the following video tutorials and API sample code.

Language	GitHub repository
TypeScript	https://github.com/doverunner/tnp-request-sample-typescript
Python	https://github.com/doverunner/tnp-request-sample-python
Java	https://github.com/doverunner/tnp-request-sample-java

Common Specifications

The specifications below are common to all T&P APIs described in this document.

Authentication Token

When calling the T&P API, you need to set an authentication token issued by the process below.

Step 1: Generate the base64 encoded Authorization parameter

1. Navigate to Base64 Enc/Dec page on DoveRunner DevConsole.
2. While Encrypt option is selected, enter the EmailID: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 email address 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://tnp.pallycon.com/api/token/{siteId}
• 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/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: tnp.pallycon.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

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 T&P 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

Region Codes

Some of T&P APIs use region codes as below in the request and response data.

Region Code	Region Name	AWS Region Code
RG004	Oregon	us-west-2
RG011	Seoul	ap-northeast-2
RG013	Singapore	ap-southeast-1

TNP Integration Setting API

Get Integration Setting

API to get TNP Integration Setting.

• URL: https://tnp.pallycon.com/api/setting/{siteId}
• Method: GET

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID

Sample Request

GET /api/setting/DEMO HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.api.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	TNP Integration Information
data.site_id	String	Site ID
data.region	String	Region Code to proceed with TNP packaging
data.service_status	String	TNP Service Status (SE000:In Service, SE001: No Service)
data.trial_pack_cnt	Number	On Trial, number of packaging jobs
data.site_key	String	Encryption key required for service site integration (check the DoveRunner Console’s ‘Site Settings’ page)
data.access_key	String	Encryption key used for additional integration such as packager, license token, etc. (check the DoveRunner Console’s ‘Site Settings’ page)

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 230

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "site_id" : "DEMO",
    "region" : "RG011",
    "service_status" : "SE000",
    "trial_pack_cnt" : 0,
    "site_key" : null,
    "access_key" : null
  }
}

Update Integration Setting

API to update TNP Integration Setting.

• URL: https://tnp.pallycon.com/api/setting/{siteId}
• Method: PUT

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID

요청 데이터 필드

필드	유형	설명
siteId	Your DoveRunner Site ID
region	String	Region Code to proceed with TNP packaging

Sample Request

PUT /api/setting/DEMO HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 76
Host: tnp.api.com

{
  "site_id" : "DEMO",
  "region" : "RG004"
}

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	TNP Integration Information
data.site_id	String	Site ID
data.region	String	Region Code to proceed with TNP packaging

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 156

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "site_id" : "DEMO",
    "region" : "RG004"
  }
}

Job API

Create Job

The API used to create the Transcoding and Packaging Job

• URL: https://tnp.pallycon.com/api/job/{siteId}
• Method: POST

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID (four alphanumeric characters)

Request Fields

Field	Type	Required	Description
job_name	String	Yes	Job name
content_id	String	Yes	Content id
input	Object	Yes	Input content information
input.storage_id	String	Yes	Input storage id
input.files	Array	Yes	Input files information.
input.files.[].file_type	String	Yes	file type : multi, video, audio - multi : Use the video and audio track of the input file. Audio track information must be included. - video: Use the video track of the input file. Audio track information is not used. multi and video cannot be used together in the same job. - audio: Use the audio track of the input file. Audio track information must be included.
input.files.[].file_path	String	Yes	input file path
input.files.[].audios	Array		audio information(Required in case of multi or audio file_type)
input.files.[].audios.[].in	Object	Yes	input audio track
input.files.[].audios.[].in.track	Number		input audio track index. default: 0
input.files.[].audios.[].remap	Object	Yes	remapped audio track
input.files.[].audios.[].remap.track	Number		remapped audio track index. default: 0
input.subtitles	Array		Subtitle
input.subtitles.[].file_path	String	Yes	subtitle file path
input.subtitles.[].language	String	Yes	subtitle language
output	Object	Yes	Output task information
output.storage_id	String	Yes	Output storage id
output.path	String	Yes	Output folder path
output.default_language	String		Default language code of audio track
output.transcodings	Array	Yes	Transcoding
output.transcodings.[].track_id	String	Yes	track id
output.transcodings.[].track_type	String	Yes	track type : video, audio
output.transcodings.[].track_name	String		track name : audio
output.transcodings.[].codec	String	Yes	video/audio codec name (video: h264, h265. audio: aac, aac_lc,ac3,eac3 & heaac_v2) In case of audio codec, the name should be as same as the source file has.
output.transcodings.[].height	Number	Yes	Height of video
output.transcodings.[].width	Number	Yes	Width of video
output.transcodings.[].bitrate_mode	String		Bitrate mode (cbr, vbr)
output.transcodings.[].bitrate	Number	Yes	Bitrate (CBR)(bps).
output.transcodings.[].min_bitrate	Number		Minimum bitrate (bps). for vbr.
output.transcodings.[].max_bitrate	Number		Maximum bitrate (bps). for vbr.
output.transcodings.[].crf	Number		Set bitrate based on quality. Only available if VBR. Range : 0~63
output.transcodings.[].bandwidth	Number		bandwidth of video
output.transcodings.[].sample_rate	Number		Sample rate of audio
output.transcodings.[].language	String		Language code(ISO 639-1, lowercase two-letter) of audio track
output.transcodings.[].sources	Array		List of remapped audio tracks to use.
output.transcodings.[].sources.[].track	Number		remapped audio track index to use.
output.packaging	Object	Yes	Packaging
output.packaging.dash	Boolean		output dash. Either dash or hls or cmaf is required. If you set this streaming format, the cmaf must have a false value.
output.packaging.hls	Boolean		output hls. Either dash or hls is cmaf is required. If you set this streaming format, the cmaf must have a false value.
output.packaging.cmaf	Boolean		output cmaf. Other streaming formats (dash,hls) or cmaf are required.
output.packaging.option	Object		packaging option
output.packaging.option.min_buffer_time	Number		Specifies, in seconds, a common duration used in the definition of the MPD Representation data rate. Minimum: 2
output.packaging.option.enable_average_bandwidth_mpd	Boolean		Use average bandwidth for each track in MPD. (default: false)
output.packaging.option.mp4_subtitle	Boolean		Deprecated the output subtitle format can be set to Embedded MP4 with this parameter. If the parameter is omitted, the subtitle in Text VTT format is created by default. (default: false)
output.packaging.option.subtitle_format.dash	String		Able to set subtitle format with option name(text_vtt, mp4_ttml, mp4_vtt). Only available when output DASH type is requested. (default: text_vtt)
output.packaging.option.subtitle_format.hls	String		Able to set subtitle format with option name(text_vtt, mp4_ttml, mp4_vtt). Only available when output HLS type is requested. (default: text_vtt)
output.packaging.option.subtitle_format.cmaf	String		Able to set subtitle format with option name(text_vtt, mp4_ttml). Only available when output CMAF type is requested. (default: text_vtt)
output.drm	Object		Drm
output.drm.enabled	Boolean		Drm enable flag. default: false
output.drm.option	Object		Drm option
output.drm.option.multi_key	Boolean		Enables multi-key packaging. default: false
output.drm.option.max_sd_height	Number		Max resolution to be packaged as SD track. default: 480
output.drm.option.max_hd_height	Number		Max resolution to be packaged as HD track. default: 1080
output.drm.option.max_uhd1_height	Number		Max resolution to be packaged as UHD track. default: 2160
output.drm.option.skip_audio_encryption	Boolean		Disable audio track encryption. default: false(encrypt audio)
output.drm.option.clear_lead	Number		Unencrypted section at the beginning (by second). default: 0
output.drm.option.generate_tracktype_manifests	Boolean		Create multiple manifest (playlist) files for multi-key packaging. For adaptive streams containing SD to UHD tracks, three manifests are created: SD_ONLY, SD_HD, and SD_UHD. default: false
output.forensic_watermarking	Object		Forensic watermarking
output.forensic_watermarking.enabled	Boolean		Forensic watermarking enable flag. default: false
output.job_noti_id	String		Use the notification ID which has been configured already (Refer to SNS Creation) for TNP Job status update.
output.scale_option_type	String		scale option type(none, fit, fit_with_padding, fill_with_crop, stretch, stretch_with_par)

Sample Request

POST /api/job/DEMO HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 1541
Host: tnp.pallycon.com

{
  "job_name" : "jobName",
  "content_id" : "test-cid",
  "input" : {
    "storage_id" : "input-storage-id",
    "files" : [ {
      "file_type" : "multi",
      "file_path" : "input/input-file1.mp4",
      "audios" : [ {
        "in" : {
          "track" : 0
        },
        "remap" : {
          "track" : 0
        }
      } ]
    } ],
    "subtitles" : [ {
      "file_path" : "input/subtitle/en.vtt",
      "language" : "eng"
    } ]
  },
  "output" : {
    "storage_id" : "output-storage-id",
    "path" : "output",
    "transcodings" : [ {
      "track_id" : "video1",
      "track_type" : "video",
      "codec" : "h264",
      "height" : 1080,
      "width" : 1920,
      "bitrate_mode" : "cbr",
      "bitrate" : 10000,
      "frame_rate" : 23.98
    }, {
      "track_id" : "audio1",
      "track_type" : "audio",
      "track_name" : "english",
      "codec" : "h264",
      "bitrate_mode" : "cbr",
      "bitrate" : 128000,
      "language" : "en",
      "sources" : [
        {
          "track": 0
        }
      ]
    } ],
    "packaging" : {
      "dash" : true,
      "hls" : false,
      "cmaf" : false,
      "option" : {
        "min_buffer_time" : 2,
        "enable_average_bandwidth_mpd" : false,
        "subtitle_format": {
          "dash": "text_vtt"
        }
      }
    },
    "drm" : {
      "enabled" : true,
      "option" : {
        "multi_key" : false,
        "max_sd_height" : 0,
        "max_hd_height" : 0,
        "max_uhd1_height" : 0,
        "skip_audio_encryption" : false,
        "clear_lead" : 0,
        "generate_tracktype_manifests" : false
      }
    },
    "forensic_watermarking" : {
      "enabled" : true
    },
    "job_noti_id":1,
    "scale_option_type":"fit_with_padding"
  }
}

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data.job_id	Number	created job id

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 96

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "job_id" : 123
  }
}

Search Job List

Use this API to search the Job List

• URL: https://tnp.pallycon.com/api/job/{siteId}
• Method: GET

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID

Request Parameters

Parameter	Type	Description
from	String	Search parameter for job registration time. (YYYY-MM-DD)
to	String	Search parameter for job registration time. (YYYY-MM-DD)
job_name	String	Search job name.
region	String	Search region code.
page_unit	Number	Number of max result per page. default : 25, max: 1000.
page_index	Number	Index of result page. default : 1
job_id	Number	Search job id.
job_id_operator	String	Search Operator of job id. (eq, gt, goe, lt, loe)
content_id	String	Search content id.
streaming_format	Array	Search streaming format : dash / hls / cmaf / dash,hls
job_status	Array	Search job status by list.
job_type	Array	Search job type by list. drm / forensic_watermark / drm,forensic_watermark
codec	String	Search transcoding video codec. : h264 / h265 / h264,h2655
time_zone	String	Search timezone. default : +00:00

Sample Request

GET /api/job/DEMO?from=2022-05-01&to=2022-05-13&job_name=test-job&region=RG011&page_unit=20&page_index=1&job_id=123&content_id=test-content-id&security=forensic_watermark&streaming_format=dash&time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
total_count	Number	total count
data	Array	Job list
data.[].job_id	Number	Job ID
data.[].job_name	String	Job name
data.[].content_id	String	Content id
data.[].job_status	String	Job status code
data.[].drm	Boolean	Use DRM
data.[].forensic_watermark	Boolean	Use Forensic watermark
data.[].dash	Boolean	Packaging Dash
data.[].hls	Boolean	packaging Hls
data.[].cmaf	Boolean	packaging CMAF
data.[].region	String	Job registration region
data.[].reg_time	String	Job registration time.
data.[].start_time	String	Start time for the job
data.[].update_time	String	Last update time for the job

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 933

{
    "error_code" : "0000",
    "error_message" : "Success.",
    "time_zone" : "+00:00",
    "total_count" : 3,
    "data" : [ {
    "job_id" : 1,
    "job_name" : "test job 1",
    "content_id" : "test cid 1",
    "job_status" : "TP100200",
    "drm" : true,
    "forensic_watermark" : true,
    "dash" : true,
    "hls" : true,
    "cmaf": false,
    "codec": "h264"
    "region" : "RG011",
    "reg_time" : "2022-05-20T00:00:00"
    }, {
    "job_id" : 2,
    "job_name" : "test job 2",
    "content_id" : "test cid 2",
    "job_status" : "TP500",
    "drm" : true,
    "forensic_watermark" : false,
    "dash" : true,
    "hls" : false,
    "cmaf": false,
    "codec": "h265"
    "region" : "RG011",
    "reg_time" : "2022-05-20T00:00:00"
    }, {
    "job_id" : 3,
    "job_name" : "test job 3",
    "content_id" : "test cid 3",
    "job_status" : "TP700200",
    "drm" : true,
    "forensic_watermark" : true,
    "dash" : true,
    "hls" : true,
    "cmaf": false,
    "codec": "h264"
    "region" : "RG011",
    "reg_time" : "2022-05-20T00:00:00"
    }  ]
}

Get Job Detail

This API is used to Get the Job details

• URL: https://tnp.pallycon.com/api/job/{siteId}/{jobId}
• Method: GET

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
jobId	Job ID

Request Parameters

Parameter	Required	Description
time_zone	Yes	Search timezone. default: +00:00

Sample Request

GET /api/job/DEMO/1?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
time_zone	String	Timezone
data	Object	Job Information
data.job_id	Number	Job Id
data.job_name	String	Job name
data.job_status	String	Job status code
data.region	String	Region code
data.content_id	String	Content id
data.input	Object	Input content information
data.input.storage_id	String	Input storage id
data.input.files	Array	Input files information.
data.input.files.[].file_type	String	file type : multi, video, audio - multi : Use the video and audio track of the input file. Audio track information must be included. - video: Use the audio track of the input file. Audio track information is not used. Multi and video cannot be used together in the same job. - audio: Use the audio track of the input file. Audio track information must be included.
data.input.files.[].file_path	String	input file path
data.input.files.[].audios	Array	audio information
data.input.files.[].audios.[].in.track	Number	input audio track index
data.input.files.[].audios.[].remap.track	Number	remapped audio track index
data.input.subtitles	Array	Subtitle
data.input.subtitles.[].file_path	String	subtitle file path
data.input.subtitles.[].language	String	subtitle language
data.output	Object	Output task information
data.output.storage_id	String	Output storage id
data.output.path	String	Output folder path
data.output.default_language	String	Default language code of audio track
data.output.transcodings	Array	Transcoding
data.output.transcodings.[].track_id	String	track id
data.output.transcodings.[].track_type	String	track type : video, audio
data.output.transcodings.[].track_name	String	track name : audio
data.output.transcodings.[].codec	String	video/audio codec name (video: h264, h265. audio: aac, aac_lc,ac3,eac3 & heaac_v2)
data.output.transcodings.[].height	Number	Height of video
data.output.transcodings.[].width	Number	Width of video
data.output.transcodings.[].bitrate_mode	String	Bitrate mode (cbr, vbr)
data.output.transcodings.[].bitrate	Number	Bitrate (bps).
data.output.transcodings.[].min_bitrate	Number	Minimum bitrate (bps). for vbr.
data.output.transcodings.[].max_bitrate	Number	Maximum bitrate (bps). for vbr.
data.output.transcodings.[].frame_rate	Number	Frame rate of video
data.output.transcodings.[].crf	Number	Bitrate based on quality. Only available if VBR. Range : 0~63
data.output.transcodings.[].bandwidth	Number	bandwidth of video
data.output.transcodings.[].sample_rate	Number	Sample rate of audio
data.output.transcodings.[].language	String	Language code(ISO 639-1, lowercase two-letter) of audio track
data.output.transcodings.[].sources	Array	List of remapped audio tracks to use.
data.output.transcodings.[].sources.[].track	Number	remapped audio track index to use.
data.output.packaging	Object	Packaging
data.output.packaging.dash	Boolean	output dash. Either dash or hls or cmaf is required. If you set this streaming format, the cmaf must have a false value.
data.output.packaging.hls	Boolean	output hls. Either dash or hls or cmaf is required. If you set this streaming format, the cmaf must have a false value.
data.output.packaging.cmaf	Boolean	output cmaf. Other streaming formats (dash,hls) or cmaf are required.
data.output.packaging.option	Object	packaging option
data.output.packaging.option.min_buffer_time	Number	Specifies, in seconds, a common duration used in the definition of the MPD Representation data rate. Minimum: 2
data.output.packaging.option.enable_average_bandwidth_mpd	Boolean	Use average bandwidth for each track in MPD. (default: false)
output.packaging.option.mp4_subtitle	Boolean	Deprecated the output subtitle format can be set to Embedded MP4 with this parameter. If the parameter is omitted, the subtitle in Text VTT format is created by default. (default: false)
output.packaging.option.subtitle_format.dash	String	Able to set subtitle format with option name(text_vtt, mp4_ttml, mp4_vtt). Only available when output DASH type is requested. (default: text_vtt)
output.packaging.option.subtitle_format.hls	String	Able to set subtitle format with option name(text_vtt, mp4_ttml, mp4_vtt). Only available when output HLS type is requested. (default: text_vtt)
output.packaging.option.subtitle_format.cmaf	String	Able to set subtitle format with option name(text_vtt, mp4_ttml). Only available when output CMAF type is requested. (default: text_vtt)
data.output.drm	Object	Drm
data.output.drm.enabled	Boolean	Drm enable flag. default: false
data.output.drm.option	Object	Drm option
data.output.drm.option.multi_key	Boolean	Enables multi-key packaging. default: false
data.output.drm.option.max_sd_height	Number	Max resolution to be packaged as SD track. default: 480
data.output.drm.option.max_hd_height	Number	Max resolution to be packaged as HD track. default: 1080
data.output.drm.option.max_uhd1_height	Number	Max resolution to be packaged as UHD track. default: 2160
data.output.drm.option.skip_audio_encryption	Boolean	Disable audio track encryption. default: false(encrypt audio)
data.output.drm.option.clear_lead	Number	Unencrypted section at the beginning (by second). default: 0
data.output.drm.option.generate_tracktype_manifests	Boolean	Create multiple manifest (playlist) files for multi-key packaging. For adaptive streams containing SD to UHD tracks, three manifests are created: SD_ONLY, SD_HD, and SD_UHD. default: false
data.output.forensic_watermarking	Object	Forensic watermarking
data.output.forensic_watermarking.enabled	Boolean	Forensic watermarking enable flag. default: false
data.output.job_noti_id	String	The notification ID set for the TNP Job.
data.reg_time	String	Job registration time
data.start_time	String	Job start time
data.update_time	String	Last update time for the job

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1542

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
    "job_name" : "jobName",
    "content_id" : "test-cid",
    "input" : {
      "storage_id" : "12312312312312312312312312312312",
      "files" : [ {
        "file_type" : "multi",
        "file_path" : "del-short-hevc.mp4",
        "audios" : [ {
          "in" : {
            "track" : 0
          },
          "remap" : {
            "track" : 0
          }
        } ]
      } ]
    },
    "output" : {
      "storage_id" : "32132132132132132132131231232132",
      "path" : "saas-pack",
      "transcodings" : [ {
        "track_id" : "video1",
        "track_type" : "video",
        "codec" : "H265",
        "height" : 1080,
        "width" : 1920,
        "bitrate" : 2500,
        "frame_rate" : 23.98
      }, {
        "track_id" : "video2",
        "track_type" : "video",
        "codec" : "H264",
        "height" : 720,
        "width" : 1080,
        "bitrate" : 1500,
        "frame_rate" : 23.98
      }, {
        "track_id" : "audio1",
        "track_type" : "audio",
        "codec" : "aac",
        "sources" : [ {
          "track" : 0
        } ]
      } ],
      "packaging" : {
        "dash" : true,
        "hls" : true,
        "cmaf" : false
      },
      "drm" : {
        "enabled" : true
      },
      "forensic_watermarking" : {
        "enabled" : true
      }
      "job_noti_id":1
    },
    "job_id" : 1,
    "region" : "RG011",
    "job_status" : "TP100100",
    "start_time" : "2022-05-20T17:03:41",
    "reg_time" : "2022-05-20T17:02:17"
  }
}

Job Stop

The below API is used to stop the T&P job

• URL: https://tnp.pallycon.com/api/job/{siteId}/{jobId}/stop
• Method: PUT

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
jobId	Job ID

Sample Request

PUT /api/job/DEMO/1/stop HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Job Information
data.job_id	Number	Job Id

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 94

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "job_id" : 1
  }
}

Job Restart

API to restart the job.

• URL: https://tnp.pallycon.com/api/job/{siteId}/{jobId}/restart
• Method: PUT

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
jobId	Job ID

Sample Request

PUT /api/job/DEMO/1/restart HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Job Information
data.job_id	Number	Job Id

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 94

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "job_id" : 1
  }
}

Storage API

Create Storage

API to create the storage ID

• URL: https://tnp.pallycon.com/api/storage/{siteId}
• Method: POST

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID

Request Fields

Field	Type	Required	Description
storage_name	String	Yes	Name of the storage
aws_bucket	String	Yes	Name of S3 bucket
io_type	String	Yes	Storage input/output type
access_key_id	String	Yes	S3 access key id
secret_key	String	Yes	S3 secret key
region	String	Yes	Region code
description	String		Storage description

Sample Request

POST /api/storage/DEMO HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 295
Host: tnp.pallycon.com

{
  "storage_name" : "test-input-storage",
  "aws_bucket" : "watermark-input-seoul",
  "io_type" : "input",
  "access_key_id" : "valid-test-storage-access-key-id",
  "secret_key" : "valid-in-test-storage-secret-key",
  "region" : "RG011",
  "description" : "This storage is test input bucket."
}

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data.storage_id	String	created storage id

Sample Response

| HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 115

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "storage_id" : "input-storage-id"
  }
}

Search Storage List

API to search in the Storage List

• URL: https://tnp.pallycon.com/api/storage/{siteId}
• Method: GET

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID

Request Parameters

Parameter	Description
from	Search parameter for storage registration time. (YYYY-MM-DD)
to	Search parameter for storage registration time. (YYYY-MM-DD)
storage_name	Search storage name.
region	Search storage region code.
page_unit	Number of max result per page. default : 25, max: 1000.
page_index	Index of result page. default : 1
time_zone	Search timezone. default: +00:00

Sample Request

GET /api/storage/DEMO?from=2022-05-01&to=2022-05-13&storage_name=test-storage&region=RG011&page_unit=20&page_index=1&time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
data	Array	Storage list
data.[].storage_id	String	Storage id
data.[].storage_name	String	Storage name
data.[].aws_bucket	String	Bucket name
data.[].io_type	String	input / output
data.[].region	String	Storage region
data.[].reg_time	String	Storage registration time YYYY-MM-DD’T’hh-mm-ss
data.[].update_time	String	Last update time YYYY-MM-DD’T’hh-mm-ss

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 775

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : [ {
    "storage_id" : "e42e5fc74bee455db0fc2d79038dbabb",
    "storage_name" : "test storage 1",
    "aws_bucket" : "test bucket 1",
    "io_type" : "input",
    "region" : "RG011",
    "reg_time" : "2022-05-20T00:00:00"
  }, {
    "storage_id" : "50273cb8e91242f3ad6b9dd49faf8f03",
    "storage_name" : "test storage 2",
    "aws_bucket" : "test bucket 2",
    "io_type" : "input",
    "region" : "RG011",
    "reg_time" : "2022-05-20T00:00:00"
  }, {
    "storage_id" : "69798b703f3c46b996a1335a54c3fa0e",
    "storage_name" : "test storage 3",
    "aws_bucket" : "test bucket 3",
    "io_type" : "input",
    "region" : "RG011",
    "reg_time" : "2022-05-20T00:00:00"
  } ]
}

Get Storage Detail

API to get the storage details

• URL: https://tnp.pallycon.com/api/storage/{siteId}/{storageId}
• Method: GET

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
storageId	Storage id

Request Parameters

Parameter	Description
time_zone	Search timezone. default: +00:00

Sample Request

GET /api/storage/DEMO/12312312312312312312312312312312?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
time_zone	String	Timezone
data	Object	Storage Information
data.storage_id	String	Storage Id
data.storage_name	String	Storage name
data.io_type	String	Storage input/output type
data.aws_bucket	String	Bucket name
data.region	String	Region code
data.access_key_id	String	Storage access key id
data.secret_key	String	storage secret key
data.description	String	Storage Description
data.reg_time	String	Storage registration time (YYYY-MM-DD’T’hh-mm-ss)
data.update_time	String	Last update time

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 547

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
    "storage_id" : "12312312312312312312312312312312",
    "storage_name" : "test-input-storage",
    "io_type" : "input",
    "aws_bucket" : "watermark-input-seoul",
    "region" : "RG011",
    "access_key_id" : "valid-test-storage-access-key-id",
    "secret_key" : "valid-in-test-storage-secret-key",
    "description" : "This storage is test input bucket.",
    "update_time" : "2022-05-26T05:43:01",
    "reg_time" : "2022-05-25T05:43:01"
  }
}

Update Storage

API to update the storage details

• URL: https://tnp.pallycon.com/api/storage/{siteId}/{storageId}
• Method: PUT

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
storageId	Storage id

Request Fields

Field	Type	Description
storage_name	String	Storage name
access_key_id	String	S3 access key id
secret_key	String	S3 secret key
aws_bucket	String	S3 bucket name
io_type	String	input / output
description	String	Storage description

Sample Request

PUT /api/storage/DEMO/12312312312312312312312312312312 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 217
Host: tnp.pallycon.com

{
  "storage_name" : "test-input-storage",
  "aws_bucket" : "watermark-input-seoul",
  "io_type" : "input",
  "access_key_id" : "valid-test-storage-access-key-id",
  "secret_key" : "valid-in-test-storage-secret-key"
}

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Storage Information
data.storage_id	String	Storage Id

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 131

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "storage_id" : "12312312312312312312312312312312"
  }
}

Delete Storage ID

API to delete storage ID

• URL: https://tnp.pallycon.com/api/storage/{siteId}/{storageId}
• Method: DELETE

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
storageId	Storage ID

Sample Request

DELETE /api/storage/DEMO/12312312312312312312312312312312 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Storage Information
data.storage_id	String	Storage Id

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 131

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "storage_id" : "12312312312312312312312312312312"
  }
}

Delete Multiple Storages

API to delete multiple storage IDs at once.

• URL: https://tnp.pallycon.com/api/storage/{siteId}
• Method: DELETE

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
storage_ids	Array

Sample Request

DELETE /api/storage/DEMO HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 118
Host: tnp.pallycon.com

{
  "site_id" : "DEMO",
  "storage_ids" : [ "12312312312312312312312312312312", "12312312312312312312312312312313" ]
}

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Storage Information
data.site_id	String	Site id
data.storage_ids	Array	Storage Id list

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 196

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "site_id" : "DEMO",
    "storage_ids" : [ "12312312312312312312312312312312", "12312312312312312312312312312313" ]
  }
}

Job Notification API

TNP API supports AWS SNS (Simple Notification Service) to get updates on the TNP Job status. Currently the following 4 APIs are supported:

1. AWS SNS Job Notification creation
2. Notification Update
3. Notification Search
4. Notification Delete

SNS Creation

API to create Job notification

• URL: https://tnp.pallycon.com/api/noti/job/{SiteID}
• Method: POST

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID

Request Fields

Field	Type	Required	Description
noti_name	String	Yes	SNS notification name (maximum 50 characters English case, numbers, special characters (-)(_)(.)) supported
noti_type	String	Yes	Notification type to be mentioned, at present only SNS is supported
url_end_point	String	Yes	URL address to receive notifications (currently only AWS ARN type addresses are supported)
aws_access.access_key	String	Yes	Please mention your aws sns access key
aws_access.secret_key	String	Yes	Please mention your aws sns secret key
alarm_status	Object	Yes	Type of alarm notification status to be set
alarm_status.queued	Boolean		If set to true, whenever job is queued, notification would be sent (default: false)
alarm_status.progressing	Boolean		If set to true, whenever job enters progress from queued state, notification would be sent (default: false)
alarm_status.complete	Boolean		If set to true, whenever job is completed, notification would be sent (default: false)
alarm_status.error	Boolean		If set to true, whenever job encounters an error, notification would be sent (default: false)
alarm_status.stopped	Boolean		If set to true, whenever job is stopped, notification would be sent (default: false)

Sample Request

POST https://tnp.pallycon.com/api/noti/job/{SiteID}
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8

Host: tnp.pallycon.com

{
   "noti_name" :"noti_test",
   "noti_type" : "SNS",
   "url_end_point" : "arn:aws:sns:us-west-2:73041xxxxx:PallyCon_TNP_SNS",
  "aws_access" :
   {
       "access_key" : "AK1252GDTP5xxxxx",
       "secret_key" : "WwMma1EVkcMBhlCmXxxxxxxx1"
   },
  "alarm_status" :
   {
       "queued" : false,
       "progressing" : false,
       "stopped" : true,
       "error" : true,
       "complete" : true
   }
}

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Job Notification information
data.noti_id	Number	Notification ID

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "error_code": "0000",
   "error_message": "Success.",
   "data": {
       "noti_id": 1
   }
}

SNS Update

API to modify/update already created notification

• URL: https://tnp.pallycon.com/api/noti/job/{{SitID}}/{{notiid}}
• Method: PUT

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
notiid	Notification ID to be updated

Request Fields

Field	Type	Required	Description
noti_name	String		SNS notification name (maximum 50 characters English case, numbers, special characters (-)(_)(.)) supported
noti_type	String		Notification type to be mentioned, at present only SNS is supported
url_end_point	String		URL address to receive notifications (currently only AWS ARN type addresses are supported)
aws_access.access_key	String		Please mention your aws sns access key
aws_access.secret_key	String		Please mention your aws sns secret key
alarm_status	Object		Type of alarm notification status to be set
alarm_status.queued	Boolean	Yes	If set to true, whenever job is queued, notification would be sent (default: false)
alarm_status.progressing	Boolean	Yes	If set to true, whenever job enters progress from queued state, notification would be sent (default: false)
alarm_status.complete	Boolean	Yes	If set to true, whenever job is completed, notification would be sent (default: false)
alarm_status.error	Boolean	Yes	If set to true, whenever job encounters an error, notification would be sent (default: false)
alarm_status.stopped	Boolean	Yes	If set to true, whenever job is stopped, notification would be sent (default: false)

Sample Request

PUT https://tnp.pallycon.com/api/noti/job/{{SitID}}/{{notiid}}
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8

Host: tnp.pallycon.com

{
   "noti_name" :"noti_test",
   "noti_type" : "SNS",
   "url_end_point" : "arn:aws:sns:us-west-2:73041xxx:PallyCon_TNP_SNS",
  "aws_access" :
   {
       "access_key" : "AK1252GDTP5xxxxx",
       "secret_key" : "WwMma1EVkcMBhlCmXxxxxxxx1"
   },
  "alarm_status" :
   {
       "queued" : false,
       "progressing" : false,
       "stopped" : true,
       "error" : true,
       "complete" : true
   }
}

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Job Notification information
data.noti_id	Number	Notification ID

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "error_code": "0000",
   "error_message": "Success.",
   "data": {
       "noti_id": 1
   }
}

SNS Search

API to search Job notifications

• URL: https://tnp.pallycon.com/api/noti/job/{SiteID}
• Method: GET

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID

Sample Request

GET https://tnp.pallycon.com/api/noti/job/{SiteID}
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
time_zone	String	Timezone
total_count	Number	Total Count
data	Array	Job Notification List

The Data Array details are as follows:

Field	Type	Description
noti_id	Number	Notification ID
site_id	String	Site ID
noti_name	String	SNS notification name
noti_type	String	AWS SNS
url_end_point	String	URL address to receive notifications
alarm_status	Object	Type of alarm notification status
alarm_status.queued	Boolean	The status of job queued notification
alarm_status.progressing	Boolean	The status of job in progress state notification
alarm_status.complete	Boolean	The status of job completed notification
alarm_status.error	Boolean	The status of error notification
alarm_status.stopped	Boolean	The status of Job stopped state notification
reg_time	String	Notification created date & time
update_time	String	Notification updated date & time

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "error_code": "0000",
    "error_message": "Success.",
    "time_zone": "+00:00",
    "total_count": 1,
    "data": [
        {
            "noti_id": 1,
            "site_id": "YOUR_SITE_ID",
            "noti_name": "noti_test",
            "noti_type": "SNS",
            "url_end_point": "arn:aws:sns:us-west-2:73041xxx:PallyCon_TNP_SNS",
            "access_key": "AK1252GDTP5xxxxx",
            "alarm_status": {
                "queued": true,
                "progressing": true,
                "complete": true,
                "error": true,
                "stopped": true
            },
            "update_time": "2024-08-05T11:02:05",
            "reg_time": "2024-08-05T10:18:58"
        }
    ]
}

SNS Delete

API to delete Job notification

• URL: https://tnp.pallycon.com/api/noti/job/{SiteID}/{notiId}
• Method: DELETE

Path Parameters

Parameter	Description
siteId	Your DoveRunner Site ID
notiId	Notification ID to be deleted

Sample Request

DELETE https://tnp.pallycon.com/api/noti/job/{SiteID}/{notiId}
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8

Host: tnp.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	error code
error_message	String	error message
data	Object	Job Notification information
data.noti_id	Number	Notification ID

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
   "error_code": "0000",
   "error_message": "Success.",
   "data": {
       "noti_id": 1
   }
}

Note

The maximum SNS that is supported at present is only 5. If a new notification is required, modify one of the existing or delete an unused notification id and create a new one.