Overview

This describes the resources that make up the official Dotsub REST API v3. If you have any problems or requests please contact Dotsub support.

Authentication

JWT is used to authenticate with Dotsub API. First of all user needs to log in with credentials. Server will respond to such request with JWT token, which can be used for authorizing all subsequent requests. JWT token will expire after one day.

To retrieve JWT token use this request:

POST /api/v3/login HTTP/1.1
Content-Length: 75

{ "email": "[email protected]", "password": "4JmMnseOzfT29UK8wS59" }
Path Type Description

email

String

User email to log in

password

String

Password

If credentials are correct, server will respond with such response:

HTTP/1.1 200 OK
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJuZXctdXNlckBkb3RzdWItdGVzdC5jb20iLCJleHAiOjE1OTQ2MDgyODJ9.XczKHNai__njCoMlFGSGZUNxJHlMHywBCW4hmjWfWF__wpsq9ZOKkFW5pUMWLkEBCu2nDXnPqyaKmOPazR1rSg
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Name Description

Authorization

JWT token to be used in to authorize requests

This token can be used as header in any request that needs to be authorized:

GET /api/v3/tasks HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJuZXctdXNlckBkb3RzdWItdGVzdC5jb20iLCJleHAiOjE1OTQ2MDgyODF9.QvIWdI9LAQ4nDw31h2FmMho8-AmyN2g4v8U87_IAvvM3nWENMEUYkWomwByM0LtwcrnSKRcqKNAFEXu_GGEMIg

HTTP verbs

Dotsub API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve data

POST

Used to create a new entity

PUT

Used to update an existing entity, including partial updates

DELETE

Used to delete an existing entity

HTTP status codes

Dotsub API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

403 Forbidden

The authenticated user is not permitted to perform the requested operation

404 Not Found

The requested resource did not exist

Errors

Whenever an error response (status code 4xx) is returned, the body will contain a JSON object that describes the problem. The error object has the following structure:

Path Type Description

error

String

The HTTP error that occurred, e.g. Not Found

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 404

timestamp

String

The time, in milliseconds, at which the error occurred

For example, if a media is requested and not found, the following would be the response:

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 138

{
  "timestamp" : "2020-07-12T02:44:47Z",
  "status" : 404,
  "error" : "Not Found",
  "message" : "",
  "path" : "/api/v3/media/foobar"
}

Whenever an Internal Server Error (status code 500) is returned, the body will contain only basic JSON information. The error object has the following structure:

Path Type Description

error

String

The HTTP error that occurred, e.g. Internal Server Error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 500

timestamp

String

The time, in milliseconds, at which the error occurred

Following would be the response for Internal Server Error:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 139

{
  "timestamp" : "2020-07-12T02:44:47Z",
  "status" : 500,
  "error" : "Internal Server Error",
  "path" : "/test/internal-server-error"
}

Media API

The Media API is used for reading, creating, updating, and deleting media.

Assumptions

The Project and Workflow for Media must be configured in the videotms.com application before Media API usage.

Read Media List

A GET request will list the organization’s media.

GET /api/v3/media

Query Parameters

Parameter Description

pageSize

Required Results are returned in pages of data. The pageSize value will be the maximum number of media returned in a page.

pageIndex

Required Page index in paged set

projectName

Filter by project name which contains media

workflowName

Filter by workflow name associated with media

tagName

Filter by tag associated with media

title

Filter by title of media

externalId

Filter by external ID of media.

organizationName

Filter by name of media’s organization

uploadVisible

Filter by upload visibility of media

sort

Sort the paged media set. The result set may be sorted by mediaId, title, projectName, organizationName, or createdDate. Default sort direction is Ascending. To sort Descending, prepend - to sort value. Default sort is by createdDate descending.

Example

Request

GET /api/v3/media?title=video+title&sort=-createdDate&pageIndex=0&pageSize=2 HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 4599

{
  "content" : [ {
    "mediaId" : "21",
    "title" : "Video Title 21",
    "projectId" : "12",
    "projectName" : "Project 10",
    "workflowName" : null,
    "clientId" : "1",
    "clientName" : "Client 1",
    "description" : "This is the description",
    "webhook" : null,
    "notes" : null,
    "errorMessage" : null,
    "mediaState" : null,
    "createdDate" : "2018-11-23T11:59:30Z",
    "workflowId" : null,
    "workflowTemplateOutdated" : null,
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "externalId" : null,
    "fileName" : "VIDEO-FOO-21.MOV",
    "language" : {
      "id" : "en-US",
      "code" : "eng",
      "countryCode" : "US",
      "alpha2BCode" : "eng",
      "alpha2TCode" : "eng",
      "alpha1Code" : "en",
      "name" : "English (United States)",
      "direction" : "LTR"
    },
    "reviewLanguages" : [ ],
    "translationLanguages" : [ ],
    "subtitledLanguageIds" : null,
    "tags" : [ ],
    "uploadDetail" : {
      "id" : "21",
      "start" : "2018-11-23T07:15:00Z",
      "finish" : null,
      "origin" : "BRIGHTCOVE",
      "status" : "UPLOADED",
      "percentage" : 100,
      "errorMessage" : null,
      "rawFileStorageUrl" : null,
      "ovp" : "BRIGHTCOVE_OAUTH",
      "uploadUpdateToken" : null
    },
    "encodedMedia" : {
      "id" : "21",
      "mp4Url" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/video.mp4",
      "rawS3Mp4Url" : "s3://dotsub-media-encoded/media/4/7/video.mp4",
      "mp4HdUrl" : null,
      "gifUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/video.gif",
      "thumbnailUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/thumb.jpg",
      "error" : null,
      "originalLengthInMilliseconds" : null,
      "encodedLengthInMilliseconds" : null,
      "reprocessWith" : null
    },
    "metadata" : {
      "type" : "VIDEO",
      "length" : 33000,
      "width" : null,
      "height" : null,
      "visible" : false,
      "uploaderUserId" : "21",
      "signedUrl" : null
    },
    "replacedImportedUrl" : null
  }, {
    "mediaId" : "20",
    "title" : "Video Title 20",
    "projectId" : "12",
    "projectName" : "Project 10",
    "workflowName" : null,
    "clientId" : "1",
    "clientName" : "Client 1",
    "description" : "This is the description",
    "webhook" : null,
    "notes" : null,
    "errorMessage" : null,
    "mediaState" : null,
    "createdDate" : "2018-11-23T11:59:00Z",
    "workflowId" : null,
    "workflowTemplateOutdated" : null,
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "externalId" : null,
    "fileName" : "VIDEO-FOO-20.MOV",
    "language" : {
      "id" : "en-US",
      "code" : "eng",
      "countryCode" : "US",
      "alpha2BCode" : "eng",
      "alpha2TCode" : "eng",
      "alpha1Code" : "en",
      "name" : "English (United States)",
      "direction" : "LTR"
    },
    "reviewLanguages" : [ ],
    "translationLanguages" : [ ],
    "subtitledLanguageIds" : null,
    "tags" : [ ],
    "uploadDetail" : {
      "id" : "20",
      "start" : "2018-11-23T07:15:00Z",
      "finish" : null,
      "origin" : "BRIGHTCOVE",
      "status" : "UPLOADED",
      "percentage" : 100,
      "errorMessage" : null,
      "rawFileStorageUrl" : null,
      "ovp" : "BRIGHTCOVE_OAUTH",
      "uploadUpdateToken" : null
    },
    "encodedMedia" : {
      "id" : "20",
      "mp4Url" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/video.mp4",
      "rawS3Mp4Url" : "s3://dotsub-media-encoded/media/4/7/video.mp4",
      "mp4HdUrl" : null,
      "gifUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/video.gif",
      "thumbnailUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/thumb.jpg",
      "error" : null,
      "originalLengthInMilliseconds" : null,
      "encodedLengthInMilliseconds" : null,
      "reprocessWith" : null
    },
    "metadata" : {
      "type" : "VIDEO",
      "length" : 33000,
      "width" : null,
      "height" : null,
      "visible" : false,
      "uploaderUserId" : "21",
      "signedUrl" : null
    },
    "replacedImportedUrl" : null
  } ],
  "pageable" : {
    "sort" : {
      "unsorted" : false,
      "sorted" : true,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 2,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 14,
  "totalPages" : 7,
  "last" : false,
  "numberOfElements" : 2,
  "sort" : {
    "unsorted" : false,
    "sorted" : true,
    "empty" : false
  },
  "first" : true,
  "number" : 0,
  "size" : 2,
  "empty" : false
}
Path Type Description

content

Array

Array of found media

content[].mediaId

String

ID of the media

content[].title

String

Title of the media

content[].projectId

String

ID of the project associated with the media

content[].projectName

String

Name of the project associated with the media

content[].workflowName

Null

Name of the workflow associated with the media

content[].clientId

String

ID of the client associated with the project

content[].clientName

String

Name of the client associated with the project

content[].description

String

Description of the media

content[].notes

Null

Notes of the media containing localization instructions. Markdown is supported.

content[].createdDate

String

Created Date of the media

content[].workflowId

Null

ID of the workflow for the media

content[].organizationId

String

URL of the organization of the media

content[].organizationName

String

Name of the organization of the media

content[].externalId

Null

The Client/OVP External ID for the media

content[].fileName

String

The file name associated to the media

content[].language

Object

The language of the media

content[].reviewLanguages

Array

Languages that will be reviewed for media

content[].translationLanguages

Array

Languages that will be translated for media

content[].tags

Array

Tags associated to media

content[].uploadDetail

Object

Upload details about media

content[].encodedMedia

Object

Encoded details about video associated to media

content[].metadata

Object

Metadata information about video and media

totalElements

Number

Total number of media in full result

totalPages

Number

Total number of pages in full result

first

Boolean

Is this the first page

last

Boolean

Is this the last page

size

Number

Number of media per page

number

Number

Page number

numberOfElements

Number

Number of media per page

sort

Object

Details of sort being applied

Read Media

A GET request will return a media for the organization.

GET /api/v3/media/:mediaId
Table 1. /api/v3/media/{mediaId}
Parameter Description

mediaId

The ID of the media to read

Example

Request

GET /api/v3/media/12 HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 2640

{
  "mediaId" : "12",
  "title" : "Video Title 11",
  "projectId" : "1",
  "projectName" : "Project 1",
  "workflowName" : "Project 1",
  "clientId" : "1",
  "clientName" : "Client 1",
  "description" : "This is the description",
  "webhook" : null,
  "notes" : "Media contains unique terminology.  \r[Test link](https://www.dotsub.com)",
  "errorMessage" : null,
  "mediaState" : null,
  "createdDate" : "2016-08-01T12:12:00Z",
  "workflowId" : "1",
  "workflowTemplateOutdated" : true,
  "organizationId" : "dotsub-test",
  "organizationName" : "Dotsub Test",
  "externalId" : null,
  "fileName" : "VIDEO-FOO-11.MOV",
  "language" : {
    "id" : "en-US",
    "code" : "eng",
    "countryCode" : "US",
    "alpha2BCode" : "eng",
    "alpha2TCode" : "eng",
    "alpha1Code" : "en",
    "name" : "English (United States)",
    "direction" : "LTR"
  },
  "reviewLanguages" : [ {
    "id" : "fr-FR",
    "code" : "fra",
    "countryCode" : "FR",
    "alpha2BCode" : "fre",
    "alpha2TCode" : "fra",
    "alpha1Code" : "fr",
    "name" : "French (France)",
    "direction" : "LTR"
  } ],
  "translationLanguages" : [ {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  }, {
    "id" : "fr-FR",
    "code" : "fra",
    "countryCode" : "FR",
    "alpha2BCode" : "fre",
    "alpha2TCode" : "fra",
    "alpha1Code" : "fr",
    "name" : "French (France)",
    "direction" : "LTR"
  } ],
  "subtitledLanguageIds" : [ "ar-SA" ],
  "tags" : [ ],
  "uploadDetail" : {
    "id" : "12",
    "start" : "2016-01-20T07:15:00Z",
    "finish" : null,
    "origin" : "DISK",
    "status" : "UPLOADED",
    "percentage" : 100,
    "errorMessage" : null,
    "rawFileStorageUrl" : null,
    "ovp" : null,
    "uploadUpdateToken" : null
  },
  "encodedMedia" : {
    "id" : "12",
    "mp4Url" : "http://dotsub-media-encoded.s3.amazonaws.com/1/14/14.mp4",
    "rawS3Mp4Url" : "s3://dotsub-media-encoded/1/14/14.mp4",
    "mp4HdUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/1/14/14_hd.mp4",
    "gifUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/video.gif",
    "thumbnailUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/thumb.jpg",
    "error" : null,
    "originalLengthInMilliseconds" : null,
    "encodedLengthInMilliseconds" : null,
    "reprocessWith" : null
  },
  "metadata" : {
    "type" : "VIDEO",
    "length" : 33000,
    "width" : null,
    "height" : null,
    "visible" : false,
    "uploaderUserId" : "1",
    "signedUrl" : null
  },
  "replacedImportedUrl" : null
}
Path Type Description

mediaId

String

ID of the media

title

String

Title of the media

projectId

String

ID of the project associated with the media

projectName

String

Name of the project associated with the media

workflowName

String

Name of the workflow associated with the media

clientId

String

ID of the client associated with the project

clientName

String

Name of the client associated with the project

description

String

Description of the media

notes

String

Notes of the media containing localization instructions. Markdown is supported.

createdDate

String

Created Date of the media

workflowId

String

ID of the workflow for the media

organizationId

String

URL of the organization of the media

organizationName

String

Name of the organization of the media

externalId

Null

The Client/OVP External ID for the media

fileName

String

The file name associated to the media

language

Object

The language of the media

reviewLanguages

Array

Languages that will be reviewed for media

translationLanguages

Array

Languages that will be translated for media

subtitledLanguageIds

Array

Language IDs for subtitles that are complete

tags

Array

Tags associated to media

uploadDetail

Object

Upload details about media

encodedMedia

Object

Encoded details about video associated to media

metadata

Object

Metadata information about video and media

Read Media Subtitles

A GET request will return a media’s completed subtitles for a specified language and format.

  • The subtitledLanguageIds property returned in the Read Media request should be used to determine which languages have completed subtitles for a media.

GET /api/v3/media/:mediaId/languages/:languageId/subtitles/:subtitleFormat
Table 2. /api/v3/media/{mediaId}/languages/{languageId}/subtitles/{subtitleFormat}
Parameter Description

mediaId

The ID of the media associated with subtitle

languageId

The ID of the language associated with subtitle

subtitleFormat

The Format of subtitle desired. Valid formats are VTT, SRT, TTML, and SSA

Example

Request

GET /api/v3/media/1/languages/en-US/subtitles/VTT HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Disposition: attachment;filename=Video_Title_1_en_US.vtt
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 134

WEBVTT
X-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000

1
00:00:01.000 --> 00:00:03.000 align:middle position:50%
Hello Cruel World

Upload Media Subtitles

A POST request to upload new subtitles for a media’s language. The Content-Type request header must be set to multipart/form-data.

  • The subtitle file format must be a valid SRT file.

  • Languages are created for media as defined by the videotms workflow. This means that all languages may not exist right after a media is created. For example, if a workflow is to caption a video in English (US) then translate to the captions to Spanish, the Spanish language will not be created until after the English captioning is completed. If a requested language doesn’t exist for a media, a 404 Not Found error response is returned.

POST /api/v3/media/:mediaId/languages/:languageId/subtitles
Table 3. /api/v3/media/{mediaId}/languages/{languageId}/subtitles
Parameter Description

mediaId

The ID of the media associated with subtitle

languageId

The ID of the language associated with subtitle

Request Headers

Name Description

completeTask

Set to true if the associated workflow task should be marked completed

Example

Request

POST /api/v3/media/14/languages/en-US/subtitles HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
completeTask: false

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=subtitleFile; filename=_dmd_short_eng.srt
Content-Type: multipart/form-data

1
00:00:06,000 --> 00:00:09,000
There are billions of galaxies in the observable universe

2
00:00:09,000 --> 00:00:12,000
and each of ther contains hundreds of billion of stars

3
00:00:12,000 --> 00:00:15,000
in one of these galaxies...


--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 1865

{
  "trackId" : "15",
  "name" : "Source Proj 14",
  "language" : {
    "id" : "en-US",
    "code" : null,
    "countryCode" : "US",
    "alpha2BCode" : "eng",
    "alpha2TCode" : "eng",
    "alpha1Code" : "en",
    "name" : "English (United States)",
    "direction" : "LTR"
  },
  "type" : "CAPTION",
  "sourceTrack" : null,
  "currentVersion" : {
    "trackVersionId" : "ea0d5ae9-a1bf-4194-b6f8-b5fadef700f7",
    "title" : null,
    "description" : null,
    "comment" : "Imported from _dmd_short_eng.srt",
    "completion" : 27,
    "createdBy" : {
      "userId" : "6",
      "firstname" : "Dotsub Manager",
      "lastname" : "Manager",
      "email" : "[email protected]",
      "systemAdmin" : false,
      "displayName" : "Dotsub Manager Manager",
      "timezone" : "America/Los_Angeles",
      "assigneeId" : null,
      "invitationId" : null,
      "organizationRoles" : null
    },
    "createdAt" : "2020-07-12T02:44:46.147069Z",
    "finalized" : true,
    "lockingVersion" : 0,
    "overlapEnabled" : false
  },
  "versions" : [ {
    "trackVersionId" : "ea0d5ae9-a1bf-4194-b6f8-b5fadef700f7",
    "title" : null,
    "description" : null,
    "comment" : "Imported from _dmd_short_eng.srt",
    "completion" : 27,
    "createdBy" : {
      "userId" : "6",
      "firstname" : "Dotsub Manager",
      "lastname" : "Manager",
      "email" : "[email protected]",
      "systemAdmin" : false,
      "displayName" : "Dotsub Manager Manager",
      "timezone" : "America/Los_Angeles",
      "assigneeId" : null,
      "invitationId" : null,
      "organizationRoles" : null
    },
    "createdAt" : "2020-07-12T02:44:46.147069Z",
    "finalized" : true,
    "lockingVersion" : 0,
    "overlapEnabled" : false
  } ],
  "reviews" : [ ],
  "trackSource" : false,
  "mediaTitle" : "Video Title 14",
  "organizationId" : "dotsub-test",
  "taskId" : null
}

Create Media

A POST request will create media for the user’s organization.

POST /api/v3/media

When creating media, the request should either have s3Upload set to true or a valid URL in importUrl:

  • If s3Upload is set to true, the S3 signed URL is returned in the response metadata.signedUrl along with a token in uploadDetail.uploadUpdateToken. The metadata.signedUrl is to be used for uploading the video associated with this media. The API does not upload the video, it is the responsibility of the client to upload the video. Once the upload is complete, an update media API call must be made to update the upload status to UPLOADED so that processing can complete for the media in Dotsub. The token in uploadDetail.uploadUpdateToken must be included in the update media API request.

  • If the importUrl field is set to a valid URL, the API will use the URL to ingest and encode the video as part of media creation.

Input

Path Type Description

s3Upload

Boolean

Boolean to indicate if video associated to media will be uploaded to the dotsub-media AWS S3 bucket.

importUrl

String

URL of video to be imported and associated with the media.

contentType

String

If S3Upload is true, the content type of the video must be set in this field

mediaDto.title

String

Required Title of media

mediaDto.projectId

String

Required ID of project of media

mediaDto.fileName

String

Required File name to be associated with media

mediaDto.description

String

Description of media

mediaDto.notes

String

Notes of the media containing localization instructions. Markdown is supported.

mediaDto.tags[].name

String

The names of tags associated with the media

mediaDto.language.id

String

Language ID of media

mediaDto.translationLanguages[].id

String

The languages IDs for the media’s captioning will be translated

mediaDto.reviewLanguages[].id

String

The languages IDs that will be reviewed for captions of the media

mediaDto.workflowId

String

ID of the workflow to be associated with the media

mediaDto.externalId

String

Client External ID of the the media

mediaDto.webhook

String

Webhook URL that will be called as task lifecycle events occur for the media.

Example

Request

POST /api/v3/media HTTP/1.1
Content-Type: application/json;charset=UTF-8

{
  "s3Upload": true,
  "mediaDto": {
      "title": "Create Video Title",
      "description": "This is the description-new",
      "projectId": "1",
      "tags": [
        {
          "name": "Medical"
        }
      ],
      "fileName": "_test_file.mp4",
      "language": { "id": "en-US" },
      "translationLanguages": [
        {
          "id": "it-IT"
        },
        {
          "id": "es-ES"
        }
      ],
      "reviewLanguages": [
        {
          "id": "it-IT"
        },
        {
          "id": "es-ES"
        }
      ]
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 2977

{
  "mediaId" : "5c4f479f-0375-40e5-8077-b48c227152bc",
  "title" : "Create Video Title",
  "projectId" : "1",
  "projectName" : "Project 1",
  "workflowName" : null,
  "clientId" : "1",
  "clientName" : "Client 1",
  "description" : "This is the description-new",
  "webhook" : null,
  "notes" : null,
  "errorMessage" : null,
  "mediaState" : null,
  "createdDate" : "2020-07-12T02:44:45.331986Z",
  "workflowId" : null,
  "workflowTemplateOutdated" : null,
  "organizationId" : "dotsub-test",
  "organizationName" : "Dotsub Test",
  "externalId" : null,
  "fileName" : "_test_file.mp4",
  "language" : {
    "id" : "en-US",
    "code" : "eng",
    "countryCode" : "US",
    "alpha2BCode" : "eng",
    "alpha2TCode" : "eng",
    "alpha1Code" : "en",
    "name" : "English (United States)",
    "direction" : "LTR"
  },
  "reviewLanguages" : [ {
    "id" : "es-ES",
    "code" : "spa",
    "countryCode" : "ES",
    "alpha2BCode" : "spa",
    "alpha2TCode" : "spa",
    "alpha1Code" : "es",
    "name" : "Spanish (Spain)",
    "direction" : "LTR"
  }, {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  } ],
  "translationLanguages" : [ {
    "id" : "es-ES",
    "code" : "spa",
    "countryCode" : "ES",
    "alpha2BCode" : "spa",
    "alpha2TCode" : "spa",
    "alpha1Code" : "es",
    "name" : "Spanish (Spain)",
    "direction" : "LTR"
  }, {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  } ],
  "subtitledLanguageIds" : null,
  "tags" : [ {
    "tagId" : "1",
    "name" : "Medical",
    "color" : "7766927",
    "textColor" : "16777215",
    "workflow" : null,
    "colorHex" : "#76838F",
    "textColorHex" : "#FFFFFF"
  } ],
  "uploadDetail" : {
    "id" : "46d30975-c221-407f-82e4-85bc7f1d99f6",
    "start" : "2020-07-12T02:44:45.236805Z",
    "finish" : null,
    "origin" : "DISK",
    "status" : "IN_QUEUE",
    "percentage" : 0,
    "errorMessage" : null,
    "rawFileStorageUrl" : null,
    "ovp" : null,
    "uploadUpdateToken" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI1YzRmNDc5Zi0wMzc1LTQwZTUtODA3Ny1iNDhjMjI3MTUyYmMifQ.p_Z6fovgJfB0FoFMMLQO55jz_4PAaWpF5UjOD3eQId_DhnhqUJ5LOLU0lY9jn1CBpYr5UyTf5IsI5psU6uCcWg"
  },
  "encodedMedia" : {
    "id" : "f83d0459-170d-4041-88c5-f69f94252f09",
    "mp4Url" : null,
    "rawS3Mp4Url" : null,
    "mp4HdUrl" : null,
    "gifUrl" : null,
    "thumbnailUrl" : null,
    "error" : null,
    "originalLengthInMilliseconds" : null,
    "encodedLengthInMilliseconds" : null,
    "reprocessWith" : null
  },
  "metadata" : {
    "type" : "VIDEO",
    "length" : null,
    "width" : null,
    "height" : null,
    "visible" : true,
    "uploaderUserId" : "6",
    "signedUrl" : "<URL_Dotsub_Media_S3>"
  },
  "replacedImportedUrl" : null
}

Update Media

A PATCH request will update the organization’s media.

PATCH /api/v3/media/:mediaId
Table 4. /api/v3/media/{mediaId}
Parameter Description

mediaId

The ID of the media to update

Input

The following fields may be updated:

Path Type Description

title

String

Title of media

description

String

Description of media

notes

String

Notes of the media containing localization instructions. Markdown is supported.

webhook

String

Webhook URL that will be called as task lifecycle events occur for the media.

workflowId

String

ID of the workflow to be associated with the media

externalId

String

Media External ID, either the Client External Id or Ingest OVP External Id (take caution if updating OVP Ingest External Id, update won’t propagate to OVP)

uploadDetail.uploadUpdateToken

String

Token to be included when updating uploadDetail attributes. Only pending DISK uploads can be updated

uploadDetail.status

String

Upload status of media. Valid values are IN_QUEUE, WAITING, UPLOADING, UPLOADED, ERROR

uploadDetail.percentage

Number

Upload completion percentage.

uploadDetail.visible

Boolean

Whether the media upload is visible.

tags[].name

String

The tag names associated with the media

translationLanguages[].id

String

The translation language IDs of the media

reviewLanguages[].id

String

The review language IDs with the media

Example

Request

PATCH /api/v3/media/12 HTTP/1.1
Content-Type: application/json;charset=UTF-8

{
  "title": "Video Title 11-new",
  "description": "This is the description-new",
  "tags": [ { "name": "Medical" } ],
  "translationLanguages": [
    {
      "id": "it-IT"
    },
    {
      "id": "es-ES"
    }
  ],
  "reviewLanguages": [
    {
      "id": "it-IT"
    },
    {
      "id": "es-ES"
    }
  ]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 3027

{
  "mediaId" : "12",
  "title" : "Video Title 11-new",
  "projectId" : "1",
  "projectName" : "Project 1",
  "workflowName" : "Project 1",
  "clientId" : "1",
  "clientName" : "Client 1",
  "description" : "This is the description-new",
  "webhook" : null,
  "notes" : "Media contains unique terminology.  \r[Test link](https://www.dotsub.com)",
  "errorMessage" : null,
  "mediaState" : null,
  "createdDate" : "2016-08-01T12:12:00Z",
  "workflowId" : "1",
  "workflowTemplateOutdated" : true,
  "organizationId" : "dotsub-test",
  "organizationName" : "Dotsub Test",
  "externalId" : null,
  "fileName" : "VIDEO-FOO-11.MOV",
  "language" : {
    "id" : "en-US",
    "code" : "eng",
    "countryCode" : "US",
    "alpha2BCode" : "eng",
    "alpha2TCode" : "eng",
    "alpha1Code" : "en",
    "name" : "English (United States)",
    "direction" : "LTR"
  },
  "reviewLanguages" : [ {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  }, {
    "id" : "es-ES",
    "code" : "spa",
    "countryCode" : "ES",
    "alpha2BCode" : "spa",
    "alpha2TCode" : "spa",
    "alpha1Code" : "es",
    "name" : "Spanish (Spain)",
    "direction" : "LTR"
  } ],
  "translationLanguages" : [ {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  }, {
    "id" : "es-ES",
    "code" : "spa",
    "countryCode" : "ES",
    "alpha2BCode" : "spa",
    "alpha2TCode" : "spa",
    "alpha1Code" : "es",
    "name" : "Spanish (Spain)",
    "direction" : "LTR"
  } ],
  "subtitledLanguageIds" : null,
  "tags" : [ {
    "tagId" : "1",
    "name" : "Medical",
    "color" : "7766927",
    "textColor" : "16777215",
    "workflow" : null,
    "colorHex" : "#76838F",
    "textColorHex" : "#FFFFFF"
  } ],
  "uploadDetail" : {
    "id" : "12",
    "start" : "2016-01-20T07:15:00Z",
    "finish" : null,
    "origin" : "DISK",
    "status" : "UPLOADED",
    "percentage" : 100,
    "errorMessage" : null,
    "rawFileStorageUrl" : null,
    "ovp" : null,
    "uploadUpdateToken" : null
  },
  "encodedMedia" : {
    "id" : "12",
    "mp4Url" : "http://dotsub-media-encoded.s3.amazonaws.com/1/14/14.mp4",
    "rawS3Mp4Url" : "s3://dotsub-media-encoded/1/14/14.mp4",
    "mp4HdUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/1/14/14_hd.mp4",
    "gifUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/video.gif",
    "thumbnailUrl" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/thumb.jpg",
    "error" : null,
    "originalLengthInMilliseconds" : null,
    "encodedLengthInMilliseconds" : null,
    "reprocessWith" : null
  },
  "metadata" : {
    "type" : "VIDEO",
    "length" : 33000,
    "width" : null,
    "height" : null,
    "visible" : false,
    "uploaderUserId" : "1",
    "signedUrl" : null
  },
  "replacedImportedUrl" : null
}

Delete Media

A DELETE request will delete media from the user’s organization.

DELETE /api/v3/media/:mediaId
Table 5. /api/v3/media/{mediaId}
Parameter Description

mediaId

The ID of the media to delete

Example

Request

DELETE /api/v3/media/4 HTTP/1.1

Response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN

Task API

The Task API is used for reading and updating tasks.

Read Tasks List

A GET request will list tasks.

GET /api/v3/tasks

Query Parameters

Parameter Description

pageSize

Required Results are returned in pages of data. The pageSize value will be the maximum number of media returned in a page. Max Allowed: 50 Default: 50

pageIndex

Required Page index in paged set

sort

Sort the paged media set. The result set may be sorted by mediaId, title, projectName, type, dueDate, or createdDate. Default sort direction is Descending. To sort Ascending, prepend + to sort value. Default -createdDate

projectName

Filter by Name of the project associated with the media

organizationId

Filter by task organization ID

clientOrganizationId

Filter by clientOrganization ID of the task

type

Filter by Type of the task can be one of following values (TASK_CAPTION, TASK_TRANSLATE, TASK_DIRECT_TRANSLATE, TASK_REVIEW, TASK_REVIEW_REWORK, TASK_BURN_IN, TASK_CUSTOM, TASK_PUSH)

languageId

Filter by task language code Language ID is (ISO 639-1 + 'dash' + ISO-3166-1) eg: en-US

mediaId

Filter by ID of the media

mediaTitle

Filter by Title of the media

mediaExternalId

Filter by the OVP external ID for the media

assigneeType

Filter by Assignee Type of the task can be one of following values (GROUP, USER, ASR, BURN_IN, NONE)

assigneeName

Filter by Assignee Name of the task.

createdDate

Filter by Created Date of the task should be in ISO8601 format eg:2018-09-01T12:01:00

dueDateStart

Filter by Due Date Start of the task should be in ISO8601 format eg:2018-09-01T12:01:00

dueDateEnd

Filter by Due Date End of the task should be in ISO8601 format eg:2018-09-01T12:01:00

completionDateStart

Filter by Completion Date Start of the task should be in ISO8601 format eg:2018-09-01T12:01:00

completionDateEnd

Filter by Completion Date End the task should be in ISO8601 format eg:2018-09-01T12:01:00

completed

Filter by completed tasks

accepted

Filter by accepted tasks

Example

Request

GET /api/v3/tasks?sort=-createdDate&pageIndex=0&pageSize=2 HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 4094

{
  "content" : [ {
    "id" : "12",
    "assigneeId" : "8",
    "assigneeType" : "USER",
    "assigneeName" : "Translator, Jimmy",
    "assigneeEmail" : "[email protected]",
    "createdDate" : "2016-08-01T12:12:01Z",
    "dueDate" : "2016-09-01T12:12:00Z",
    "projectId" : "1",
    "projectName" : "Project 1",
    "completed" : true,
    "completionDate" : "2018-08-18T12:12:00Z",
    "accepted" : true,
    "type" : "TASK_TRANSLATE",
    "languageId" : "fr-FR",
    "languageName" : "French (France)",
    "mediaTitle" : "Video Title 11",
    "mediaDescription" : "This is the description",
    "mediaFilename" : "VIDEO-FOO-11.MOV",
    "mediaId" : "12",
    "mediaExternalId" : null,
    "mediaState" : null,
    "relatedTrackType" : "TRANSLATION",
    "trackId" : "12",
    "trackCurrentVersionId" : "18",
    "trackCompletionPercentage" : "100",
    "description" : null,
    "sourceTrackId" : "11",
    "trackReviewId" : null,
    "sourceTrackLanguageId" : "en-US",
    "sourceTrackLanguageName" : "English (United States)",
    "sourceTrackCurrentVersionId" : "16",
    "sourceTrackSourceTrackId" : null,
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "originAssigneeId" : null,
    "originAssigneeType" : null,
    "totalCost" : 2.5,
    "totalPrice" : 4.0,
    "invoiced" : false,
    "paid" : false,
    "length" : "33000",
    "lengthSeconds" : "33.0",
    "deletable" : true,
    "openUri" : "/tasks/12?open",
    "tags" : [ ],
    "pvmRate" : null,
    "errored" : false,
    "errorMessage" : null,
    "vendorOrganizationId" : null,
    "vendorOrganizationName" : null,
    "clientOrganizationId" : null,
    "clientOrganizationName" : null,
    "sharedHeadTaskId" : null,
    "sharedIndex" : null,
    "taskGroupCreatedDate" : "2016-08-01T12:12:00Z",
    "state" : null
  }, {
    "id" : "11",
    "assigneeId" : "8",
    "assigneeType" : "USER",
    "assigneeName" : "Translator, Jimmy",
    "assigneeEmail" : "[email protected]",
    "createdDate" : "2016-08-01T12:11:00Z",
    "dueDate" : "2016-09-01T12:11:00Z",
    "projectId" : "1",
    "projectName" : "Project 1",
    "completed" : true,
    "completionDate" : "2018-08-18T12:11:00Z",
    "accepted" : true,
    "type" : "TASK_CAPTION",
    "languageId" : "en-US",
    "languageName" : "English (United States)",
    "mediaTitle" : "Video Title 11",
    "mediaDescription" : "This is the description",
    "mediaFilename" : "VIDEO-FOO-11.MOV",
    "mediaId" : "12",
    "mediaExternalId" : null,
    "mediaState" : null,
    "relatedTrackType" : "CAPTION",
    "trackId" : "11",
    "trackCurrentVersionId" : "16",
    "trackCompletionPercentage" : "100",
    "description" : null,
    "sourceTrackId" : null,
    "trackReviewId" : null,
    "sourceTrackLanguageId" : null,
    "sourceTrackLanguageName" : null,
    "sourceTrackCurrentVersionId" : null,
    "sourceTrackSourceTrackId" : null,
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "originAssigneeId" : null,
    "originAssigneeType" : null,
    "totalCost" : 1.5,
    "totalPrice" : 2.5,
    "invoiced" : false,
    "paid" : false,
    "length" : "33000",
    "lengthSeconds" : "33.0",
    "deletable" : true,
    "openUri" : "/tasks/11?open",
    "tags" : [ ],
    "pvmRate" : null,
    "errored" : false,
    "errorMessage" : null,
    "vendorOrganizationId" : null,
    "vendorOrganizationName" : null,
    "clientOrganizationId" : null,
    "clientOrganizationName" : null,
    "sharedHeadTaskId" : null,
    "sharedIndex" : null,
    "taskGroupCreatedDate" : "2016-08-01T12:11:00Z",
    "state" : null
  } ],
  "pageable" : {
    "sort" : {
      "unsorted" : false,
      "sorted" : true,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 2,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 20,
  "totalPages" : 10,
  "last" : false,
  "numberOfElements" : 2,
  "sort" : {
    "unsorted" : false,
    "sorted" : true,
    "empty" : false
  },
  "first" : true,
  "number" : 0,
  "size" : 2,
  "empty" : false
}
Path Type Description

content

Array

Array of found tasks

content[].id

String

ID of the task

content[].assigneeId

String

Task Assignee ID

content[].assigneeName

String

Task Assignee Name

content[].assigneeEmail

String

Task Assignee Email

content[].assigneeType

String

Task Assignee Type

content[].createdDate

String

Created Date of the task in ISO8601 format

content[].dueDate

String

Due Date of the task in ISO8601 format

content[].projectId

String

Project Id of the task

content[].projectName

String

Project Name of the task

content[].completed

Boolean

Is task completed

content[].completionDate

String

Completion Date of the task in ISO8601 format

content[].accepted

Boolean

Is task accepted

content[].errored

Boolean

Is task errored

content[].errorMessage

Null

Task error message

content[].type

String

Type of the task can be one of following values (TASK_CAPTION, TASK_TRANSLATE, TASK_DIRECT_TRANSLATE, TASK_REVIEW, TASK_REVIEW_REWORK, TASK_BURN_IN, TASK_CUSTOM, TASK_PUSH)

content[].languageId

String

Language Id of the task eg: en-US

content[].languageName

String

Fully qualified name of task language eg: English(United States)

content[].mediaTitle

String

Title of the task’s media

content[].mediaDescription

String

Description of the task’s media

content[].mediaFilename

String

File name of the task’s media

content[].mediaId

String

Media ID of the task’s media

content[].mediaExternalId

Null

The OVP external ID for the task’s media

content[].trackId

String

Track Id of the task

content[].trackCurrentVersionId

String

Track Current Version ID of the task

content[].description

Null

Description of the task

content[].sourceTrackId

String

Source Track Id of the task

content[].trackReviewId

Null

Track Review Id of the task

content[].sourceTrackLanguageId

String

Source Track Language Id

content[].sourceTrackLanguageName

String

Source Track Language Name of the task

content[].sourceTrackCurrentVersionId

String

Source Track Current Version of the task

content[].sourceTrackSourceTrackId

Null

Source Track of Source Track Id of the task

content[].organizationId

String

URL of the organization assigned to work of the task

content[].organizationName

String

Name of the organization assigned to work of the task

content[].organizationId

String

ID of the organization assigned to work on the task

content[].originAssigneeId

Null

Origin Assignee ID of the task

content[].originAssigneeType

Null

Origin Assignee Type of the task

content[].totalCost

Number

Total Cost of the task

content[].totalPrice

Number

Total Price of the task

content[].invoiced

Boolean

Is task invoiced

content[].paid

Boolean

Is task paid

content[].pvmRate

Null

Rate per video minute

content[].clientOrganizationId

Null

ID of client organization associated with the task

content[].vendorOrganizationId

Null

ID of vendor organization associated with the task

content[].sharedHeadTaskId

Null

ID of head shared task from client

content[].sharedIndex

Null

Index in shared task chain

content[].taskGroupCreatedDate

String

Timestamp of shared task chain

content[].length

String

Media length in Milliseconds

content[].deletable

Boolean

Is task deletable

content[].openUri

String

Relative URI for the media

content[].tags

Array

Available tags of the OVP video if any

totalElements

Number

Total number of media in full result

totalPages

Number

Total number of pages in full result

first

Boolean

Is this the first page

last

Boolean

Is this the last page

size

Number

Number of media per page

number

Number

Page number

numberOfElements

Number

Number of media per page

sort

Object

Sort details

Update Task

A PATCH request may be used to update certain properties of a task.

PATCH /api/v3/tasks/:vtmsTaskId
Table 6. /api/v3/tasks/{vtmsTaskId}
Parameter Description

vtmsTaskId

The ID of the task to update

Input

The following fields may be updated:

Path Type Description

completed

Boolean

Sets completed status of task

accepted

Boolean

Sets accepted status of task. A value of true sets the task as accepted and assigns the task to the requesting user. A value of false sets the releases the task and assigns the task to the original assignee.

dueDate

String

Due Date of the task in ISO8601 format

description

String

Description of the task

assigneeId

Object

Must pass ID of assignee to set.

errored

Boolean

Sets errored status of task

errorMessage

String

Sets error message of task

Example

Request

PATCH /api/v3/tasks/4 HTTP/1.1
Content-Type: application/json;charset=UTF-8

{
  "completed": true
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 2040

{
  "id" : "4",
  "assigneeId" : "8",
  "assigneeType" : "USER",
  "assigneeName" : "Translator, Jimmy",
  "assigneeEmail" : "[email protected]",
  "createdDate" : "2016-08-01T12:04:00Z",
  "dueDate" : "2016-09-01T12:04:00Z",
  "projectId" : "1",
  "projectName" : "Project 1",
  "completed" : true,
  "completionDate" : "2020-07-12T02:44:44.555114Z",
  "accepted" : true,
  "type" : "TASK_CAPTION",
  "languageId" : "es-ES",
  "languageName" : "Spanish (Spain)",
  "mediaTitle" : "Video Title 1",
  "mediaDescription" : "This is the description",
  "mediaFilename" : "VIDEO-FOO.MOV",
  "mediaId" : "1",
  "mediaExternalId" : null,
  "mediaState" : null,
  "relatedTrackType" : "CAPTION",
  "trackId" : "4",
  "trackCurrentVersionId" : "5",
  "trackCompletionPercentage" : "0",
  "description" : null,
  "sourceTrackId" : null,
  "trackReviewId" : null,
  "sourceTrackLanguageId" : null,
  "sourceTrackLanguageName" : null,
  "sourceTrackCurrentVersionId" : null,
  "sourceTrackSourceTrackId" : null,
  "organizationId" : "dotsub-test",
  "organizationName" : "Dotsub Test",
  "originAssigneeId" : null,
  "originAssigneeType" : null,
  "totalCost" : 0,
  "totalPrice" : 0,
  "invoiced" : false,
  "paid" : false,
  "length" : "60000",
  "lengthSeconds" : "60.0",
  "deletable" : true,
  "openUri" : "/tasks/4?open",
  "tags" : [ {
    "tagId" : "7",
    "name" : "Tag One",
    "color" : "10407527",
    "textColor" : "16777215",
    "workflow" : null,
    "colorHex" : "#9ECE67",
    "textColorHex" : "#FFFFFF"
  }, {
    "tagId" : "8",
    "name" : "Tag Two",
    "color" : "4700358",
    "textColor" : "16777215",
    "workflow" : null,
    "colorHex" : "#47B8C6",
    "textColorHex" : "#FFFFFF"
  } ],
  "pvmRate" : null,
  "errored" : false,
  "errorMessage" : null,
  "vendorOrganizationId" : null,
  "vendorOrganizationName" : null,
  "clientOrganizationId" : null,
  "clientOrganizationName" : null,
  "sharedHeadTaskId" : null,
  "sharedIndex" : null,
  "taskGroupCreatedDate" : "2016-08-01T12:04:00Z",
  "state" : null
}
Path Type Description

id

String

ID of the task

assigneeId

String

Task Assignee ID

assigneeName

String

Task Assignee Name

assigneeType

String

Task Assignee Type

createdDate

String

Created Date of the task in ISO8601 format

dueDate

String

Due Date of the task in ISO8601 format

projectId

String

Project Id of the task

projectName

String

Project Name of the task

completed

Boolean

Is task completed

completionDate

String

Completion Date of the task in ISO8601 format

accepted

Boolean

Is task accepted

errored

Boolean

Is task errored

errorMessage

Null

Task error message

type

String

Type of the task can be one of following values (TASK_CAPTION, TASK_TRANSLATE, TASK_DIRECT_TRANSLATE, TASK_REVIEW, TASK_REVIEW_REWORK, TASK_BURN_IN, TASK_CUSTOM, TASK_PUSH)

languageId

String

Language Id of the task eg: en-US

languageName

String

Fully qualified name of task language eg: English(United States)

mediaTitle

String

Title of the task’s media

mediaDescription

String

Description of the task’s media

mediaFilename

String

File name of the task’s media

mediaId

String

Media Id of the task’s media

mediaExternalId

Null

The OVP external ID for the task’s media

trackId

String

Track Id of the task

trackCurrentVersionId

String

Track Current Version ID of the task

description

Null

Description of the task

sourceTrackId

Null

Source Track Id of the task

trackReviewId

Null

Track Review Id of the task

sourceTrackLanguageName

Null

Source Track Language Name of the task

sourceTrackCurrentVersionId

Null

Source Track Current Version of the task

organizationId

String

URL of the task’s organization of the task

organizationName

String

Name of the task organization of the task

originAssigneeId

Null

Origin Assignee ID of the task

originAssigneeType

Null

Origin Assignee Type of the task

totalCost

Number

Total Cost of the task

totalPrice

Number

Total Price of the task

invoiced

Boolean

Is task invoiced

paid

Boolean

Is task paid

pvmRate

Null

Rate per video minute

clientOrganizationId

Null

ID of client organization associated with the task

vendorOrganizationId

Null

ID of vendor organization associated with the task

sharedHeadTaskId

Null

ID of head shared task from client

sharedIndex

Null

Index in shared task chain

taskGroupCreatedDate

String

Timestamp of shared task chain

length

String

Media length in Milliseconds

deletable

Boolean

Is task deletable

openUri

String

Relative URI for the task

tags

Array

Available tags of the OVP video if any

Notifications API

The Notifications API uses the Media webhook URL or the Organization Webhook to POST JSON notifications as task actions occur for the Media.

In order for the notification to be sent to the webhook URL, it must be valid, and the media’s organization has to be opted in for API Webhook notification types. You can opt in/out for the task actions you wish to be notified about using the Organization/Notification Configuration page in the application.

The Organization Webhook can be set in the application on the Organization/Basic Settings screen.

Task Actions

Action Description

CAPTIONING_REQUEST

Captioning task created. Request has been sent to do the work.

CAPTIONING_ASSIGNED

Captioning task assigned for work.

CAPTIONING_ACCEPTED

Captioning task has been accepted by a person to do the work.

CAPTIONING_FINISHED

Captioning task has been finished. Captions are ready. If captioned are to be reviewed, REVIEW_* actions will be sent when complete.

TRANSLATION_REQUEST

Translation task created. Request has been sent to do the work.

TRANSLATION_ASSIGNED

Translation task assigned for work.

TRANSLATION_ACCEPTED

Translation task has been accepted by a person to do the work.

TRANSLATION_FINISHED

Translation task has been finished. Subtitles are ready. If subtitles are to be reviewed, REVIEW_* actions will be sent when complete.

REVIEW_REQUEST

Review task for captioning/translation created. Request has been sent to do the work.

REVIEW_ASSIGNED

Review task for captioning/translation assigned for work.

REVIEW_ACCEPTED

Review task for captioning/translation has been accepted by a person to do the work.

REVIEW_FINISHED

Review task for captioning/translation has been finished and captions/subtitles are ready.

CUSTOM_REQUEST

Custom task created and request has been sent to do the work.

CUSTOM_ASSIGNED

Custom task assigned for work.

CUSTOM_ACCEPTED

Custom task has been accepted by a person to do the work.

CUSTOM_FINISHED

Custom task has been finished and captions are ready.

BURN_IN_FINISHED

Burn in task has finished successfully.

BURN_IN_FAILED

Burn in task has failed.

Notification Structure

Sample Notification JSON

Below is a sample of the notification JSON that will be POSTed to your webhook URL.

{
  "dateTime" : "2019-05-31T10:59:22Z",
  "action" : "CAPTIONING_ASSIGNED",
  "taskId" : "1",
  "projectId" : "1",
  "mediaId" : "1",
  "languageId" : "en-US"
}

Project API

The Project API is used for reading lists of projects.

Read Project List

A GET request will list projects.

GET /api/v3/projects

Query Parameters

Parameter Description

pageSize

Required Results are returned in pages of data. The pageSize value will be the maximum number of projects returned in a page.

pageIndex

Required Page index in paged set

Example

Request

GET /api/v3/projects?pageIndex=0&pageSize=1 HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 3319

{
  "content" : [ {
    "projectId" : "1",
    "name" : "Project 1",
    "client" : {
      "clientId" : "1",
      "name" : "Client 1",
      "organizationId" : null,
      "vendorOrganization" : {
        "id" : "dotsub-test",
        "name" : "Dotsub Test",
        "timezone" : "America/New_York",
        "userRole" : null,
        "taskReassignmentTimeout" : 0,
        "webhook" : null,
        "webhookUsername" : null,
        "webhookPasswordEdit" : null
      },
      "clientOrganization" : null,
      "active" : true,
      "activationToken" : null
    },
    "tags" : [ {
      "tagId" : "1",
      "name" : "Medical",
      "color" : "7766927",
      "textColor" : "16777215",
      "workflow" : null,
      "colorHex" : "#76838F",
      "textColorHex" : "#FFFFFF"
    }, {
      "tagId" : "2",
      "name" : "Technical",
      "color" : "14043467",
      "textColor" : "16777215",
      "workflow" : null,
      "colorHex" : "#D6494B",
      "textColorHex" : "#FFFFFF"
    }, {
      "tagId" : "3",
      "name" : "Kaltura",
      "color" : "3507146",
      "textColor" : "16777215",
      "workflow" : null,
      "colorHex" : "#3583CA",
      "textColorHex" : "#FFFFFF"
    } ],
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "defaultWorkflowId" : "1",
    "defaultWorkflowName" : "Project 1",
    "copyDefaultWorkflow" : false,
    "priceSheetId" : "1",
    "translationLanguages" : [ {
      "id" : "it-IT",
      "code" : "ita",
      "countryCode" : "IT",
      "alpha2BCode" : "ita",
      "alpha2TCode" : "ita",
      "alpha1Code" : "it",
      "name" : "Italian",
      "direction" : "LTR"
    }, {
      "id" : "fr-FR",
      "code" : "fra",
      "countryCode" : "FR",
      "alpha2BCode" : "fre",
      "alpha2TCode" : "fra",
      "alpha1Code" : "fr",
      "name" : "French (France)",
      "direction" : "LTR"
    } ],
    "reviewLanguages" : [ {
      "id" : "en-US",
      "code" : "eng",
      "countryCode" : "US",
      "alpha2BCode" : "eng",
      "alpha2TCode" : "eng",
      "alpha1Code" : "en",
      "name" : "English (United States)",
      "direction" : "LTR"
    }, {
      "id" : "it-IT",
      "code" : "ita",
      "countryCode" : "IT",
      "alpha2BCode" : "ita",
      "alpha2TCode" : "ita",
      "alpha1Code" : "it",
      "name" : "Italian",
      "direction" : "LTR"
    }, {
      "id" : "fr-FR",
      "code" : "fra",
      "countryCode" : "FR",
      "alpha2BCode" : "fre",
      "alpha2TCode" : "fra",
      "alpha1Code" : "fr",
      "name" : "French (France)",
      "direction" : "LTR"
    } ],
    "fallbackMediaLanguage" : {
      "id" : "en-US",
      "code" : "eng",
      "countryCode" : "US",
      "alpha2BCode" : "eng",
      "alpha2TCode" : "eng",
      "alpha1Code" : "en",
      "name" : "English (United States)",
      "direction" : "LTR"
    }
  } ],
  "pageable" : {
    "sort" : {
      "unsorted" : false,
      "sorted" : true,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 1,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 12,
  "totalPages" : 12,
  "last" : false,
  "numberOfElements" : 1,
  "sort" : {
    "unsorted" : false,
    "sorted" : true,
    "empty" : false
  },
  "first" : true,
  "number" : 0,
  "size" : 1,
  "empty" : false
}
Path Type Description

content

Array

Array of found projects

content[].projectId

String

ID of the project

content[].name

String

Name of the project

content[].client

Object

The Client of the project

content[].tags

Array

List of Tags of the project

content[].organizationId

String

ID of the organization of the project

content[].defaultWorkflowId

String

ID of the default workflow for the project

content[].copyDefaultWorkflow

Boolean

Boolean to copy workflow on update requests. Does not apply to this API

content[].priceSheetId

String

Pricesheet ID of the project

content[].translationLanguages

Array

List of translation languages for the project. Media added to this project will be added with these translation languages by default.

content[].reviewLanguages

Array

List of review languages for the project. Media added to this project will be added with these review languages by default.

content[].fallbackMediaLanguage

Object

Fallback Media Language of the project. Media added to this project will be added with this language as media language if not already set.

totalElements

Number

Total number of projects in full result

totalPages

Number

Total number of pages in full result

first

Boolean

Is this the first page

last

Boolean

Is this the last page

size

Number

Number of projects per page

number

Number

Page number

numberOfElements

Number

Number of projects per page

sort

Object

Details of sort being applied

Workflow API

The Workflow API is used for reading lists of workflow.

Read Workflow List

A GET request will list workflows.

GET /api/v3/organizations/:organizationId/workflows
Table 7. /api/v3/organizations/{organizationId}/workflows
Parameter Description

organizationId

The ID of the organization owning workflows

Query Parameters

Parameter Description

pageSize

Required Results are returned in pages of data. The pageSize value will be the maximum number of workflows returned in a page.

pageIndex

Required Page index in paged set

name

Filter workflows by name

projectId

Filter workflows by Project ID

Example

Request

GET /api/v3/organizations/dotsub-test/workflows?pageIndex=0&pageSize=1 HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 755

{
  "content" : [ {
    "id" : "1",
    "createdDate" : "2017-03-22T12:00:00Z",
    "modifiedDate" : "2017-03-22T16:00:00Z",
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "latestVersion" : "0",
    "workflowName" : "Project 1",
    "projectToAddInto" : null
  } ],
  "pageable" : {
    "sort" : {
      "unsorted" : false,
      "sorted" : true,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 1,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 4,
  "totalPages" : 4,
  "last" : false,
  "numberOfElements" : 1,
  "sort" : {
    "unsorted" : false,
    "sorted" : true,
    "empty" : false
  },
  "first" : true,
  "number" : 0,
  "size" : 1,
  "empty" : false
}
Path Type Description

content

Array

Array of found workflows

content[].id

String

ID of the workflow

content[].workflowName

String

Name of the workflow

content[].createdDate

String

The timestamp the workflow was created

content[].modifiedDate

String

The timestamp the workflow was last modified

content[].organizationId

String

ID of the organization for the workflow

content[].organizationName

String

Name of the organization for the workflow

content[].latestVersion

String

Latest version of the workflow

content[].projectToAddInto

Null

ID of project to add workflow. Does not apply to this API

totalElements

Number

Total number of workflows in full result

totalPages

Number

Total number of pages in full result

first

Boolean

Is this the first page

last

Boolean

Is this the last page

size

Number

Number of workflows per page

number

Number

Page number

numberOfElements

Number

Number of workflows per page

sort

Object

Details of sort being applied

Organization Languages API

An API is used for reading languages in a given organization

A GET request will list the organization’s languages.

GET /api/v3/organizations/:organizationId/languages
Table 8. /api/v3/organizations/{organizationId}/languages
Parameter Description

organizationId

Required Id of the organization contains language list.

Example

Request

GET /api/v3/organizations/dotsub-test/languages HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: SAMEORIGIN
Content-Length: 940

[ {
  "id" : "en-US",
  "code" : "eng",
  "countryCode" : "US",
  "alpha2BCode" : "eng",
  "alpha2TCode" : "eng",
  "alpha1Code" : "en",
  "name" : "English (United States)",
  "direction" : "LTR"
}, {
  "id" : "fr-FR",
  "code" : "fra",
  "countryCode" : "FR",
  "alpha2BCode" : "fre",
  "alpha2TCode" : "fra",
  "alpha1Code" : "fr",
  "name" : "French (France)",
  "direction" : "LTR"
}, {
  "id" : "it-IT",
  "code" : "ita",
  "countryCode" : "IT",
  "alpha2BCode" : "ita",
  "alpha2TCode" : "ita",
  "alpha1Code" : "it",
  "name" : "Italian",
  "direction" : "LTR"
}, {
  "id" : "sk",
  "code" : "slk",
  "countryCode" : null,
  "alpha2BCode" : "slk",
  "alpha2TCode" : "slk",
  "alpha1Code" : "sk",
  "name" : "Slovak",
  "direction" : "LTR"
}, {
  "id" : "es-ES",
  "code" : "spa",
  "countryCode" : "ES",
  "alpha2BCode" : "spa",
  "alpha2TCode" : "spa",
  "alpha1Code" : "es",
  "name" : "Spanish (Spain)",
  "direction" : "LTR"
} ]
Path Type Description

[]

Array

Array of found languages in organization.

[].id

String

Language id in BCP47 representative e.g 'en-US'

[].name

String

Language name with country name appended e.g 'English (United States)'

[].code

String

ISO 639-3 Code (3 letters e.g 'eng')

[].countryCode

String

ISO-3166-1 alpha-2

[].alpha2BCode

String

ISO 639-2 Bibliographic Synonym

[].alpha2TCode

String

ISO 639-2 Bibliographic Synonym

[].alpha1Code

String

ISO 639-1 (2 letters e.g 'en')

[].direction

String

Language direction can be 'RTL' or 'LTR'