General

Authentication

For authenticated requests to our API, you have to use a generated API key.

Such an Api key can be created by following: How to create an API key?. You can

• set an optional expiration date

• define permissions for the key as you can define permissions for members or your workspace

Please make sure to copy & store the API key at a save place just after creation. For security reasons the API key cannot be viewed at a later time.

The API key has to be passed as Authorization: Bearer <api key> HTTP header.

curl -H 'Authorization: Bearer lingo_...' -X GET https://api.lingohub.com/v1/projects

Resource URLs

We at Lingohub have changed how our URLs are being generated.

Finding the correct Workspace URL

Since then the information isn't quite easy to find how to address your workspace in API V1 URLs. Or follow the instruction here since the project URL includes the workspace information as well.

If you cannnot find the information how to address your workspace in the URL, please contact our support.

Project URL

In order to get the correct string to address your project in an URL, it is best to use the List accessible project endpoint to list information about all of your assignable project.

The "rel": "self" href is the one to use to access a specific project.

HTTP status codes

For each request, the Lingohub API tries to return suitable HTTP status codes. Response codes for the REST API can be suppressed. Below is a list of status codes that are used:

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

• 401 Unauthorized: There are missing or incorrect authentication credentials.

• 403 Forbidden: Your request was understood, but it has been refused due to missing rights. There will be an explanatory error message.

• 404 Not Found: The URI requested is not valid or the requested resource, a project for example, does not exist.

• 406 Not Acceptable: If an invalid format is specified in the request the API will return this code.

• 429 Too Many Requests: If too many requests have been performed in a short time the API rate limit is exceeded and 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 and our customers from abuse, the API usage is rate-limited, with additional fair use limits.

How does it work?

A rate limiter is implemented using a token bucket. The used algorithm is called Leaky Bucket.

Initially, your account has a bucket that can hold up to 100 tokens. Each request adds a token to your bucket. Once the bucket contains 100 tokens, any additional request will overflow the bucket and trigger the rate limit. The system will respond with an error code 429 – API rate limit exceeded. However, the bucket also “leaks” one token per second. This means new requests are possible every second

In total, the system allows up to 3700 requests per hour with the possibility to burst up to 100 requests.

Preventing rate limits

The response header displays how many API calls you have left. Be sure to check how many requests are still available to you before starting a large volume of requests.

Additionally, you can set pauses between the API calls. This way you can be sure that no limit will be reached either since one request per second will be freed up.

If you need any assistance implementing throttling, don’t hesitate to contact our support.