Overview

This describes the resources that make up the official Dotsub REST API VideoTMSTM. 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.

In order to obtain a JWT token, you must first have client_id and client_secret credentials. Follow these steps to generate the credentials:

1- Open https://videotms.com, and login with an Admin user account.

2- From the left menu, navigate to Organization > Advanced Settings.

3- Click the "Create Api Credentials" button to generate the credentials.

You will then see the client_id and client_secret values as follows: client creds after creation screenshot Note: You can click the eye icon to show the client_secret value.

Please be careful not to share your credentials with untrusted parties

To retrieve the JWT token, use this request:

$ curl 'https://login.videotms.com/oauth/token' -i -X POST \
    -H 'Content-Type: application/json; charset=UTF-8' \
    -d '{
  "client_id" : "OOb7go1K6036e3fMPgLo5dzPWlqHDYHR",
  "client_secret" : "s7rL1R62kKtsXzhXOjaiQ6fuMjWeygpXkbMDuGiFnRR4SHR7cbakYxBMeX8dMW4-",
  "audience" : "https://videotms.com/api/v3/",
  "grant_type" : "client_credentials"
}'
Path Type Description

client_id

String

Client ID

client_secret

String

Client Secret

audience

String

Dotsub’s API URI. Trailing slash is important!

grant_type

String

What grant type should issuer create token for

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

HTTP/1.1 200 OK

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik9URTVPVGc1T1RnMFFUSXhOVEJEUlRCRlJqSTVOelEwT0VZNFJrRTFSRFkzTnpNek1VSkdRdyJ9.eyJpc3MiOiJodHRwczovL2xvZ2luLnZpZGVvdG1zLmNvbS8iLCJzdWIiOiJPT2I3Z28xSzYwMzZlM2ZNUGdMbzVkelBXbHFIRFlIUkBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9kb2VzLm5vdC5leGlzdC50ZXN0L2FwaS92My8iLCJpYXQiOjE2MDc2ODAyMzAsImV4cCI6MTYwNzc2NjYzMCwiYXpwIjoiT09iN2dvMUs2MDM2ZTNmTVBnTG81ZHpQV2xxSERZSFIiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.Y1HaYEwi1bmexhvpdV4CwN4qlJedAULKjDC-IIXVM_o3rzALSEePj4beqnJNIfx0bIRbGs1EbPd8d1uFqffZPCOYlzY-yxK1woMjVYnB4t0BA0w_QkrBOfWV2D1nJ-WvoYP57NTTadbs1CkZTCX_qpF6t16C6vr8a0NTwIGchzx1IQgDF6bGSSUkyBQaD95rhiJAOzZNhydc4ExuEf_rFhiXDph6uTxhYuZE8qcGZUL7jOSyv0l8tA0KI8e6oBSkHgzHtcXBwZIV2GI254ROJMkqXFnGycXYB7Z5o871iv4gAQPA-76tx-1ge01gkUyQrnZqvhgOkPw3Qn48298GhA",
  "expires_in" : 86400,
  "token_type" : "Bearer"
}

Token constructed from response can be used as header in any request that needs to be authorized:

GET /api/v3/tasks HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik9URTVPVGc1T1RnMFFUSXhOVEJEUlRCRlJqSTVOelEwT0VZNFJrRTFSRFkzTnpNek1VSkdRdyJ9.eyJpc3MiOiJodHRwczovL2xvZ2luLnZpZGVvdG1zLmNvbS8iLCJzdWIiOiJ0SkZmVEZxZmJQcmo5M2oxMjFWbmN1bXVWWmdxVDZkMUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6ODA4MC9hcGkvdjMvIiwiaWF0IjoxNjA3NjgwMjI3LCJleHAiOjE2MDc3NjY2MjcsImF6cCI6InRKRmZURnFmYlByajkzajEyMVZuY3VtdVZaZ3FUNmQxIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.I6vpN0fMsQVobhbH8_huPM5_UiNYk0Ook8PTdOUN_yG91g0XOeAAlzrjyiY3uIQBKDZdiLDRAazWnBpe9ai1YFUmrWcp4bu_0-72XCm2biV0hU33JiCc0ITLeIx2ckeVlEZ2yqBcwbvZPTmjW9wBUvtAeE0Z5StWU9Aw4mtScGEtrPdmmAfUOkv5PSx520ieDVSb2d4ni6JDRF-ENiLq6Ex6bBz63SRahmBYcErNPWYqbV5hkf6ADLf9yPIXT01MHWENXsdDu3zYaDqQNOFJSyrgEqTHKBFl9RtUKAsMlSfWs26FiEmEteMWJgGgoa6ED4M2eByIpDNXOekxPs2YuA

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

PATCH

Used to partially update an existing entity using JSON Merge Patch

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: 171

{
  "timestamp" : "2021-06-02T08:26:59Z",
  "status" : 404,
  "error" : "Not Found",
  "message" : "Media with ID foobar wasn't found",
  "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" : "2021-06-02T08:26:59Z",
  "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

language

Filter by media’s language name case insensitive, e.g (english)

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: 4803

{
  "content" : [ {
    "mediaId" : "27",
    "title" : "Video Title 23",
    "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" : "2020-11-23T08:15:00Z",
    "workflowId" : null,
    "workflowTemplateOutdated" : null,
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "externalId" : null,
    "fileName" : "VIDEO-FOO-23.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" : "24",
      "start" : "2020-11-23T07:15:00Z",
      "finish" : null,
      "origin" : "DISK",
      "status" : "COMPLETE",
      "percentage" : 100,
      "errorMessage" : null,
      "rawFileStorageUrl" : null,
      "ovp" : null,
      "uploadUpdateToken" : null
    },
    "encodedMedia" : {
      "id" : "24",
      "mp4Url" : "http://dotsub-media-encoded.s3.amazonaws.com/media/4/7/video.mp4",
      "rawS3Mp4Url" : null,
      "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" : 8000,
      "width" : null,
      "height" : null,
      "visible" : false,
      "uploaderUserId" : "21",
      "signedUrl" : null
    },
    "replacedImportedUrl" : null,
    "chunkParentMediaId" : null,
    "chunkIndex" : null,
    "chunkStart" : null,
    "chunkEnd" : null,
    "mediaChunkIds" : null
  }, {
    "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,
    "chunkParentMediaId" : null,
    "chunkIndex" : null,
    "chunkStart" : null,
    "chunkEnd" : null,
    "mediaChunkIds" : null
  } ],
  "pageable" : {
    "sort" : {
      "unsorted" : false,
      "sorted" : true,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 2,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 16,
  "totalPages" : 8,
  "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: 2763

{
  "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,
  "chunkParentMediaId" : null,
  "chunkIndex" : null,
  "chunkStart" : null,
  "chunkEnd" : null,
  "mediaChunkIds" : [ ]
}
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.

  • Subtitle download supports these formats:

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 values are: [VTT, SRT, TTML, 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/vtt;charset=UTF-8
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: 121

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

1
00:00:01.000 --> 00:00:03.000 align:center
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.

  • Subtitle upload supports these formats:

  • Import engine detects subtitle format automatically, so there is not need to explicitly specify it.

  • 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: 1941

{
  "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" : "5415067e-0268-4521-b340-7e04258e3e26",
    "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",
      "invitationId" : null,
      "unreadNotifications" : 0,
      "selectedAssigneeUser" : null,
      "assigneeUsers" : null
    },
    "createdAt" : "2021-06-02T08:27:01.45253Z",
    "finalized" : true,
    "lockingVersion" : 0,
    "overlapEnabled" : false
  },
  "versions" : [ {
    "trackVersionId" : "5415067e-0268-4521-b340-7e04258e3e26",
    "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",
      "invitationId" : null,
      "unreadNotifications" : 0,
      "selectedAssigneeUser" : null,
      "assigneeUsers" : null
    },
    "createdAt" : "2021-06-02T08:27:01.45253Z",
    "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 translation language IDs of the media. In order for the media to be translated into a language, the ID of the language must be in this array. This also assumes the media is being processed by a workflow that has a Translation task in the workflow definition.

mediaDto.reviewLanguages[].id

String

The review language IDs with the media. The Caption and Translations for a media can be Reviewed after completion. In order for the review task to be created, the Language ID of Caption or Translation must be in this array. This also assumes the media is being processed by a workflow that has a Review task in the workflow definition.

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: 3101

{
  "mediaId" : "3280c39d-0256-4524-87f9-6275b4c56a34",
  "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" : "2021-06-02T08:27:00.665091Z",
  "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" : "499fca1a-2c3d-4505-a5ec-1b8702a91884",
    "start" : "2021-06-02T08:27:00.623956Z",
    "finish" : null,
    "origin" : "DISK",
    "status" : "IN_QUEUE",
    "percentage" : 0,
    "errorMessage" : null,
    "rawFileStorageUrl" : null,
    "ovp" : null,
    "uploadUpdateToken" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIzMjgwYzM5ZC0wMjU2LTQ1MjQtODdmOS02Mjc1YjRjNTZhMzQifQ.ks3mmN9WvcgsQLG5xRLsGBBKPZrWJhB-Zvy5_4mhQ4XGYxtU1yIKZdTuP8JIcchsR7CuxXov59Et93mL77wXeg"
  },
  "encodedMedia" : {
    "id" : "ed7ece44-110e-42fc-9beb-6f4633b0af5b",
    "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,
  "chunkParentMediaId" : null,
  "chunkIndex" : null,
  "chunkStart" : null,
  "chunkEnd" : null,
  "mediaChunkIds" : null
}

Update Media

A PATCH request will partially update the organization’s media. This is a JSON Merge Patch.

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)

replacedImportedUrl

String

Replaces media’s video with the video located at the replacedImportedUrl.

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. In order for the media to be translated into a language, the ID of the language must be in this array. This also assumes the media is being processed by a workflow that has a Translation task in the workflow definition.

reviewLanguages[].id

String

The review language IDs with the media. The Caption and Translations for a media can be Reviewed after completion. In order for the review task to be created, the Language ID of Caption or Translation must be in this array. This also assumes the media is being processed by a workflow that has a Review task in the workflow definition.

encodedMedia.reprocessWith

String

Re-encode the media with either the primary or secondary encoding service. Please use the primary encoding service unless it is failing for some reason. Valid values are primary and secondary.

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: 3151

{
  "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,
  "chunkParentMediaId" : null,
  "chunkIndex" : null,
  "chunkStart" : null,
  "chunkEnd" : null,
  "mediaChunkIds" : 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, MT, 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: 4607

{
  "content" : [ {
    "id" : "12",
    "assigneeId" : "8",
    "assigneeType" : "USER",
    "assigneeName" : "Translator, Jimmy",
    "assigneeEmail" : "[email protected]",
    "assigneeTags" : null,
    "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",
    "mediaTitle" : "Video Title 11",
    "mediaDescription" : "This is the description",
    "mediaFilename" : "VIDEO-FOO-11.MOV",
    "mediaChunkIndex" : null,
    "mediaId" : "12",
    "mediaExternalId" : null,
    "mediaState" : null,
    "mediaDeletedDate" : null,
    "relatedTrackType" : "TRANSLATION",
    "trackId" : "12",
    "trackCurrentVersionId" : "18",
    "trackCompletionPercentage" : "100",
    "sourceTrackLanguageId" : "en-US",
    "sourceTrackLanguageName" : "English (United States)",
    "sourceTrackCurrentVersionId" : "16",
    "sourceTrackSourceTrackId" : null,
    "languageId" : "fr-FR",
    "languageName" : "French (France)",
    "description" : null,
    "sourceTrackId" : "11",
    "trackReviewId" : 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" : [ {
      "tagId" : "7",
      "name" : "Tag One",
      "color" : "10407527",
      "textColor" : "16777215",
      "workflow" : null,
      "colorHex" : "#9ECE67",
      "textColorHex" : "#FFFFFF"
    } ],
    "mediaTags" : [ ],
    "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,
    "finalChunkReview" : false
  }, {
    "id" : "11",
    "assigneeId" : "8",
    "assigneeType" : "USER",
    "assigneeName" : "Translator, Jimmy",
    "assigneeEmail" : "[email protected]",
    "assigneeTags" : null,
    "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",
    "mediaTitle" : "Video Title 11",
    "mediaDescription" : "This is the description",
    "mediaFilename" : "VIDEO-FOO-11.MOV",
    "mediaChunkIndex" : null,
    "mediaId" : "12",
    "mediaExternalId" : null,
    "mediaState" : null,
    "mediaDeletedDate" : null,
    "relatedTrackType" : "CAPTION",
    "trackId" : "11",
    "trackCurrentVersionId" : "16",
    "trackCompletionPercentage" : "100",
    "sourceTrackLanguageId" : "en-US",
    "sourceTrackLanguageName" : "English (United States)",
    "sourceTrackCurrentVersionId" : null,
    "sourceTrackSourceTrackId" : null,
    "languageId" : "en-US",
    "languageName" : "English (United States)",
    "description" : null,
    "sourceTrackId" : null,
    "trackReviewId" : 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" : [ ],
    "mediaTags" : [ ],
    "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,
    "finalChunkReview" : false
  } ],
  "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 partially update certain properties of a task. This is a JSON Merge Patch.

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: 2197

{
  "id" : "4",
  "assigneeId" : "8",
  "assigneeType" : "USER",
  "assigneeName" : "Translator, Jimmy",
  "assigneeEmail" : "[email protected]",
  "assigneeTags" : null,
  "createdDate" : "2016-08-01T12:04:00Z",
  "dueDate" : "2016-09-01T12:04:00Z",
  "projectId" : "1",
  "projectName" : "Project 1",
  "completed" : true,
  "completionDate" : "2021-06-02T08:26:56.947949Z",
  "accepted" : true,
  "type" : "TASK_CAPTION",
  "mediaTitle" : "Video Title 1",
  "mediaDescription" : "This is the description",
  "mediaFilename" : "VIDEO-FOO.MOV",
  "mediaChunkIndex" : null,
  "mediaId" : "1",
  "mediaExternalId" : null,
  "mediaState" : null,
  "mediaDeletedDate" : null,
  "relatedTrackType" : "CAPTION",
  "trackId" : "4",
  "trackCurrentVersionId" : "5",
  "trackCompletionPercentage" : "0",
  "sourceTrackLanguageId" : "en-US",
  "sourceTrackLanguageName" : "English (United States)",
  "sourceTrackCurrentVersionId" : null,
  "sourceTrackSourceTrackId" : null,
  "languageId" : "es-ES",
  "languageName" : "Spanish (Spain)",
  "description" : null,
  "sourceTrackId" : null,
  "trackReviewId" : 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" : [ ],
  "mediaTags" : [ {
    "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,
  "finalChunkReview" : false
}
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

String

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

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.

SHARED_NOT_FINISHED_BY_VENDOR

A task shared to a vendor organization was completed by the client organization.

SHARED_REASSIGNED_REMOVED_VENDOR

A task shared to a vendor organization was reassigned from the vendor by the client organization.

TASK_DUE_DATE_CHANGED_ADMINS

A task due date has been changed. Notification sent to the task’s organization Admins.

TASK_DUE_DATE_CHANGED_ASSIGNEES

A task due date has been changed. Notification sent to the task’s assignee (Group or Linguist).

TASK_DELETED_ADMINS

A task has been deleted. Notification sent to the task’s organization Admins.

TASK_DELETED_ASSIGNEES

A task has been deleted. Notification sent to the task’s assignee (Group or Linguist).

LINGUIST_SIGNUP

A new linguist has completed registration in the organization.

TASK_ALMOST_DUE_MANAGERS

A task is not complete and has been open for more than half the due date. Notification sent to the task’s organization Admins.

TASK_ALMOST_DUE_ASSIGNEE

A task is not complete and has been open for more than half the due date. Notification sent to the task’s assignee (Group or Linguist).

TASK_PAST_DUE_MANAGERS

A task is not complete and has passed the due date. Notification sent to the task’s organization Admins.

TASK_PAST_DUE_ASSIGNEE

A task is not complete and has passed the due date. Notification sent to the task’s assignee (Group or Linguist).

TASK_ASSIGNMENT_FAILED
  • None of the configured Automated Speech Recognition/ Machine Translation engines support given skill (captioning language or translation language pair)

  • Human assignee group was not found for skill (captioning language or translation language pair)

TASK_PROCESSING_FAILED

Asynchronous automated task failed. Affected task types:

  • ASR captioning

  • Machine Translation

  • Push

  • Burn-In

MEDIA_ENCODING_FAILED

A media has failed encoding after being added to VideoTMS.

MEDIA_WORKFLOW_FAILED

Workflow processing for media 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",
  "mediaExternalId": "vKdatbDc",
  "mediaTags": [
    "tag1",
    "tag2"
  ],
  "errorDetail": "Detailed information in case of error notifications"
}

Project API

The Project API is used for reading/writing 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

name

Filter by project name

workflowId

Filter by workflow Id associated with project

workflowName

Filter by workflow name associated with project

tagName

Filter by tag associated with project

sort

Sort the paged project set. The result set may be sorted by name and client name. Default sort direction is Ascending. To sort Descending, prepend - to sort value. Default sort is by name descending.

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: 3378

{
  "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,
        "lineFeed" : "LF"
      },
      "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"
    },
    "mediaChunkSeconds" : null
  } ],
  "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

Create Project

A POST request will create a project in the user’s organization.

POST /api/v3/projects

Input

Path Type Description

name

String

Required Name of project

organizationId

String

Required ID of the Organization owning the project

fallbackMediaLanguage.id

String

Required ID of the Language to use as fallback for media in the project

defaultWorkflowId

String

ID of the Default Workflow for the project

client.clientId

String

ID of the Client for the project

priceSheetId

String

ID of the PriceSheet for the project

tags[].name

String

The tag names associated with the project

translationLanguages[].id

String

The translation language IDs of the project

reviewLanguages[].id

String

The review language IDs with the project

Example

Request

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

{
  "name": "Project New One",
  "organizationId": "dotsub-test",
  "defaultWorkflowId": "5",
  "tags": [ { "name": "Medical" } ],
  "translationLanguages": [
    {
      "id": "it-IT"
    }
  ],
  "reviewLanguages": [
    {
      "id": "it-IT"
    },
    {
      "id": "en-US"
    }
  ],
  "fallbackMediaLanguage": {
      "id": "en-US"
  }
}

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: 1457

{
  "projectId" : "7df9fe17-6b55-429f-998d-60638bbc51a0",
  "name" : "Project New One",
  "client" : null,
  "tags" : [ {
    "tagId" : "1",
    "name" : "Medical",
    "color" : "7766927",
    "textColor" : "16777215",
    "workflow" : null,
    "colorHex" : "#76838F",
    "textColorHex" : "#FFFFFF"
  } ],
  "organizationId" : "dotsub-test",
  "organizationName" : "Dotsub Test",
  "defaultWorkflowId" : "5",
  "defaultWorkflowName" : "Workflow 5",
  "copyDefaultWorkflow" : false,
  "priceSheetId" : null,
  "translationLanguages" : [ {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  } ],
  "reviewLanguages" : [ {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  }, {
    "id" : "en-US",
    "code" : "eng",
    "countryCode" : "US",
    "alpha2BCode" : "eng",
    "alpha2TCode" : "eng",
    "alpha1Code" : "en",
    "name" : "English (United States)",
    "direction" : "LTR"
  } ],
  "fallbackMediaLanguage" : {
    "id" : "en-US",
    "code" : "eng",
    "countryCode" : "US",
    "alpha2BCode" : "eng",
    "alpha2TCode" : "eng",
    "alpha1Code" : "en",
    "name" : "English (United States)",
    "direction" : "LTR"
  },
  "mediaChunkSeconds" : null
}

Update Project

A PATCH request will partially update the organization’s project. This is a JSON Merge Patch.

PATCH /api/v3/projects/:projectId
Table 7. /api/v3/projects/{projectId}
Parameter Description

projectId

The ID of the project to update

Input

The following fields may be updated:

Path Type Description

name

String

Required Name of project

fallbackMediaLanguage.id

String

Required ID of the Language to use as fallback for media in the project

defaultWorkflowId

String

ID of the Default Workflow for the project

client.clientId

String

ID of the Client for the project

priceSheetId

String

ID of the PriceSheet for the project

tags[].name

String

The tag names associated with the project

translationLanguages[].id

String

The translation language IDs of the project. Array of Objects with language id attribute.

reviewLanguages[].id

String

The review language IDs with the projectArray of Objects with language id attribute.

Example

Request

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

{
  "name": "Project 10-new",
  "tags": [ { "name": "Medical" } ],
  "fallbackMediaLanguage": {
      "id": "it-IT"
  }
}

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: 1253

{
  "projectId" : "12",
  "name" : "Project 10-new",
  "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,
      "lineFeed" : "LF"
    },
    "clientOrganization" : null,
    "active" : true,
    "activationToken" : null
  },
  "tags" : [ {
    "tagId" : "1",
    "name" : "Medical",
    "color" : "7766927",
    "textColor" : "16777215",
    "workflow" : null,
    "colorHex" : "#76838F",
    "textColorHex" : "#FFFFFF"
  } ],
  "organizationId" : "dotsub-test",
  "organizationName" : "Dotsub Test",
  "defaultWorkflowId" : null,
  "defaultWorkflowName" : null,
  "copyDefaultWorkflow" : false,
  "priceSheetId" : null,
  "translationLanguages" : [ ],
  "reviewLanguages" : [ ],
  "fallbackMediaLanguage" : {
    "id" : "it-IT",
    "code" : "ita",
    "countryCode" : "IT",
    "alpha2BCode" : "ita",
    "alpha2TCode" : "ita",
    "alpha1Code" : "it",
    "name" : "Italian",
    "direction" : "LTR"
  },
  "mediaChunkSeconds" : 4
}

Subtitle Specification API

The Subtitle Specification API is used for reading/writing subtitle specification associated with projects and media.

Read Subtitle Specification For Project

A GET request will return the subtitle specification for a project.

GET /api/v3/projects/:projectId/subtitleSpecification
Table 8. /api/v3/projects/{projectId}/subtitleSpecification
Parameter Description

projectId

The ID of the project associated with the Subtitle Specification

Example

Request

GET /api/v3/projects/1/subtitleSpecification 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: 421

{
  "subtitleSpecificationId" : "1",
  "projectId" : "1",
  "enabled" : true,
  "spokenAudio" : true,
  "audioDescription" : true,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "comments" : "comment",
  "mediaNotes" : null
}
Path Type Description

subtitleSpecificationId

String

ID of the Subtitle Specification

projectId

String

ID of the project associated with the Subtitle Specification

enabled

Boolean

If true, the subtitle spec will be enforced when captioning/subtitling

spokenAudio

Boolean

If true, include Spoken Audio

audioDescription

Boolean

If true, include Audio Descriptions

onScreenText

Boolean

If true, include On-Screen text in video in captioning/subtitling

speakerIdentification

String

Speaker identification method to use for captioning/subtitling. Valid values are FIRST_NAME, FULLNAME, NUMBERED, GENDER, GENRE, SEE_COMMENTS, NONE.

dialogueStyle

String

Dialogue style to use for captioning/subtitling. Valid values are LINE_BREAKS, DOUBLE_CHEVRON, NO_DASHES, SEE_COMMENTS.

maxLinesPerCaption

Number

The maximum line count allowed in a caption/subtitle

maxCharactersPerLine

Number

The maximum character count allowed in a caption/subtitle line

minCaptionDurationInMillis

Number

The minimum duration a caption/subtitle is allowed to be (in milliseconds)

maxCaptionDurationInMillis

Number

The maximum duration a caption/subtitle is allowed to be (in milliseconds)

comments

String

General comments for spec (Markdown is supported)

mediaNotes

String

Media notes, not applicable for this API

Read Subtitle Specification For Project’s Media

A GET request will return the subtitle specification for a media in a project.

GET /api/v3/projects/:projectId/subtitleSpecification/media/:mediaId
Table 9. /api/v3/projects/{projectId}/subtitleSpecification/media/{mediaId}
Parameter Description

projectId

The ID of the project associated with the Subtitle Specification

mediaId

The ID of the media associated with the Subtitle Specification

Example

Request

GET /api/v3/projects/1/subtitleSpecification/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: 492

{
  "subtitleSpecificationId" : "1",
  "projectId" : "1",
  "enabled" : true,
  "spokenAudio" : true,
  "audioDescription" : true,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "comments" : "comment",
  "mediaNotes" : "Media contains unique terminology.  \r[Test link](https://www.dotsub.com)"
}
Path Type Description

subtitleSpecificationId

String

ID of the Subtitle Specification

projectId

String

ID of the project associated with the Subtitle Specification

enabled

Boolean

If true, the subtitle spec will be enforced when captioning/subtitling

spokenAudio

Boolean

If true, include Spoken Audio

audioDescription

Boolean

If true, include Audio Descriptions

onScreenText

Boolean

If true, include On-Screen text in video in captioning/subtitling

speakerIdentification

String

Speaker identification method to use for captioning/subtitling. Valid values are FIRST_NAME, FULLNAME, NUMBERED, GENDER, GENRE, SEE_COMMENTS, NONE.

dialogueStyle

String

Dialogue style to use for captioning/subtitling. Valid values are LINE_BREAKS, DOUBLE_CHEVRON, NO_DASHES, SEE_COMMENTS.

maxLinesPerCaption

Number

The maximum line count allowed in a caption/subtitle

maxCharactersPerLine

Number

The maximum character count allowed in a caption/subtitle line

minCaptionDurationInMillis

Number

The minimum duration a caption/subtitle is allowed to be (in milliseconds)

maxCaptionDurationInMillis

Number

The maximum duration a caption/subtitle is allowed to be (in milliseconds)

comments

String

General comments for spec (Markdown is supported)

mediaNotes

String

Media notes (Markdown supported)

Create Subtitle Specification

A POST request will create a Subtitle Specification for a Project.

POST /api/v3/projects/:projectId:/subtitleSpecification
Table 10. /api/v3/projects/{projectId}/subtitleSpecification
Parameter Description

projectId

The ID of the project associated with the Subtitle Specification

Input

Path Type Description

enabled

Boolean

If true, the subtitle spec will be enforced when captioning/subtitling

spokenAudio

Boolean

If true, include Spoken Audio

audioDescription

Boolean

If true, include Audio Descriptions

onScreenText

Boolean

If true, include On-Screen text in video in captioning/subtitling

speakerIdentification

String

Speaker identification method to use for captioning/subtitling. Valid values are FIRST_NAME, FULLNAME, NUMBERED, GENDER, GENRE, SEE_COMMENTS, NONE.

dialogueStyle

String

Dialogue style to use for captioning/subtitling. Valid values are LINE_BREAKS, DOUBLE_CHEVRON, NO_DASHES, SEE_COMMENTS.

maxLinesPerCaption

Number

The maximum line count allowed in a caption/subtitle. Valid range is 1-4.

maxCharactersPerLine

Number

The maximum character count allowed in a caption/subtitle line. Valid range is 30-80.

minCaptionDurationInMillis

Number

The minimum duration a caption/subtitle is allowed to be (in milliseconds). Value needs to be less than maxCaptionDurationInMillis. Valid range is 1000-4000.

maxCaptionDurationInMillis

Number

The maximum duration a caption/subtitle is allowed to be (in milliseconds). Valid range is 2000-10000.

comments

String

General comments for spec (Markdown is supported)

Example

Request

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

{
  "enabled": true,
  "onScreenText": true,
  "spokenAudio": false,
  "audioDescription": false,
  "speakerIdentification": "FULLNAME",
  "dialogueStyle": "DOUBLE_CHEVRON",
  "comments": "**test comments**",
  "maxLinesPerCaption":2,
  "maxCharactersPerLine":35,
  "minCaptionDurationInMillis":2000,
  "maxCaptionDurationInMillis":10000
}

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: 469

{
  "subtitleSpecificationId" : "1851ac06-be1a-4149-b28a-6230f3e81b6d",
  "projectId" : "13",
  "enabled" : true,
  "spokenAudio" : false,
  "audioDescription" : false,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "comments" : "**test comments**",
  "mediaNotes" : null
}

Update Subtitle Specification

A PATCH request will update a Subtitle Specification for a Project. This is a JSON Merge Patch.

PATCH /api/v3/projects/:projectId:/subtitleSpecification
Table 11. /api/v3/projects/{projectId}/subtitleSpecification
Parameter Description

projectId

The ID of the project associated with the Subtitle Specification

Input

Path Type Description

enabled

Boolean

If true, the subtitle spec will be enforced when captioning/subtitling

spokenAudio

Boolean

If true, include Spoken Audio

audioDescription

Boolean

If true, include Audio Descriptions

onScreenText

Boolean

If true, include On-Screen text in video in captioning/subtitling

speakerIdentification

String

Speaker identification method to use for captioning/subtitling. Valid values are FIRST_NAME, FULLNAME, NUMBERED, GENDER, GENRE, SEE_COMMENTS, NONE.

dialogueStyle

String

Dialogue style to use for captioning/subtitling. Valid values are LINE_BREAKS, DOUBLE_CHEVRON, NO_DASHES, SEE_COMMENTS.

maxLinesPerCaption

Number

The maximum line count allowed in a caption/subtitle. Valid range is 1-4.

maxCharactersPerLine

Number

The maximum character count allowed in a caption/subtitle line. Valid range is 30-80.

minCaptionDurationInMillis

Number

The minimum duration a caption/subtitle is allowed to be (in milliseconds). Value needs to be less than maxCaptionDurationInMillis. Valid range is 1000-4000.

maxCaptionDurationInMillis

Number

The maximum duration a caption/subtitle is allowed to be (in milliseconds). Valid range is 2000-10000.

comments

String

General comments for spec (Markdown is supported)

Example

Request

PATCH /api/v3/projects/1/subtitleSpecification HTTP/1.1
Content-Type: application/json;charset=UTF-8

{
  "comments": "updated comments test"
}

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: 435

{
  "subtitleSpecificationId" : "1",
  "projectId" : "1",
  "enabled" : true,
  "spokenAudio" : true,
  "audioDescription" : true,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "comments" : "updated comments test",
  "mediaNotes" : null
}

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 12. /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: 795

{
  "content" : [ {
    "id" : "1",
    "createdDate" : "2017-03-22T12:00:00Z",
    "modifiedDate" : "2017-03-22T16:00:00Z",
    "organizationId" : "dotsub-test",
    "organizationName" : "Dotsub Test",
    "latestVersion" : "0",
    "useDefaultTaskAssignments" : true,
    "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

Project Glossaries API

The Project Glossaries API is used for reading, creating, updating, and deleting glossaries.

Read Project Glossaries List

A GET request will list project glossaries.

GET /api/v3/projects/{projectId}/glossaries

Query Parameters

Parameter Description

pageSize

Results are returned in pages of data. Default 50.

pageIndex

Page index in paged set Default 0

sort

Sort the paged glossary set. The result set may be sorted by createdDate, name. Default sort direction is Descending. To sort Ascending, prepend + to sort value. Default -createdDate

name

Filter by glossary name case insensitive

Example

Request

GET /api/v3/projects/1/glossaries?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: 811

{
  "content" : [ {
    "id" : "8",
    "name" : "Sample Glossary 5 for Project 1",
    "createdDate" : "2020-12-08T11:59:00Z",
    "createdBy" : {
      "id" : "5",
      "name" : "Dotsub Admin Admin",
      "email" : "[email protected]",
      "timezone" : "America/Los_Angeles"
    },
    "csvUpdatedDate" : null,
    "projectDefault" : false
  } ],
  "pageable" : {
    "sort" : {
      "unsorted" : false,
      "sorted" : true,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 1,
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "totalElements" : 6,
  "totalPages" : 6,
  "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 project glossaries

content[].id

String

ID of the glossary

content[].name

String

Name of the glossary

content[].createdDate

String

Created Date of the glossary in ISO8601 format

content[].csvUpdatedDate

Null

Date of the last glossary csv update in ISO8601 format

content[].projectDefault

Boolean

Boolean indicates whether the glossary is a project default or not

content[].createdBy

Object

Glossary creator user info

content[].createdBy.id

String

Glossary creator user ID

content[].createdBy.name

String

Glossary creator user full name

content[].createdBy.email

String

Glossary creator email

content[].createdBy.timezone

String

Glossary creator timezone

totalElements

Number

Total number of project glossaries 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 project glossaries per page

number

Number

Page number

numberOfElements

Number

Number of project glossaries per page

sort

Object

Details of sort being applied

Read Project Glossary

A GET request will return a specific glossary.

GET /api/v3/projects/{projectId}/glossaries/{glossaryId}
Table 13. /api/v3/projects/{projectId}/glossaries/{glossaryId}
Parameter Description

projectId

The ID of the project associated with glossary

glossaryId

The ID of the glossary

Example

Request

GET /api/v3/projects/13/glossaries/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: 327

{
  "id" : "1",
  "name" : "Sample Glossary for Project 11",
  "createdDate" : "2020-12-01T11:59:00Z",
  "createdBy" : {
    "id" : "5",
    "name" : "Dotsub Admin Admin",
    "email" : "[email protected]",
    "timezone" : "America/Los_Angeles"
  },
  "csvUpdatedDate" : "2020-12-01T14:00:00Z",
  "projectDefault" : true
}
Path Type Description

id

String

ID of the glossary

name

String

Name of the glossary

createdDate

String

Date of the glossary creation in ISO8601 format

csvUpdatedDate

String

Date of the last glossary csv update in ISO8601 format

projectDefault

Boolean

Boolean indicates whether the glossary is a project default or not

createdBy

Object

Glossary creator user info

createdBy.id

String

Glossary creator user ID

createdBy.name

String

Glossary creator user full name

createdBy.email

String

Glossary creator email

createdBy.timezone

String

Glossary creator timezone

Create Project Glossary

A POST request will create project glossary.

POST /api/v3/project/{projectId}/glossaries

Input

Part Description

glossaryFile

Required A multipart CSV file represents the glossary content, File must be matching the following rules Glossary file must be a CSV file, here is an example http://videotms.com/misc/sample-glossary.csv to get you started. Please make sure your CSV file is using comma or semi-colon as delimiter. The first row of the CSV should list all the language codes included in the glossary. Language codes are composed by the ISO 693-1 code (2 letters), dash, and the ISO 3166 country code (2 letters, uppercase). For example: en-US, ja-JP or pt-BR. The glossary must contain at least two languages (columns). Only languages enabled on your organization’s settings are allowed. Blank glossary entries are allowed, if there are no translations available for the given language.

glossaryPayload

Required A multipart json represents the metadata required to create the glossary

Path Type Description

glossaryPayload

Object

Glossary payload that contains information about glossary

glossaryPayload.name

String

Required String to set the glossary name

glossaryPayload.projectDefault

Boolean

Boolean to set whether the glossary is a project default or not Default=true

Example

Request

POST /api/v3/projects/1/glossaries HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=glossaryFile; filename=sample-glossary.csv
Content-Type: multipart/form-data

en-US,fr-FR,it-IT,es-ES
Adapter,Adaptateur,adattatore,adaptador
adapter,adaptateur,adattatore,adaptador
caution,attention,attenzione,precaución
Caution,see O4,attenzione,precaución
Gun,Pistolet,pistola,pistola
gun,pistolet,pistola,pistola
Label,Étiquette,etichetta,etiqueta
label,étiquette,etichettare,etiqueta
Manifold,Collecteur,collettore,"colector, múltiple"
manifold,embase,collettore,"colector, múltiple"
pin,"fiche, goupille, broche, cheville, tenon, tige",pin,"clavija (eléctrica), pasador, vástago, perno (no roscado), patilla, pin (electrónica)"
Pin,Goupille,perno,"clavija (eléctrica), pasador, vástago, perno (no roscado), patilla, pin (electrónica)"
Plug,Bougie,tappo,"enchufe, tapón"
Plug,"fiche, goupille, broche, cheville, tenon, tige",connettore,"enchufe, tapón"
plug,"not ""prise"", but fiche, goupille, broche, cheville, tenon, tige",spina,"enchufe, tapón"
spring,ressort,molla,"muelle, resorte"
Spring,Ressort,Molla,elástico(a)
Swivel,Pivot,girevole,giratoria(o)
swivel,"raccord tournant, articulation",raccordo girevole,giratoria(o)
Tag,Étiquette,tag,"etiqueta, marca"
tag,"balise, marque",etichetta,"etiqueta, marca"
technical data,données techniques,dati tecnici,característica/información/datos técnicos(as)
Technical Data,Données techniques,Dati tecnici,características/información/datos técnicos(as)
Troubleshooting,Dépannage,Ricerca e riparazione dei guasti,Resolución de problemas
troubleshooting,dépannage,risoluzione dei problemi,Resolución de problemas
buna-N,buna-N,buna-N,buna-N
buna-S,buna-S,buna-S,buna-S
bar,bar,bar,bar
Mpa,MPa,Mpa,Mpa
waterbased,"aqueux, aqueuse",a base d'acqua,"en base acuosa, a base de agua, medio acuoso"
waterborne,à l'eau,a base acquosa,"en base acuosa, a base de agua, medio acuoso"
"1,1,1-trichloro-ethane","1,1,1-trichloroéthane","1,1,1-tricloro-etano","tricloroetano 1,1,1"
4-ball piston design,piston à 4 billes,design a pistone a 4 sfere,pistón de 4 bolas
700 Series Hose Reels,Dévidoirs de la série 700,avvolgitubo Serie 700,Carretes para mangueras serie 700
7900 HD,7900 HD,7900 HD,7900 HD
AAF tip line,gamme de buses AAF,linea di ugelli AAF,línea de boquillas AAF
abrasion resistance,résistance à l'abrasion,resistenza all'abrasione,resistencia a la abrasión
abrasive applications,applications abrasives,applicazioni abrasive,aplicaciones abrasivas
abrasive fillers,produits de remplissage abrasifs,"cariche riempitive abrasive, cariche abrasive",rellenos abrasivos
abrasive materials,matériaux abrasifs,materiali abrasivi,materiales abrasivos
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=glossaryPayload; filename=request
Content-Type: application/json

{
  "name": "Sample Glossary One",
  "projectDefault": false
}
--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: 341

{
  "id" : "98f47a23-968c-4ad4-83a5-e4dc323a1c56",
  "name" : "Sample Glossary One",
  "createdDate" : "2021-06-02T08:26:58.91457Z",
  "createdBy" : {
    "id" : "6",
    "name" : "Dotsub Manager Manager",
    "email" : "[email protected]",
    "timezone" : "America/Los_Angeles"
  },
  "csvUpdatedDate" : null,
  "projectDefault" : false
}

Update Project Glossary

A PUT request will update project glossary.

POST /api/v3/project/{projectId}/glossaries/{glossaryId}

Input

Part Description

glossaryFile

A multipart CSV file represents the glossary content, File must be matching the following rules Glossary file must be a CSV file, here is an example http://videotms.com/misc/sample-glossary.csv to get you started. Please make sure your CSV file is using comma or semi-colon as delimiter. The first row of the CSV should list all the language codes included in the glossary. Language codes are composed by the ISO 693-1 code (2 letters), dash, and the ISO 3166 country code (2 letters, uppercase). For example: en-US, ja-JP or pt-BR. The glossary must contain at least two languages (columns). Only languages enabled on your organization’s settings are allowed. Blank glossary entries are allowed, if there are no translations available for the given language.

glossaryPayload

Required A multipart json represents the metadata required to create the glossary

Path Type Description

glossaryPayload

Object

Glossary payload that contains information about glossary

glossaryPayload.name

String

Required String to set the glossary name

glossaryPayload.projectDefault

Boolean

Boolean to set whether the glossary is a project default or not Default=true

Example

Request

PUT /api/v3/projects/13/glossaries/1 HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=glossaryFile; filename=sample-glossary.csv
Content-Type: multipart/form-data

en-US,fr-FR,it-IT,es-ES
Adapter,Adaptateur,adattatore,adaptador
adapter,adaptateur,adattatore,adaptador
caution,attention,attenzione,precaución
Caution,see O4,attenzione,precaución
Gun,Pistolet,pistola,pistola
gun,pistolet,pistola,pistola
Label,Étiquette,etichetta,etiqueta
label,étiquette,etichettare,etiqueta
Manifold,Collecteur,collettore,"colector, múltiple"
manifold,embase,collettore,"colector, múltiple"
pin,"fiche, goupille, broche, cheville, tenon, tige",pin,"clavija (eléctrica), pasador, vástago, perno (no roscado), patilla, pin (electrónica)"
Pin,Goupille,perno,"clavija (eléctrica), pasador, vástago, perno (no roscado), patilla, pin (electrónica)"
Plug,Bougie,tappo,"enchufe, tapón"
Plug,"fiche, goupille, broche, cheville, tenon, tige",connettore,"enchufe, tapón"
plug,"not ""prise"", but fiche, goupille, broche, cheville, tenon, tige",spina,"enchufe, tapón"
spring,ressort,molla,"muelle, resorte"
Spring,Ressort,Molla,elástico(a)
Swivel,Pivot,girevole,giratoria(o)
swivel,"raccord tournant, articulation",raccordo girevole,giratoria(o)
Tag,Étiquette,tag,"etiqueta, marca"
tag,"balise, marque",etichetta,"etiqueta, marca"
technical data,données techniques,dati tecnici,característica/información/datos técnicos(as)
Technical Data,Données techniques,Dati tecnici,características/información/datos técnicos(as)
Troubleshooting,Dépannage,Ricerca e riparazione dei guasti,Resolución de problemas
troubleshooting,dépannage,risoluzione dei problemi,Resolución de problemas
buna-N,buna-N,buna-N,buna-N
buna-S,buna-S,buna-S,buna-S
bar,bar,bar,bar
Mpa,MPa,Mpa,Mpa
waterbased,"aqueux, aqueuse",a base d'acqua,"en base acuosa, a base de agua, medio acuoso"
waterborne,à l'eau,a base acquosa,"en base acuosa, a base de agua, medio acuoso"
"1,1,1-trichloro-ethane","1,1,1-trichloroéthane","1,1,1-tricloro-etano","tricloroetano 1,1,1"
4-ball piston design,piston à 4 billes,design a pistone a 4 sfere,pistón de 4 bolas
700 Series Hose Reels,Dévidoirs de la série 700,avvolgitubo Serie 700,Carretes para mangueras serie 700
7900 HD,7900 HD,7900 HD,7900 HD
AAF tip line,gamme de buses AAF,linea di ugelli AAF,línea de boquillas AAF
abrasion resistance,résistance à l'abrasion,resistenza all'abrasione,resistencia a la abrasión
abrasive applications,applications abrasives,applicazioni abrasive,aplicaciones abrasivas
abrasive fillers,produits de remplissage abrasifs,"cariche riempitive abrasive, cariche abrasive",rellenos abrasivos
abrasive materials,matériaux abrasifs,materiali abrasivi,materiales abrasivos
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=glossaryPayload; filename=request
Content-Type: application/json

{
  "name": "Sample Glossary One",
  "projectDefault": false
}
--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: 324

{
  "id" : "1",
  "name" : "Sample Glossary One",
  "createdDate" : "2020-12-01T11:59:00Z",
  "createdBy" : {
    "id" : "5",
    "name" : "Dotsub Admin Admin",
    "email" : "[email protected]",
    "timezone" : "America/Los_Angeles"
  },
  "csvUpdatedDate" : "2021-06-02T08:26:59.401052Z",
  "projectDefault" : false
}

Delete Glossary

A DELETE request will delete glossary.

DELETE /api/v3/projects/{projectId}/glossaries/{glossaryId}
Table 14. /api/v3/projects/{projectId}/glossaries/{glossaryId}
Parameter Description

projectId

The ID of the project associated with glossary

glossaryId

The ID of the glossary

Example

Request

DELETE /api/v3/projects/13/glossaries/1 HTTP/1.1

Response

HTTP/1.1 204 No Content
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

Organization Languages API

An API used for reading languages in a given organization

A GET request will list the organization’s languages.

GET /api/v3/organizations/:organizationId/languages
Table 15. /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'