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.

Path Format Change

We have changed the API path to not include a version (v3). We will continue to support paths that contain v3 for the foreseeable future, but please update to the new path format as soon as possible.

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/tasks HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik9URTVPVGc1T1RnMFFUSXhOVEJEUlRCRlJqSTVOelEwT0VZNFJrRTFSRFkzTnpNek1VSkdRdyJ9.eyJpc3MiOiJodHRwczovL2xvZ2luLnZpZGVvdG1zLmNvbS8iLCJzdWIiOiJ0SkZmVEZxZmJQcmo5M2oxMjFWbmN1bXVWWmdxVDZkMUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6ODA4MC9hcGkvdjMvIiwiaWF0IjoxNjA3NjgwMjI3LCJleHAiOjE2MDc3NjY2MjcsImF6cCI6InRKRmZURnFmYlByajkzajEyMVZuY3VtdVZaZ3FUNmQxIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.I6vpN0fMsQVobhbH8_huPM5_UiNYk0Ook8PTdOUN_yG91g0XOeAAlzrjyiY3uIQBKDZdiLDRAazWnBpe9ai1YFUmrWcp4bu_0-72XCm2biV0hU33JiCc0ITLeIx2ckeVlEZ2yqBcwbvZPTmjW9wBUvtAeE0Z5StWU9Aw4mtScGEtrPdmmAfUOkv5PSx520ieDVSb2d4ni6JDRF-ENiLq6Ex6bBz63SRahmBYcErNPWYqbV5hkf6ADLf9yPIXT01MHWENXsdDu3zYaDqQNOFJSyrgEqTHKBFl9RtUKAsMlSfWs26FiEmEteMWJgGgoa6ED4M2eByIpDNXOekxPs2YuA
Cache your Tokens

Tokens remain valid up to 24 hours, so they can be cached in your system and re-used for multiple requests. We have a limitation on the number of Machine-2-Machine auth tokens that can be issued, therefore excessive usage may lead to your application being temporarily blocked.

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

{
  "timestamp" : "2022-05-20T20:57:27Z",
  "status" : 404,
  "error" : "Not Found",
  "message" : "Media with ID foobar wasn't found",
  "path" : "/api/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" : "2022-05-20T20:57:28Z",
  "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/media
Avoid polling the Media endpoint

Please avoid polling this endpoint with repetitive and continuous requests. If you need to constantly monitor the media list to identify new entries, or monitor the encoding status of existing items, please consider taking advantage of the Notifications API webhook mechanism.

Query Parameters

Parameter Description

pageSize

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

pageIndex

Page index in paged set.
Default: 0

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/media?title=video+title&sort=-createdDate&pageIndex=0&pageSize=2 HTTP/1.1
X-CSRF-TOKEN: 1b72c0fd-65f3-45f7-bcb5-bdcfefb8ae0f

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

{
  "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",
      "waveformUrl" : null,
      "error" : null,
      "originalLengthInMilliseconds" : null,
      "encodedLengthInMilliseconds" : null,
      "reprocessWith" : null
    },
    "externalReferences" : [ ],
    "metadata" : {
      "type" : "VIDEO",
      "length" : 8000,
      "width" : null,
      "height" : null,
      "visible" : false,
      "uploaderUserId" : "21",
      "signedUrl" : null
    },
    "chunkParentMediaId" : null,
    "chunkIndex" : null,
    "chunkStart" : null,
    "chunkEnd" : null,
    "mediaChunkIds" : null,
    "estimate" : false,
    "estimatedLength" : null,
    "estimatedTasks" : null,
    "clientCustomerName" : null,
    "importUrl" : null,
    "s3Upload" : false
  }, {
    "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",
      "waveformUrl" : null,
      "error" : null,
      "originalLengthInMilliseconds" : null,
      "encodedLengthInMilliseconds" : null,
      "reprocessWith" : null
    },
    "externalReferences" : [ ],
    "metadata" : {
      "type" : "VIDEO",
      "length" : 33000,
      "width" : null,
      "height" : null,
      "visible" : false,
      "uploaderUserId" : "21",
      "signedUrl" : null
    },
    "chunkParentMediaId" : null,
    "chunkIndex" : null,
    "chunkStart" : null,
    "chunkEnd" : null,
    "mediaChunkIds" : null,
    "estimate" : false,
    "estimatedLength" : null,
    "estimatedTasks" : null,
    "clientCustomerName" : null,
    "importUrl" : null,
    "s3Upload" : false
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 2,
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : false,
  "totalElements" : 16,
  "totalPages" : 8,
  "first" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 2,
  "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 Primary 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

content[].metadata.type

String

media file type either 'VIDEO' or 'AUDIO'

content[].metadata.length

Number

media file length

content[].metadata.width

Number

media file frame width

content[].metadata.height

Number

media file frame height

content[].externalReferences

Array

List of external references of the media. Each is record of association to an OVP for ingest/push and/or used to store a client’s ID of the media.

content[].externalReferences[].ovp

String

The OVP of the external reference. Will be null if external reference is client’s ID.

content[].externalReferences[].externalId

String

The ExternalId of the external reference.

content[].externalReferences[].ingested

Boolean

Boolean indicating if the media was ingested from the OVP.

content[].clientCustomerName

String

The name of the client’s customer who owns the source video

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/media/:mediaId
Table 1. /api/media/{mediaId}
Parameter Description

mediaId

The ID of the media to read

Example

Request

GET /api/media/12 HTTP/1.1
X-CSRF-TOKEN: 9306969a-ae77-424d-b5ac-477db351f135

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

{
  "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",
    "waveformUrl" : null,
    "error" : null,
    "originalLengthInMilliseconds" : null,
    "encodedLengthInMilliseconds" : null,
    "reprocessWith" : null
  },
  "externalReferences" : [ ],
  "metadata" : {
    "type" : "VIDEO",
    "length" : 33000,
    "width" : null,
    "height" : null,
    "visible" : false,
    "uploaderUserId" : "1",
    "signedUrl" : null
  },
  "chunkParentMediaId" : null,
  "chunkIndex" : null,
  "chunkStart" : null,
  "chunkEnd" : null,
  "mediaChunkIds" : [ ],
  "estimate" : false,
  "estimatedLength" : null,
  "estimatedTasks" : null,
  "clientCustomerName" : null,
  "importUrl" : null,
  "s3Upload" : false
}
Path Type Description

mediaId

String

ID of the media

s3Upload

Boolean

If s3Upload true, the response will include an Amazon S3 pre-signed URL for direct media file upload

contentType

String

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

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 Primary 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

metadata.type

String

media file type either 'VIDEO' or 'AUDIO'

metadata.length

Number

media file length

metadata.width

Number

media file frame width

metadata.height

Number

media file frame height

metadata.signedUrl

String

media presigned url to dotsub s3 buckets where media source can be updated, generated when requesting with s3Upload and contentType

externalReferences

Array

List of external references of the media. Each is record of association to an OVP for ingest/push and/or used to store a client’s ID of the media.

externalReferences[].ovp

String

The OVP of the external reference. Will be null if external reference is client’s ID.

externalReferences[].externalId

String

The ExternalId of the external reference.

externalReferences[].ingested

Boolean

Boolean indicating if the media was ingested from the OVP.

clientCustomerName

String

The name of the client’s customer who owns the source video

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/media/:mediaId/languages/:languageId/subtitles/:subtitleFormat
Table 2. /api/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/media/1/languages/en-US/subtitles/VTT HTTP/1.1
X-CSRF-TOKEN: 7be250e4-e921-44d3-b61f-ce3034b0eeeb

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

WEBVTT

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/media/:mediaId/languages/:languageId/subtitles
Table 3. /api/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/media/14/languages/en-US/subtitles HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
completeTask: false
X-CSRF-TOKEN: 0fa9cf1f-b075-417d-aff7-554c8e24d0fc

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

{
  "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" : "325b010a-d2a3-4694-a608-306e14875ec3",
    "title" : null,
    "description" : null,
    "comment" : "Imported from _dmd_short_eng.srt",
    "completion" : 27,
    "createdBy" : {
      "userId" : "6",
      "firstname" : "Dotsub Manager",
      "lastname" : "Manager",
      "email" : "[email protected]",
      "timezone" : "America/Los_Angeles",
      "displayName" : "Dotsub Manager Manager",
      "systemAdmin" : false,
      "lastActive" : null,
      "unreadNotifications" : null,
      "selectedAssigneeUser" : null,
      "assigneeUsers" : null
    },
    "createdAt" : "2022-05-20T20:57:34.072688Z",
    "finalized" : true,
    "lockingVersion" : 0,
    "overlapEnabled" : false
  },
  "versions" : null,
  "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/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. Only ()_-,. and alphanumeric characters are allowed.

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. Only ()_-,. and alphanumeric characters are allowed.

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.

mediaDto.clientCustomerName

String

The name of the client’s customer who owns the source video.

Example

Request

POST /api/media HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: 31f65d67-5620-4008-9a3f-15a65fa5f3d5

{
  "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: 3278

{
  "mediaId" : "b5d7576a-825d-43f8-b322-1415ca87d937",
  "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" : "2022-05-20T20:57:32.438656Z",
  "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" : false,
    "colorHex" : "#76838F",
    "textColorHex" : "#FFFFFF"
  } ],
  "uploadDetail" : {
    "id" : "746292e0-a176-4739-a211-042046730dd8",
    "start" : "2022-05-20T20:57:32.394419Z",
    "finish" : null,
    "origin" : "DISK",
    "status" : "IN_QUEUE",
    "percentage" : 0,
    "errorMessage" : null,
    "rawFileStorageUrl" : null,
    "ovp" : null,
    "uploadUpdateToken" : "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJiNWQ3NTc2YS04MjVkLTQzZjgtYjMyMi0xNDE1Y2E4N2Q5MzcifQ.-w428i8uKJT1ThC7FUTNbot1nV-onW2xJvRHnhJXkm_DxJudhtrfH0Yq3PsWZiPxTn2cwAWckTNIQfPnqO9Krg"
  },
  "encodedMedia" : {
    "id" : "2b17e26e-68b7-4f4d-a852-883522a777ea",
    "mp4Url" : null,
    "rawS3Mp4Url" : null,
    "mp4HdUrl" : null,
    "gifUrl" : null,
    "thumbnailUrl" : null,
    "waveformUrl" : null,
    "error" : null,
    "originalLengthInMilliseconds" : null,
    "encodedLengthInMilliseconds" : null,
    "reprocessWith" : null
  },
  "externalReferences" : [ ],
  "metadata" : {
    "type" : "VIDEO",
    "length" : null,
    "width" : null,
    "height" : null,
    "visible" : true,
    "uploaderUserId" : "6",
    "signedUrl" : "<URL_Dotsub_Media_S3>"
  },
  "chunkParentMediaId" : null,
  "chunkIndex" : null,
  "chunkStart" : null,
  "chunkEnd" : null,
  "mediaChunkIds" : null,
  "estimate" : false,
  "estimatedLength" : null,
  "estimatedTasks" : null,
  "clientCustomerName" : null,
  "importUrl" : null,
  "s3Upload" : false
}

Update Media

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

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

mediaId

The ID of the media to update

Input

The following fields may be updated:

Path Type Description

s3Upload

Boolean

Boolean to indicate if media source is to be updated with a file uploaded to dotsub s3 buckets.

importUrl

String

Public URL of the video file associated with this media. Ignored if s3Upload is true (direct file upload request).

fileName

String

if s3Upload is true, the file name associated to the media

title

String

Title of media. Only ()_-,. and alphanumeric characters are allowed.

description

String

Description of media. Only ()_-,. and alphanumeric characters are allowed.

notes

String

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

webhook

String

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

workflowId

String

ID of the workflow to be associated with the media

externalId

String

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

uploadDetail.uploadUpdateToken

String

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

uploadDetail.status

String

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

uploadDetail.percentage

Number

Upload completion percentage.

uploadDetail.rawFileStorageUrl

String

if s3Upload is true, the URL of the uploaded file in the S3 bucket.

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/media/12 HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: d6d1afca-250c-4336-91ae-e30eac2f2b71

{
  "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: 3328

{
  "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" : false,
    "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",
    "waveformUrl" : null,
    "error" : null,
    "originalLengthInMilliseconds" : null,
    "encodedLengthInMilliseconds" : null,
    "reprocessWith" : null
  },
  "externalReferences" : [ ],
  "metadata" : {
    "type" : "VIDEO",
    "length" : 33000,
    "width" : null,
    "height" : null,
    "visible" : false,
    "uploaderUserId" : "1",
    "signedUrl" : null
  },
  "chunkParentMediaId" : null,
  "chunkIndex" : null,
  "chunkStart" : null,
  "chunkEnd" : null,
  "mediaChunkIds" : null,
  "estimate" : false,
  "estimatedLength" : null,
  "estimatedTasks" : null,
  "clientCustomerName" : null,
  "importUrl" : null,
  "s3Upload" : false
}

Delete Media

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

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

mediaId

The ID of the media to delete

Example

Request

DELETE /api/media/4 HTTP/1.1
X-CSRF-TOKEN: 60f2d829-154c-49d5-ae46-0f00269ae889

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/tasks
Avoid polling the Tasks endpoint

Please avoid polling this endpoint with repetitive and continuous requests. If you need to constantly monitor the tasks list to identify new tasks, or monitor the status of existing tasks, please consider taking advantage of the Notifications API webhook mechanism.

Query Parameters

Parameter Description

pageSize

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

pageIndex

Page index in paged set.
Default: 0

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_PIVOT_TRANSLATE, TASK_DIRECT_TRANSLATE, TASK_TRANSLATE, TASK_REVIEW, TASK_POST_EDITING, TASK_PROOF_READING, TASK_CUSTOM, TASK_SIGN_OFF, TASK_BURN_IN, TASK_PUSH)

languageId

Filter by task language ID

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/tasks?sort=-createdDate&pageIndex=0&pageSize=2 HTTP/1.1

Response

HTTP/1.1 200 OK
Set-Cookie: XSRF-TOKEN=c1c0e57c-e5fb-419c-ac57-c7f49a7ae127; Path=/
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: 4792

{
  "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,
    "mediaClientCustomerName" : 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" : false,
      "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,
    "manuallyCreated" : null,
    "estimate" : 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,
    "mediaClientCustomerName" : 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,
    "manuallyCreated" : null,
    "estimate" : false
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 2,
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : false,
  "totalElements" : 20,
  "totalPages" : 10,
  "first" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 2,
  "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_PIVOT_TRANSLATE, TASK_DIRECT_TRANSLATE, TASK_TRANSLATE, TASK_REVIEW, TASK_POST_EDITING, TASK_PROOF_READING, TASK_CUSTOM, TASK_SIGN_OFF, TASK_BURN_IN, 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/tasks/:vtmsTaskId
Table 6. /api/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/tasks/4?_csrf=dea5a1ab-4d7b-4d64-a1de-0a874136382e 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: 2296

{
  "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" : "2022-05-20T20:57:23.994035Z",
  "accepted" : true,
  "type" : "TASK_CAPTION",
  "mediaTitle" : "Video Title 1",
  "mediaDescription" : "This is the description",
  "mediaFilename" : "VIDEO-FOO.MOV",
  "mediaChunkIndex" : null,
  "mediaId" : "1",
  "mediaExternalId" : "3979279311001",
  "mediaState" : null,
  "mediaDeletedDate" : null,
  "mediaClientCustomerName" : 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" : false,
    "colorHex" : "#9ECE67",
    "textColorHex" : "#FFFFFF"
  }, {
    "tagId" : "8",
    "name" : "Tag Two",
    "color" : "4700358",
    "textColor" : "16777215",
    "workflow" : false,
    "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,
  "manuallyCreated" : null,
  "estimate" : 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_PIVOT_TRANSLATE, TASK_DIRECT_TRANSLATE, TASK_TRANSLATE, TASK_REVIEW, TASK_POST_EDITING, TASK_PROOF_READING, TASK_CUSTOM, TASK_SIGN_OFF, TASK_BURN_IN, TASK_PUSH)

languageId

String

Language Id of the task, as returned in the Organization Languages API (see https://videotms.com/api/apidocs/html5/index.html#_organization_languages_api)

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

String

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 notification 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.

Notification Actions

Action Description Audience

CAPTIONING_REQUEST

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

Linguists, Admins and Project Managers

CAPTIONING_ASSIGNED

Captioning task assigned for work.

Admins and Project Managers

CAPTIONING_ACCEPTED

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

Linguists, Admins and Project Managers

CAPTIONING_FINISHED

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

Admins and Project Managers

CAPTIONING_REOPENED

Captioning task has been re-opened after being completed, likely because some re-work is needed.

Linguists, Admins and Project Managers

TRANSLATION_REQUEST

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

Linguists, Admins and Project Managers

TRANSLATION_ASSIGNED

Translation task assigned for work.

Admins and Project Managers

TRANSLATION_ACCEPTED

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

Linguists, Admins and Project Managers

TRANSLATION_FINISHED

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

Admins and Project Managers

TRANSLATION_REOPENED

Translation task has been re-opened after being completed, likely because some re-work is needed.

Linguists, Admins and Project Managers

REVIEW_REQUEST

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

Linguists, Admins and Project Managers

REVIEW_ASSIGNED

Review task for captioning/translation assigned for work.

Admins and Project Managers

REVIEW_ACCEPTED

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

Linguists, Admins and Project Managers

REVIEW_FINISHED

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

Admins and Project Managers

REVIEW_REOPENED

Review task has been re-opened after being completed, likely because some re-work has been done and an additional review is needed.

Linguists, Admins and Project Managers

CUSTOM_REQUEST

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

Linguists, Admins and Project Managers

CUSTOM_ASSIGNED

Custom task assigned for work.

Admins and Project Managers

CUSTOM_ACCEPTED

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

Linguists, Admins and Project Managers

CUSTOM_FINISHED

Custom task has been finished and captions are ready.

Admins and Project Managers

CUSTOM_REOPENED

Custom task has been re-opened after being completed, likely because some re-work is needed.

Linguists, Admins and Project Managers

BURN_IN_FINISHED

Burn in task has finished successfully.

Admins and Project Managers

BURN_IN_FAILED

Burn in task has failed.

Admins and Project Managers

SHARED_NOT_FINISHED_BY_VENDOR

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

Admins and Project Managers

SHARED_REASSIGNED_REMOVED_VENDOR

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

Admins and Project Managers

TASK_DUE_DATE_CHANGED_ADMINS

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

Admins and Project Managers

TASK_DUE_DATE_CHANGED_ASSIGNEES

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

Linguists

TASK_DELETED_ADMINS

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

Admins and Project Managers

TASK_DELETED_ASSIGNEES

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

Linguists

LINGUIST_SIGNUP

A new linguist has completed registration in the organization.

Admins and Project Managers

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.

Admins and Project Managers

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).

Linguists

TASK_PAST_DUE_MANAGERS

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

Admins and Project Managers

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).

Linguists

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)

Admins and Project Managers

TASK_PROCESSING_FAILED

Asynchronous automated task failed. Affected task types: * ASR captioning * Machine Translation * Push * Burn-In

Admins and Project Managers

MEDIA_ENCODING_FAILED

A media has failed encoding after being added to VideoTMS.

Admins and Project Managers

MEDIA_WORKFLOW_FAILED

Workflow processing for media failed.

Admins and Project Managers

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/projects

Query Parameters

Parameter Description

pageSize

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

pageIndex

Page index in paged set.
Default: 0

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/projects?pageIndex=0&pageSize=1 HTTP/1.1
X-CSRF-TOKEN: 59b70e77-8b41-422f-86a2-add9fac6af5b

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

{
  "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" : false,
      "colorHex" : "#76838F",
      "textColorHex" : "#FFFFFF"
    }, {
      "tagId" : "2",
      "name" : "Technical",
      "color" : "14043467",
      "textColor" : "16777215",
      "workflow" : false,
      "colorHex" : "#D6494B",
      "textColorHex" : "#FFFFFF"
    }, {
      "tagId" : "3",
      "name" : "Kaltura",
      "color" : "3507146",
      "textColor" : "16777215",
      "workflow" : false,
      "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" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 1,
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : false,
  "totalElements" : 12,
  "totalPages" : 12,
  "first" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 1,
  "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/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/projects HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: e363c469-5640-4b7d-8fae-ca7230c8dccb

{
  "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: 1458

{
  "projectId" : "0f61ff5a-2a6d-4a93-9f21-2258e66eded5",
  "name" : "Project New One",
  "client" : null,
  "tags" : [ {
    "tagId" : "1",
    "name" : "Medical",
    "color" : "7766927",
    "textColor" : "16777215",
    "workflow" : false,
    "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/projects/:projectId
Table 7. /api/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/projects/12 HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: 28f4e7b6-e8e0-4bb3-bef8-800f15bd434b

{
  "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: 1254

{
  "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" : false,
    "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 for projects and tasks.

Read Subtitle Specifications List

A GET request will list the organization’s subtitle specifications.

GET /api/subtitleSpecifications

Query Parameters

Parameter Description

pageSize

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

pageIndex

Page index in paged set.
Default: 0

projectId

Filter by project id of Subtitle Specs

languageId

Filter by language id of Subtitle Specs

languageName

Filter by language name of Subtitle Specs

taskId

Returns the Subtitle Specs for a Task ID

sort

Sort the paged subtitle spec set. The result set may be sorted by subtitleSpecificationId and languageName. Default sort direction is Ascending. To sort Descending, prepend - to sort value. Default sort is by subtitleSpecificationId descending.

Example

Request

GET /api/subtitleSpecifications?pageIndex=0&pageSize=5&projectId=1&languageName=french HTTP/1.1
X-CSRF-TOKEN: f667630b-2ebe-41c4-8dd6-d13296ec0dc3

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

{
  "content" : [ {
    "subtitleSpecificationId" : "4",
    "projectId" : "1",
    "projectDefault" : false,
    "languageId" : "fr-FR",
    "languageName" : "French (France)",
    "enabled" : true,
    "spokenAudio" : true,
    "audioDescription" : true,
    "onScreenText" : true,
    "speakerIdentification" : "NONE",
    "dialogueStyle" : "LINE_BREAKS",
    "maxLinesPerCaption" : 3,
    "maxCharactersPerLine" : 54,
    "minCaptionDurationInMillis" : 3000,
    "maxCaptionDurationInMillis" : 9000,
    "maxCharactersPerSecondPerCaption" : null,
    "comments" : "French comment",
    "mediaNotes" : null
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 5,
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : true,
  "totalElements" : 1,
  "totalPages" : 1,
  "first" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 1,
  "size" : 5,
  "empty" : false
}
Path Type Description

content

Array

Array of found sub specs

content[].subtitleSpecificationId

String

ID of the Subtitle Specification

content[].projectId

String

ID of the project associated with the Subtitle Specification

content[].enabled

Boolean

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

content[].languageId

String

ID of the Language associated with the Subtitle Specification

content[].languageName

String

The Language Name associated with the Subtitle Specification

content[].projectDefault

Boolean

Boolean indicating if the Subtitle Specification is the project default

content[].spokenAudio

Boolean

If true, include Spoken Audio

content[].audioDescription

Boolean

If true, include Audio Descriptions

content[].onScreenText

Boolean

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

content[].speakerIdentification

String

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

content[].dialogueStyle

String

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

content[].maxLinesPerCaption

Number

The maximum line count allowed in a caption/subtitle

content[].maxCharactersPerLine

Number

The maximum character count allowed in a caption/subtitle line

content[].minCaptionDurationInMillis

Number

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

content[].maxCaptionDurationInMillis

Number

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

content[].comments

String

General comments for spec (Markdown is supported)

content[].mediaNotes

String

Will be returned if taskId is set in filter. Media Notes of the task’s media.

totalElements

Number

Total number of sub specs 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 sub specs per page

number

Number

Page number

numberOfElements

Number

Number of sub specs per page

sort

Object

Details of sort being applied

Read Subtitle Specifications

A GET request will return a subtitle specification.

GET /api/subtitleSpecifications/:subtitleSpecId
Table 8. /api/subtitleSpecifications/{subtitleSpecId}
Parameter Description

subtitleSpecId

The ID of the Subtitle Specification

Example

Request

GET /api/subtitleSpecifications/1 HTTP/1.1
X-CSRF-TOKEN: a38d6d0d-c75a-4c0c-a859-800852772449

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

{
  "subtitleSpecificationId" : "1",
  "projectId" : "1",
  "projectDefault" : true,
  "languageId" : null,
  "languageName" : null,
  "enabled" : true,
  "spokenAudio" : true,
  "audioDescription" : true,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "maxCharactersPerSecondPerCaption" : 60,
  "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

languageId

String

ID of the Language associated with the Subtitle Specification

languageName

Null

The Language Name associated with the Subtitle Specification

projectDefault

Boolean

Boolean indicating if the Subtitle Specification is the project default

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)

Create Subtitle Specification

A POST request will create a Subtitle Specification.

POST /api/subtitleSpecification

Input

Path Type Description

projectId

String

ID of the Project for the Subtitle Specification

enabled

Boolean

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

languageId

String

ID of the Language associated with the Subtitle Specification

projectDefault

Boolean

Boolean indicating if the Subtitle Specification is the project default

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/subtitleSpecifications HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: da32347f-57f0-401c-99d6-96c192a78303

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

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

{
  "subtitleSpecificationId" : "98b4d367-17ba-4927-a4fe-124cea867267",
  "projectId" : "11",
  "projectDefault" : true,
  "languageId" : null,
  "languageName" : null,
  "enabled" : true,
  "spokenAudio" : false,
  "audioDescription" : false,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "maxCharactersPerSecondPerCaption" : 60,
  "comments" : "**test comments**",
  "mediaNotes" : null
}

Update Subtitle Specification

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

PATCH /api/subtitleSpecification/:subtitleSpecId
Table 9. /api/subtitleSpecifications/{subtitleSpecId}
Parameter Description

subtitleSpecId

The ID of the Subtitle Specification

Input

Path Type Description

enabled

Boolean

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

languageId

String

ID of the Language associated with the Subtitle Specification

projectDefault

Boolean

Boolean indicating if the Subtitle Specification is the project default

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/subtitleSpecifications/1 HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: 511ecef0-e5b3-42f3-bbd4-9bcdd872e965

{
  "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: 553

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

Delete Subtitle Specification

A DELETE request will delete a Subtitle Specification.

DELETE /api/subtitleSpecification/:subtitleSpecId
Table 10. /api/subtitleSpecifications/{subtitleSpecId}
Parameter Description

subtitleSpecId

The ID of the Subtitle Specification to delete

Example

Request

DELETE /api/subtitleSpecifications/4 HTTP/1.1
X-CSRF-TOKEN: a926b362-340e-4832-bc2d-87b68fd6dab2

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

Read Default Subtitle Specification For Project

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

DEPRECATED endpoint

Please use Subtitle Specification List API instead.

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

projectId

The ID of the project associated with the Subtitle Specification

Example

Request

GET /api/projects/1/subtitleSpecification HTTP/1.1
X-CSRF-TOKEN: 01ee9e66-eb1f-4ac6-a300-ae6f1d35133a

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

{
  "subtitleSpecificationId" : "1",
  "projectId" : "1",
  "projectDefault" : true,
  "languageId" : null,
  "languageName" : null,
  "enabled" : true,
  "spokenAudio" : true,
  "audioDescription" : true,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "maxCharactersPerSecondPerCaption" : 60,
  "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

languageId

Null

ID of the Language associated with the Subtitle Specification

languageName

Null

The Language Name associated with the Subtitle Specification

projectDefault

Boolean

Boolean indicating if the Subtitle Specification is the project default

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 Default Subtitle Specification For Project’s Media

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

DEPRECATED endpoint

Subtitle specifications are now per language, and should be read by Task ID. Please use Subtitle Specification List API instead.

GET /api/projects/:projectId/subtitleSpecification/media/:mediaId
Table 12. /api/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/projects/1/subtitleSpecification/media/12 HTTP/1.1
X-CSRF-TOKEN: e36280cf-b0e2-4580-9571-a51e6eff70ad

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

{
  "subtitleSpecificationId" : "1",
  "projectId" : "1",
  "projectDefault" : true,
  "languageId" : null,
  "languageName" : null,
  "enabled" : true,
  "spokenAudio" : true,
  "audioDescription" : true,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "maxCharactersPerSecondPerCaption" : 60,
  "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

languageId

Null

ID of the Language associated with the Subtitle Specification

languageName

Null

The Language Name associated with the Subtitle Specification

projectDefault

Boolean

Boolean indicating if the Subtitle Specification is the project default

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 Default Subtitle Specification

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

DEPRECATED endpoint

Please use Create Subtitle Specification API instead.

POST /api/projects/:projectId:/subtitleSpecification
Table 13. /api/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/projects/13/subtitleSpecification HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: 92933d17-0cc1-4267-8f4f-38ebcc8f948b

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

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

{
  "subtitleSpecificationId" : "fe646187-b341-4275-a7d6-63e38fb28089",
  "projectId" : "13",
  "projectDefault" : true,
  "languageId" : null,
  "languageName" : null,
  "enabled" : true,
  "spokenAudio" : false,
  "audioDescription" : false,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "maxCharactersPerSecondPerCaption" : 60,
  "comments" : "**test comments**",
  "mediaNotes" : null
}

Update Default Subtitle Specification

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

DEPRECATED endpoint

Please use Update Subtitle Specification API instead.

PATCH /api/projects/:projectId:/subtitleSpecification
Table 14. /api/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/projects/1/subtitleSpecification HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: 7a89cca7-d596-4939-9378-02b0acbe3bfe

{
  "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: 553

{
  "subtitleSpecificationId" : "1",
  "projectId" : "1",
  "projectDefault" : true,
  "languageId" : null,
  "languageName" : null,
  "enabled" : true,
  "spokenAudio" : true,
  "audioDescription" : true,
  "onScreenText" : true,
  "speakerIdentification" : "FULLNAME",
  "dialogueStyle" : "DOUBLE_CHEVRON",
  "maxLinesPerCaption" : 2,
  "maxCharactersPerLine" : 35,
  "minCaptionDurationInMillis" : 2000,
  "maxCaptionDurationInMillis" : 10000,
  "maxCharactersPerSecondPerCaption" : 60,
  "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/organizations/:organizationId/workflows
Table 15. /api/organizations/{organizationId}/workflows
Parameter Description

organizationId

The ID of the organization owning workflows

Query Parameters

Parameter Description

pageSize

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

pageIndex

Page index in paged set.
Default: 0

name

Filter workflows by name

projectId

Filter workflows by Project ID

Example

Request

GET /api/organizations/dotsub-test/workflows?pageIndex=0&pageSize=1 HTTP/1.1
X-CSRF-TOKEN: 03535abe-489d-4785-8a8a-ae55eac63561

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" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 1,
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : false,
  "totalElements" : 4,
  "totalPages" : 4,
  "first" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 1,
  "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/projects/{projectId}/glossaries

Query Parameters

Parameter Description

pageSize

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

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/projects/1/glossaries?pageIndex=0&pageSize=1 HTTP/1.1
X-CSRF-TOKEN: 44458bf7-c47f-41f0-8b19-76fc91f01fb3

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" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 1,
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : false,
  "totalElements" : 6,
  "totalPages" : 6,
  "first" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 1,
  "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/projects/{projectId}/glossaries/{glossaryId}
Table 16. /api/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/projects/13/glossaries/1 HTTP/1.1
X-CSRF-TOKEN: 1fdba53f-63a1-491d-88c6-990da9063b8e

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/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/projects/1/glossaries HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
X-CSRF-TOKEN: 9a21acd2-f461-43a3-ab11-e5b963a58a71

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

{
  "id" : "2b6eb497-274a-4e34-8b03-40337ea51739",
  "name" : "Sample Glossary One",
  "createdDate" : "2022-05-20T20:57:26.654363Z",
  "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/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/projects/13/glossaries/1 HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
X-CSRF-TOKEN: cf101228-f218-413d-ab9f-5f5878e2672a

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

{
  "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" : "2022-05-20T20:57:27.38411Z",
  "projectDefault" : false
}

Delete Glossary

A DELETE request will delete glossary.

DELETE /api/projects/{projectId}/glossaries/{glossaryId}
Table 17. /api/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/projects/13/glossaries/1 HTTP/1.1
X-CSRF-TOKEN: 06814c35-5a4f-482b-8cb9-06b6040b23b7

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/organizations/:organizationId/languages
Table 18. /api/organizations/{organizationId}/languages
Parameter Description

organizationId

Required Id of the organization contains language list.

Example

Request

GET /api/organizations/dotsub-test/languages HTTP/1.1
X-CSRF-TOKEN: b43d5fab-08f1-4681-8086-b8c9daec1d9b

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

[ {
  "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-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 is mostly in BCP47 format (ISO 639-1 + 'dash' + ISO-3166-1) eg: 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'

User API

Read Users

An API used for reading users in a given organization

A GET request will list the organization’s users.

GET /api/users

Query Parameters

Parameter Description

pageSize

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

pageIndex

Page index in paged set.
Default: 0

organizationId

Required ID of user’s organization, required to include assignee data in response for user

sort

Sort the paged users set. The result set may be sorted by email and lastActive. Default direction is Descending. To sort Ascending, prepend + to sort value. Default -email

email

Filter by email address

name

Filter by user last name, first name

projectId

Filter by project ID, applicable to Project Managers only

tagName

Filter by tags of users

lastActive

Filter by Last Active Date of the user should be in ISO8601 format eg:2018-09-01T12:01:00

Example

Request

GET /api/users?organizationId=dotsub-test&email=translator2%40dotsub-test.com&pageIndex=0&pageSize=2 HTTP/1.1
X-CSRF-TOKEN: bf617ed0-7e45-4fe6-8303-d077d82a024a

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

{
  "content" : [ {
    "userId" : "14",
    "firstname" : "Sally",
    "lastname" : "Translator",
    "email" : "[email protected]",
    "timezone" : "America/Los_Angeles",
    "displayName" : "Sally Translator",
    "systemAdmin" : false,
    "lastActive" : null,
    "unreadNotifications" : null,
    "selectedAssigneeUser" : {
      "id" : "b15101fb-7d2f-4aed-8b1f-c6abf611df8f",
      "name" : "Translator, Sally",
      "type" : "USER",
      "shared" : false,
      "organizationId" : "dotsub-test",
      "createdDate" : "2022-04-11T12:29:22.010094Z",
      "email" : "[email protected]",
      "userId" : "14",
      "users" : [ {
        "userId" : "14",
        "firstname" : "Sally",
        "lastname" : "Translator",
        "email" : "[email protected]",
        "timezone" : "America/Los_Angeles",
        "displayName" : "Sally Translator",
        "systemAdmin" : false,
        "lastActive" : null,
        "unreadNotifications" : null,
        "selectedAssigneeUser" : null,
        "assigneeUsers" : null
      } ],
      "active" : true,
      "tags" : [ ],
      "roles" : null
    },
    "assigneeUsers" : null
  } ],
  "pageable" : {
    "sort" : {
      "sorted" : true,
      "unsorted" : false,
      "empty" : false
    },
    "pageNumber" : 0,
    "pageSize" : 2,
    "offset" : 0,
    "unpaged" : false,
    "paged" : true
  },
  "last" : true,
  "totalElements" : 1,
  "totalPages" : 1,
  "first" : true,
  "sort" : {
    "sorted" : true,
    "unsorted" : false,
    "empty" : false
  },
  "number" : 0,
  "numberOfElements" : 1,
  "size" : 2,
  "empty" : false
}
Path Type Description

content

Array

Array of found users

content[].userId

String

ID of the user

content[].firstname

String

User First Name

content[].lastname

String

User Last Name

content[].email

String

User Email

content[].systemAdmin

Boolean

Is User System Admin

content[].displayName

String

User first and last names as displayed in app

content[].timezone

String

The user’s registered timezone

content[].lastActive

Null

The Last Active Date of when the user was in VideoTMS

content[].unreadNotifications

Null

Count of unread in-app notifications of user

content[].selectedAssigneeUser.id

String

The assignee user ID used for task assignment

totalElements

Number

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

sort

Object

Sort details

Create Users

A POST request will create users in the associated organization.

POST /api/users

Input

Path Type Description

organizationId

String

Required ID of organization

organizationRole

String

Required The organizationRole property shall be the role of the added users. Valid values are LINGUIST and ADMIN

userDtos

Array

Array of UserDtos to add to organization

userDtos[].email

String

Required The email property shall be the email of the added user

Example

Request

POST /api/users HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: c23aca31-a5a6-46ad-a1f7-7e08c98cbdb5

{
  "organizationId": "dotsub-test",
  "organizationRole": "LINGUIST",
  "userDtos": [
    {
      "email": "[email protected]"
    }
  ]
}

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

[ {
  "userId" : "94a08ef1-4d07-400a-bbdb-e242d0cd3454",
  "firstname" : null,
  "lastname" : null,
  "email" : "[email protected]",
  "timezone" : null,
  "displayName" : "[email protected] (Pending Registration)",
  "systemAdmin" : false,
  "lastActive" : null,
  "unreadNotifications" : null,
  "selectedAssigneeUser" : {
    "id" : "0549d22d-4fc0-45c9-bdc1-8d32e02c2a31",
    "name" : null,
    "type" : "USER",
    "shared" : false,
    "organizationId" : "dotsub-test",
    "createdDate" : "2022-05-20T20:57:31.661306Z",
    "email" : "[email protected]",
    "userId" : "94a08ef1-4d07-400a-bbdb-e242d0cd3454",
    "users" : [ {
      "userId" : "94a08ef1-4d07-400a-bbdb-e242d0cd3454",
      "firstname" : null,
      "lastname" : null,
      "email" : "[email protected]",
      "timezone" : null,
      "displayName" : "[email protected] (Pending Registration)",
      "systemAdmin" : false,
      "lastActive" : null,
      "unreadNotifications" : null,
      "selectedAssigneeUser" : null,
      "assigneeUsers" : null
    } ],
    "active" : true,
    "tags" : [ ],
    "roles" : null
  },
  "assigneeUsers" : null
} ]

Delete Users

A DELETE request will use delete users from the associated organization.

DELETE /api/users

Input

Path Type Description

organizationId

String

Required ID of organization

userDtos

Array

Array of UserDtos to delete from organization

userDtos[].email

String

Required The email property shall be the email of the deleted user

Example

Request

DELETE /api/users HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-CSRF-TOKEN: 9b75547b-d036-409e-956b-d68dfae58f60

{
  "organizationId": "dotsub-test",
  "userDtos": [
    {
      "email": "[email protected]"
    }
  ]
}

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