REST Corpus API API Reference

Corpus

The Corpus API is used to manage SYSTRAN corpora used in translation.

Authentication

In header the access token generated from the authorization-server (ses-console) using OAuth2 Flow Client Credentials or PKCE.

Authorization: Bearer YOUR_ACCESS_TOKEN

In header the API Key generated from the authorization-server (ses-console)

Authorization: Key YOUR_API_KEY

In querystring the API Key as key parameter

?key=YOUR_API_KEY

Note about the input/output text

The input text passed as a URL parameter will be escaped with an equivalent of the javascript 'encodeURIComponent' function.
The input text must be encoded in UTF-8.
The output text will be encoded in UTF-8.

Language code values

The language codes to be used are the two-letter codes defined by the ISO 639-1:2002, Codes for the representation of names of languages - Part 1: Alpha-2 code standard.

Refer to the column 'ISO 639-1 code' of this list: http://www.loc.gov/standards/iso639-2/php/code_list.php.

In addition to this list, the following codes are used:

Language Code	Language
auto	Language Detection
tj	Tajik (cyrillic script)

Our new Chinese-target engines and all Chinese-target models trained on Model Studio are XXZH models that support multiple locales (e.g. CN=China Simplified script, TW=Taiwan Traditional script, or HK=Hong Kong Traditional script).

To use them you have to create a XXZH profile in which you define your locale under “Model Schema,” and select the 'zh' language code locale and specify the profileID for a request. By default XX to ZH requests will use the zh-CN locale.

If you are currently using a XXZT profile for Traditional Chinese, please note that new XXZT models will not be released whereas all improvements concerning Traditional Chinese will be now released under XXZH models.

Although the existing XXZT engines may still be used for the moment by calling the language code 'zt', this may change in the future, so we strongly advise you to create a new XXZH profile for your translation needs.

Schemes: https

Version: 1.1.0

Authentication

accessToken

"Bearer access_token" OR "Key api_key"

type

apiKey

name

Authorization

header

apiKey

API Key

type

apiKey

name

key

query

Paths

Corpus

Get API version

GET /resources/corpus/apiVersion

Current version for this API

200 OK

ApiVersionResponse

Successful response

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "version": "1.0.0"
}


apiKey
accessToken

Corpus

List corpora

GET /resources/corpus/list

List available corpora. Parameters can be used to restrict the list of returned corpora.

sourceLang: string

in query

Source language code ( details)

targetLang: string

in query

Target language code ( details)

withoutPending: boolean false

in query

Filter out corpora in "pending" status

withoutError: boolean false

in query

Filter out corpora in "error" status

prefix: string

in query

Prefix of the corpus name

directory: string

in query

If specified, response will return the content of this directory, including corpora and directories. This list can also be filtered by the prefix parameter.

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "directories": [
    "/MyProject/Technical",
    "/MyProject/Administration"
  ],
  "files": [
    {
      "id": "55af580d4cf4c7f74e7c8d1c",
      "name": "/MyProject/gears.txt",
      "createdAt": "Wed Jul 22 10:45:01 2015",
      "format": "text/bitext",
      "nbSegments": 5993,
      "sourceLang": "fr",
      "targetLangs": [
        "en"
      ],
      "status": "ok"
    },
    {
      "id": "56af580d4cf4c8f74e7c9e9a",
      "name": "/MyProject/balloon.tmx",
      "createdAt": "Wed Jul 22 10:47:04 2015",
      "format": "application/x-tmx+xml",
      "nbSegments": 2496,
      "sourceLang": "en",
      "targetLangs": [
        "fr",
        "es"
      ],
      "status": "pending"
    }
  ]
}


apiKey
accessToken

Corpus

Add empty corpus

POST /resources/corpus/add

Add a new empty corpus.

in query

Corpus name. The name also contains the directories (ex: "/myproject/firstPass/PersonalCorpus")

sourceLang: string

in query

Source language code ( details)

targetLang: string

in query

Target language code ( details)

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "corpus": {
    "id": "55af580d4cf4c7f74e7c8d1c"
  }
}


apiKey
accessToken

Corpus

Import corpus

POST /resources/corpus/import

Add a new corpus from an existing corpus.

in query

Corpus name. The name also contains the directories (ex: "/myproject/firstPass/PersonalCorpus")

format: string application/x-tmx+xml, text/bitext application/x-tmx+xml

in query

Format of the input corpus.

input: string

in query

Content of the existing corpus

Either input or inputFile is required

inputFile: file

in formData

Content of the existing corpus

Either input or inputFile is required

tag: string[]

in query

Tag for the the corpus (this parameter can be repeated)

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "corpus": {
    "id": "55af580d4cf4c7f74e7c8d1c"
  }
}


apiKey
accessToken

Corpus

Check corpus existence

GET /resources/corpus/exists

Check if a corpus exists

in query

Corpus name. The name also contains the directories (ex: "/myproject/firstPass/PersonalCorpus")

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "exists": false
}


apiKey
accessToken

Corpus

Get corpus details

GET /resources/corpus/details

Get detailed information about a corpus.

corpusId: string

in query

Corpus identifier

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "id": "55af580d4cf4c7f74e7c8d1c",
  "name": "/MyProject/gears.txt",
  "createdAt": "Wed Jul 22 10:45:01 2015",
  "format": "text/bitext",
  "nbSegments": 5993,
  "sourceLang": "fr",
  "targetLangs": [
    "en"
  ],
  "status": "ok"
}


apiKey
accessToken

Corpus

Update corpus properties

POST /resources/corpus/update

Update properties of a corpus.

corpusId: string

in query

Corpus identifier

in query

Corpus name. The name also contains the directories (ex: "/myproject/firstPass/PersonalCorpus")

tag: string[]

in query

Tag for the the corpus (this parameter can be repeated)

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "updated": true
}


apiKey
accessToken

Corpus

Export corpus

GET /resources/corpus/export

Download a corpus in an expected format.

corpusId: string

in query

Corpus identifier

format: string application/x-tmx+xml, text/bitext application/x-tmx+xml

in query

The expected corpus format

200 OK

Successful response

type

file

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/x-tmx+xml, text/bitext

Response Example (200 OK)

"file"


apiKey
accessToken

Corpus

Delete corpus

POST /resources/corpus/delete

Delete a corpus.

corpusId: string[]

in query

Corpus identifier (this parameter can be repeated)

Array values passed as multiple parameters: ?corpusId=aaa&corpusId=bbb

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "files": [
    {
      "id": "55af70344cf4c7f74e7cbbf0"
    }
  ]
}


apiKey
accessToken

Corpus

Find matches

GET /resources/corpus/match

Find sentences in the corpus that match the input text from a given threshold.

corpusId: string[]

in query

Corpus identifier (this parameter can be repeated)

Array values passed as multiple parameters: ?corpusId=aaa&corpusId=bbb

input: string[]

in query

Text is used to perform the match operation (this parameter can be repeated)

Array values passed as multiple parameters: ?input=aaa&input=bbb

sourceLang: string

in query

Source language code ( details)

targetLang: string

in query

Target language code ( details)

threshold: number (double) 0.7

in query

The fuzzy match threshold from which a sentence will be considered as a match result

limit: integer 1

in query

Limit the number of returned matches. Only first matches within the "limit" will be returned

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "matches": [
    {
      "form": "1er samestre (1136 Kb)",
      "matches": [
        {
          "penalty": 0.1428571492433548,
          "score": 0.8571428656578064,
          "source": "1er semestre (1136 Kb)",
          "target": "First half (1 Kb)"
        }
      ]
    },
    {
      "form": "Antivols alectriques de direction",
      "matches": [
        {
          "penalty": 0,
          "score": 0.75,
          "source": "Antivols électriques de direction",
          "target": "Electrical Steering Column Locks"
        },
        {
          "penalty": 0,
          "score": 0.75,
          "source": "Antivols électriques de direction",
          "target": "Identifier or advanced electronic key"
        }
      ]
    }
  ]
}


apiKey
accessToken

Corpus

List corpus segments

GET /resources/corpus/segment/list

List segments in a corpus.

corpusId: string

in query

Corpus identifier

skip: integer

in query

Skip first found segments in the response

limit: integer

in query

Limit the number of returned segments

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "segments": [
    {
      "lang": "en",
      "source": "glass",
      "id": "5649fdb8569da4eca7037230.5649fe48569da4eca7037232",
      "targets": [
        {
          "id": "5649fe48569da4eca7037233",
          "lang": "fr",
          "target": "mirroir"
        },
        {
          "id": "5649fe48569da4eca7037234",
          "lang": "fr",
          "target": "verre"
        }
      ]
    }
  ]
}


apiKey
accessToken

Corpus

Add corpus segments

POST /resources/corpus/segment/add

Add segments in a corpus.

List of segments to add

corpusId: string: Corpus identifier
segments: object[]: List of segments to add
object lang: string Language source: string Source text targets: object[] List of targets object lang: string Language target: string Target text

Request Example

{
  "corpusId": "55afbc9e17fb5791ef7a54ff",
  "segments": [
    {
      "lang": "fr",
      "source": "Exemple de traduction",
      "targets": [
        {
          "lang": "en",
          "target": "Translation example"
        },
        {
          "lang": "en",
          "target": "Example of translation"
        }
      ]
    }
  ]
}

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "segments": [
    "55afbc9e17fb5791ef7a54fe.55b65d8c6b457345fd2e3473",
    "55afbc9e17fb5791ef7a54fe.55b65d9c6c457345fd1f5a8b"
  ]
}


apiKey
accessToken

Corpus

Delete corpus segments

POST /resources/corpus/segment/delete

Delete segments in a corpus.

corpusId: string

in query

Corpus identifier

segId: string[]

in query

Segment Id (this parameter can be repeated)

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "error": {
    "message": "Internal error",
    "statusCode": 500,
    "info": "object"
  },
  "nbDeleted": "integer"
}


apiKey
accessToken

Corpus

Update corpus segment

POST /resources/corpus/segment/update

Update a segment in a corpus.

corpusId: string

in query

Corpus identifier

segId: string

in query

Segment Id

source: string

in query

Source text

targetId: string

in query

Target id

target: string

in query

Target text. targetId is required if target is specified.

targetLang: string

in query

Target language. targetId is required if targetLang is specified.

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "error": {
    "message": "Internal error",
    "statusCode": 500,
    "info": "object"
  },
  "updated": "boolean"
}


apiKey
accessToken

Corpus

Add corpus segment targets

POST /resources/corpus/segment/target/add

Add targets to a segment in a corpus.

List of targets to add

corpusId: string: Corpus identifier
segId: string: Segment identifier
targets: object[]: List of targets
object lang: string Language target: string Target text

Request Example

{
  "corpusId": "55afbc9e17fb5791ef7a54ff",
  "segId": "55afbc9e17fb5791ef7a54fe.55b69c8d6b457345fd2e347f",
  "targets": [
    {
      "lang": "en",
      "target": "added segment one"
    },
    {
      "lang": "en",
      "target": "added segment two"
    }
  ]
}

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "added": true
}


apiKey
accessToken

Corpus

Delete corpus segment targets

POST /resources/corpus/segment/target/delete

Delete segment targets in a corpus.

corpusId: string

in query

Corpus identifier

segId: string

in query

Segment Id

targetId: string[]

in query

Target id (this parameter can be repeated)

200 OK

Successful response

type

object

400 Bad Request

Invalid parameters

500 Internal Server Error

Error

Response Content-Types: application/json

Response Example (200 OK)

{
  "deleted": true
}


apiKey
accessToken

Schema Definitions

Corpus: object

id: string: Identifier
name: string: Name
createdAt: string: Creation date
format: string: Format
nbSegments: integer: Number of segments
sourceLang: string: Source language
targetLangs: string[]: Target languages
string
status: string pending, error, ok: Corpus status

Example

{
  "id": "string",
  "name": "string",
  "createdAt": "string",
  "format": "string",
  "nbSegments": "integer",
  "sourceLang": "string",
  "targetLangs": [
    "string"
  ],
  "status": "string"
}

CorpusListResponse: object

error: ErrorResponse: Error at request level
files: object[]: List of corpus files
object id: string Identifier name: string Name createdAt: string Creation date format: string Format nbSegments: integer Number of segments sourceLang: string Source language targetLangs: string[] Target languages string status: string pending, error, ok Corpus status
directories: string[]: List of directories. Returned only if directory parameter was specified in the request.
string

Example

{
  "directories": [
    "/MyProject/Technical",
    "/MyProject/Administration"
  ],
  "files": [
    {
      "id": "55af580d4cf4c7f74e7c8d1c",
      "name": "/MyProject/gears.txt",
      "createdAt": "Wed Jul 22 10:45:01 2015",
      "format": "text/bitext",
      "nbSegments": 5993,
      "sourceLang": "fr",
      "targetLangs": [
        "en"
      ],
      "status": "ok"
    },
    {
      "id": "56af580d4cf4c8f74e7c9e9a",
      "name": "/MyProject/balloon.tmx",
      "createdAt": "Wed Jul 22 10:47:04 2015",
      "format": "application/x-tmx+xml",
      "nbSegments": 2496,
      "sourceLang": "en",
      "targetLangs": [
        "fr",
        "es"
      ],
      "status": "pending"
    }
  ]
}

CorpusDetailResponse: object

error: ErrorResponse: Error at request level
corpus: object
id: string Identifier name: string Name createdAt: string Creation date format: string Format nbSegments: integer Number of segments sourceLang: string Source language targetLangs: string[] Target languages string status: string pending, error, ok Corpus status

Example

{
  "id": "55af580d4cf4c7f74e7c8d1c",
  "name": "/MyProject/gears.txt",
  "createdAt": "Wed Jul 22 10:45:01 2015",
  "format": "text/bitext",
  "nbSegments": 5993,
  "sourceLang": "fr",
  "targetLangs": [
    "en"
  ],
  "status": "ok"
}

CorpusUpdateResponse: object

error: ErrorResponse: Error at request level
updated: boolean: Corpus updated

Example

{
  "updated": true
}

LiteCorpus: object

id: string: Identifier

Example

{
  "id": "string"
}

CorpusAddResponse: object

error: ErrorResponse: Error at request level
corpus: object
id: string Identifier

Example

{
  "corpus": {
    "id": "55af580d4cf4c7f74e7c8d1c"
  }
}

CorpusExistsResponse: object

error: ErrorResponse: Error at request level
exists: boolean: True if the corpus exists

Example

{
  "exists": false
}

CorpusDeleteResponse: object

error: ErrorResponse: Error at request level
files: object[]: List of deleted corpora
object id: string Identifier

Example

{
  "files": [
    {
      "id": "55af70344cf4c7f74e7cbbf0"
    }
  ]
}

CorpusImportResponse: object

error: ErrorResponse: Error at request level
corpus: object
id: string Identifier

Example

{
  "corpus": {
    "id": "55af580d4cf4c7f74e7c8d1c"
  }
}

CorpusMatch: object

Corpus match

source: string
target: string
score: number (double)
penalty: number (double)
align: string

Example

{
  "source": "string",
  "target": "string",
  "score": "number (double)",
  "penalty": "number (double)",
  "align": "string"
}

CorpusMatches: object

form: string: Searched form
matches: object[]: List of matches
object Corpus match source: string target: string score: number (double) penalty: number (double) align: string

Example

{
  "form": "string",
  "matches": [
    {
      "source": "string",
      "target": "string",
      "score": "number (double)",
      "penalty": "number (double)",
      "align": "string"
    }
  ]
}

CorpusMatchResponse: object

error: ErrorResponse: Error at request level
matches: object[]: List of matches for each input string
object form: string Searched form matches: object[] List of matches object Corpus match source: string target: string score: number (double) penalty: number (double) align: string

Example

{
  "matches": [
    {
      "form": "1er samestre (1136 Kb)",
      "matches": [
        {
          "penalty": 0.1428571492433548,
          "score": 0.8571428656578064,
          "source": "1er semestre (1136 Kb)",
          "target": "First half (1 Kb)"
        }
      ]
    },
    {
      "form": "Antivols alectriques de direction",
      "matches": [
        {
          "penalty": 0,
          "score": 0.75,
          "source": "Antivols électriques de direction",
          "target": "Electrical Steering Column Locks"
        },
        {
          "penalty": 0,
          "score": 0.75,
          "source": "Antivols électriques de direction",
          "target": "Identifier or advanced electronic key"
        }
      ]
    }
  ]
}

CorpusSegmentTarget: object

id: string: Identifier
lang: string: Language
target: string: Target text

Example

{
  "id": "string",
  "lang": "string",
  "target": "string"
}

CorpusSegment: object

id: string: Identifier
lang: string: Language
source: string: Source text
targets: object[]: List of target texts
object id: string Identifier lang: string Language target: string Target text

Example

{
  "id": "string",
  "lang": "string",
  "source": "string",
  "targets": [
    {
      "id": "string",
      "lang": "string",
      "target": "string"
    }
  ]
}

CorpusSegmentListResponse: object

error: ErrorResponse: Error at request level
segments: object[]: List of segments
object id: string Identifier lang: string Language source: string Source text targets: object[] List of target texts object id: string Identifier lang: string Language target: string Target text

Example

{
  "segments": [
    {
      "lang": "en",
      "source": "glass",
      "id": "5649fdb8569da4eca7037230.5649fe48569da4eca7037232",
      "targets": [
        {
          "id": "5649fe48569da4eca7037233",
          "lang": "fr",
          "target": "mirroir"
        },
        {
          "id": "5649fe48569da4eca7037234",
          "lang": "fr",
          "target": "verre"
        }
      ]
    }
  ]
}

CorpusAddSegmentTarget: object

lang: string: Language
target: string: Target text

Example

{
  "lang": "string",
  "target": "string"
}

CorpusAddSegment: object

lang: string: Language
source: string: Source text
targets: object[]: List of targets
object lang: string Language target: string Target text

Example

{
  "lang": "string",
  "source": "string",
  "targets": [
    {
      "lang": "string",
      "target": "string"
    }
  ]
}

CorpusSegmentAddRequest: object

corpusId: string: Corpus identifier
segments: object[]: List of segments to add
object lang: string Language source: string Source text targets: object[] List of targets object lang: string Language target: string Target text

Example

{
  "corpusId": "55afbc9e17fb5791ef7a54ff",
  "segments": [
    {
      "lang": "fr",
      "source": "Exemple de traduction",
      "targets": [
        {
          "lang": "en",
          "target": "Translation example"
        },
        {
          "lang": "en",
          "target": "Example of translation"
        }
      ]
    }
  ]
}

CorpusSegmentAddResponse: object

error: ErrorResponse: Error at request level
segments: string[]: List of added segments ids
string

Example

{
  "segments": [
    "55afbc9e17fb5791ef7a54fe.55b65d8c6b457345fd2e3473",
    "55afbc9e17fb5791ef7a54fe.55b65d9c6c457345fd1f5a8b"
  ]
}

CorpusSegmentDeleteResponse: object

error: ErrorResponse: Error at request level
nbDeleted: integer: Number of deleted segments

Example

{
  "error": {
    "message": "Internal error",
    "statusCode": 500,
    "info": "object"
  },
  "nbDeleted": "integer"
}

CorpusSegmentUpdateResponse: object

error: ErrorResponse: Error at request level
updated: boolean: Segment updated

Example

{
  "error": {
    "message": "Internal error",
    "statusCode": 500,
    "info": "object"
  },
  "updated": "boolean"
}

CorpusSegmentAddTargetRequest: object

corpusId: string: Corpus identifier
segId: string: Segment identifier
targets: object[]: List of targets
object lang: string Language target: string Target text

Example

{
  "corpusId": "55afbc9e17fb5791ef7a54ff",
  "segId": "55afbc9e17fb5791ef7a54fe.55b69c8d6b457345fd2e347f",
  "targets": [
    {
      "lang": "en",
      "target": "added segment one"
    },
    {
      "lang": "en",
      "target": "added segment two"
    }
  ]
}

CorpusSegmentAddTargetResponse: object

error: ErrorResponse: Error at request level
added: boolean: Segment target added

Example

{
  "added": true
}

CorpusSegmentDeleteTargetResponse: object

error: ErrorResponse: Error at request level
deleted: boolean: Segment target deleted

Example

{
  "deleted": true
}

Profile: object

Profile

id: string: Profile UUID (Universally Unique IDentifier)
private: boolean: Public or private profile

Example

{
  "id": "6b80a3f5-aff2-41ba-a5ce-21603738432e",
  "private": false
}

ApiVersionResponse: object

version: string

Example

{
  "version": "1.0.0"
}

ErrorResponse: object

message: string: Readable description of the error
statusCode: integer
info: object: Additional information about the error

Example

{
  "message": "Internal error",
  "statusCode": 500,
  "info": "object"
}

Documentation by Spectacle