REST API v1

Authentication

LingoHub offers two authentication methods with our API:

Token Authentication
HTTP Authentication

The two methods of authentication are supported equally. If you wish to change your authentication details (username, email, password, token) you can do so on your Account Settings page.

Token Authentication

You can add the URL parameter ‘auth_token’ to your request for authentication. You can find your API token value your API on your Account Settings page.

curl -X GET https://api.lingohub.com/v1/projects.json?auth_token=cb26a0249f6953a...

HTTP Authentication

HTTP supports the use of several authentication mechanisms to control access to pages and other resources. These mechanisms are all based around the use of the 401 status code and the WWW-Authenticate response header. The client sends the username and password as unencrypted, base64-encoded text. Because it is unencrypted, it should only be used with HTTPS, as the password can be easily captured and reused over HTTP.
Luckily, LingoHub encrypts all communication with SSL.

curl -X GET https://api.lingohub.com/v1/projects.json -u [email protected]:password

HTTP Status Codes

For each request LingoHub API tries to return suitable HTTP status codes. Response codes for the REST API can be suppressed.

200 OK: Success!
304 Not Modified: No new data was found.
400 Bad Request: Your request was not valid. There will be an explanatory error message. This is the status code; during rate limiting it will be returned
401 Unauthorized: There are missing or incorrect authentication credentials.
403 Forbidden: Your request was understood, but it has been refused. There will be an explanatory error message.This code is used when requests are being refused due to update limits.
404 Not Found: The URI requested is not valid or the requested resource, a user for example, does not exist.
406 Not Acceptable: If an invalid format is specified in the request the search API will return this code.
500 Internal Server Error: Please inform the LingoHub Support team who will investigate as something is damaged.

Error Messages

When the LingoHub API returns error messages, it does so in your requested format. For example, an error from a JSON method might look like this:

{
 "error": "The 'page_size' parameter must be between 1 and 100 but was -1"
}

Request Rate Limiting

To protect LingoHub from abuse the API usage is rate-limited, with additional fair use limits.

Projects

Project's details

Retrieves the detailed information of the specified project

Parameters

accountUrl^{* required} (path)

Account url. It is derived from the name of the organization

projectUrl^{* required} (path)

Project url. It is derived from the project's title.

Responses Description

OK: Returns the project's details including its title, description, locales, etc.

GET /v1/{accountUrl}/projects/{projectUrl}

Response

{
 "title": "string",
 "description": "string",
 "links": [
  {
   "rel": "string",
   "href": "string",
   "hreflang": "string",
   "media": "string",
   "title": "string",
   "type": "string",
   "deprecation": "string",
   "profile": "string",
   "name": "string"
  }
 ],
 "owner_email": "string",
 "project_locales": [
  "string"
 ],
 "created_at": "string",
 "updated_at": "string"
}

Projects' list

Retrieves a list of projects of the authenticated user.

Responses Description

OK: Returns a list of projects. Not only those the user owns, but also those he is collaborating on

GET /v1/projects

Response

{
 "members": [
  {
   "title": "string",
   "links": [
    {
     "rel": "string",
     "href": "string",
     "hreflang": "string",
     "media": "string",
     "title": "string",
     "type": "string",
     "deprecation": "string",
     "profile": "string",
     "name": "string"
    }
   ]
  }
 ],
 "links": [
  {
   "rel": "string",
   "href": "string",
   "hreflang": "string",
   "media": "string",
   "title": "string",
   "type": "string",
   "deprecation": "string",
   "profile": "string",
   "name": "string"
  }
 ]
}

Projects' informations

Retrieves a list of the specified organization's projects with the standard attributes for each of them (title, url...) and the different translation statuses.

Parameters

accountUrl^{* required} (path)

Account url. It is derived from the name of the organization

Responses Description

OK: Returns a list of projects. For each project, the translation statuses of the different resource files is given.

GET /v1/{accountUrl}/projects/status

Response

[
 {
  "title": "string",
  "url": "string",
  "totalCount": "integer",
  "status": {}
 }
]

Project's status

Retrieves the translation's status of the specified project

Parameters

accountUrl^{* required} (path)

Account url. It is derived from the name of the organization

projectUrl^{* required} (path)

Project url. It is derived from the project's title.

Responses Description

OK: Returns a a list of the project's resource files with their different translation statuses

GET /v1/{accountUrl}/projects/{projectUrl}/status

Response

{
 "resourceFiles": [
  {
   "uuid": "string",
   "basename": "string",
   "filePathWithLocalePlaceholder": "string",
   "files": [
    {
     "name": "string",
     "iso2Slug": "string",
     "mimeType": "string",
     "statuses": {},
     "failingLingochecksCount": "integer"
    }
   ]
  }
 ],
 "supportedExportFormats": [
  {
   "id": "string",
   "name": "string"
  }
 ],
 "repositoryConnections": [
  {
   "provider": "string",
   "connected": "boolean"
  }
 ],
 "repositoryConnected": "boolean",
 "pushToRepositoryPossible": "boolean",
 "pushType": "string",
 "oneFileForAllLocales": "boolean",
 "projectType": {
  "id": "string",
  "name": "string",
  "fileExtensions": [
   "string"
  ],
  "detectLocalePossible": "boolean"
 },
 "availableLocales": [
  "string"
 ]
}

Resources

Download resource file

Downloads the requested resource file

Parameters

accountUrl^{* required} (path)

Organization url. It is derived from the name of the organization

projectUrl^{* required} (path)

Project url. It is derived from the project's title.

fileName^{* required} (path)

Name of the resource file to download

path (query)

Path of the resource file to download. if the fileName won't be unique.

iso2_slug (query)

The iso code of the resource file locale. Alias of 'iso2_code'.

iso2_code (query)

The iso code of the resource file locale. Alias of 'iso2_slug'.

source:blankContentHandling (query)

Should the segment be exported if source content is blank. One of: use_source, keep, skip

target:blankContentHandling (query)

Should the segment be exported if target content is blank. One of: use_source, keep, skip

source:filterByStatus (query)

Filter for source segments based on status. One of: ALL, TRANSLATED_AND_APPROVED, APPROVED

target:filterByStatus (query)

Filter for target segments based on status. One of: ALL, TRANSLATED_AND_APPROVED, APPROVED

htmlEncoding (query)

If the segment content holds HTML. How should it be escaped. One of: RAW, ESCAPE, CDATA

encoding (query)

The character set encoding the file should have.

escapeMode (query)

Alias of 'htmlEncoding'

addLocaleInformationToFilename (query)

One of: ALL, TARGETS, NONE

escapeCharacters (query)

If special characters should be escaped. Different behaviour according to resource type

exportTargetComments (query)

Should comments be exported to files of the target language

exportSourceLocale (query)

If a resource file holds multiple languages, this indicates if the source language should be included in this export.

exportHeader (query)

If the file header (if applicable) should be exported.

exportTitle (query)

exportTitle Description

exportDescription (query)

If a resource file holds multiple languages, this indicates if the description of the segments should be exported at all.

projectType (query)

Overrides the project type of the project for this export. Enables to eg. download an iOS file as Android XML or vice versa.

GET /v1/{accountUrl}/projects/{projectUrl}/resources/{fileName}

Resource files list

Returns the list of the resource files of a given project.

Parameters

accountUrl^{* required} (path)

Account url. It is derived from the name of the organization

projectUrl^{* required} (path)

Project url. It is derived from the project's title.

Responses Description

OK: Returns a list of the project's resource files.

GET /v1/{accountUrl}/projects/{projectUrl}/resources

Response

{
 "members": [
  {
   "name": "string",
   "links": [
    {
     "rel": "string",
     "href": "string",
     "hreflang": "string",
     "media": "string",
     "title": "string",
     "type": "string",
     "deprecation": "string",
     "profile": "string",
     "name": "string"
    }
   ],
   "project_locale": "string"
  }
 ],
 "links": [
  {
   "rel": "string",
   "href": "string",
   "hreflang": "string",
   "media": "string",
   "title": "string",
   "type": "string",
   "deprecation": "string",
   "profile": "string",
   "name": "string"
  }
 ]
}

Upload resource file

Uploads the given resource file to the specified project.

Parameters

accountUrl^{* required} (path)

Organization url. It is derived from the name of the organization

projectUrl^{* required} (path)

Project url. It is derived from the project's title.

path (query)

Path where the resource file has to be uploaded

iso2_slug (query)

The iso code of the resource file locale. Alias of 'iso2_code'.

iso2_code (query)

The iso code of the resource file locale. Alias of 'iso2_slug'.

source:createNew (query)

This is a file belongs to the source language: If new segments should be created

source:updateExisting (query)

This is a file belongs to the source language: If changed segments should be updated

source:deactivateMissing (query)

This is a file belongs to the source language: If removed segments should be deactivated

target:createNew (query)

This is a file belongs to a target language: If new segments should be created

target:updateExisting (query)

This is a file belongs to a target language: If changed segments should be updated

target:deactivateMissing (query)

This is a file belongs to a target language: If removed segments should be deactivated

POST /v1/{accountUrl}/projects/{projectUrl}/resources

Sessions

Session

Retrieves session information

Responses Description

OK: Returns an api_key.

POST /v1/sessions

Response

{
 "api_key": "string"
}