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)
zh-Hans Chinese (Simplified)
zh-Hant Chinese (Traditional)
Schemes: https
Version: 1.0.1

Authentication

accessToken

"Bearer access_token" OR "Key api_key"

type
apiKey
name
Authorization
in
header

apiKey

API Key

type
apiKey
name
key
in
query

Paths

Get API version

GET /resources/corpus/apiVersion

Current version for this API

callback: string
in query

Javascript callback function name for JSONP Support

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"
}

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.

callback: string
in query

Javascript callback function name for JSONP Support

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"
    }
  ]
}

Add empty corpus

POST /resources/corpus/add

Add a new empty corpus.

name: string
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)

callback: string
in query

Javascript callback function name for JSONP Support

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"
  }
}

Import corpus

POST /resources/corpus/import

Add a new corpus from an existing corpus.

name: string
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)

callback: string
in query

Javascript callback function name for JSONP Support

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"
  }
}

Check corpus existence

GET /resources/corpus/exists

Check if a corpus exists

name: string
in query

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

callback: string
in query

Javascript callback function name for JSONP Support

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
}

Get corpus details

GET /resources/corpus/details

Get detailed information about a corpus.

corpusId: string
in query

Corpus identifier

callback: string
in query

Javascript callback function name for JSONP Support

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"
}

Update corpus properties

POST /resources/corpus/update

Update properties of a corpus.

corpusId: string
in query

Corpus identifier

name: string
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)

callback: string
in query

Javascript callback function name for JSONP Support

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
}

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

callback: string
in query

Javascript callback function name for JSONP Support

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"

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

callback: string
in query

Javascript callback function name for JSONP Support

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"
    }
  ]
}

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

callback: string
in query

Javascript callback function name for JSONP Support

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"
        }
      ]
    }
  ]
}

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

callback: string
in query

Javascript callback function name for JSONP Support

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"
        }
      ]
    }
  ]
}

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

callback: string
in query

Javascript callback function name for JSONP Support

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"
  ]
}

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)

callback: string
in query

Javascript callback function name for JSONP Support

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"
}

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.

callback: string
in query

Javascript callback function name for JSONP Support

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"
}

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

callback: string
in query

Javascript callback function name for JSONP Support

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
}

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)

callback: string
in query

Javascript callback function name for JSONP Support

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
}

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"
}