API: Get started

Last updated: October 06, 2023Author: Jakub Pomykała

SimpleLocalize API gives you an ability to create your own integrations. API provides an endpoint to create, update, read, and delete translations. Optionally, you can import translations and export translations.

OpenAPI Specification

SimpleLocalize API is described with OpenAPI 3.x Specification and can be used to generate client libraries for your favorite programming language or import to REST Client, e.g.: Postman or Insomnia. We also provide a Swagger UI to test the API.

SimpleLocalize OpenAPI Swagger UI

REST API authorization

Each request which adds or updates the translation data needs to be authorized. Every request sent to such endpoint needs to have X-SimpleLocalize-Token header with API Key value. The API Key can be found in the 'Integrations > Project credentials > API Key'.

SimpleLocalize: Project API Key location

Please note that the API Access is rate-limited, and you should not use it to fetch translations for every end-user. Use Translation Hosting instead.

Translation Hosting authorization

Each request for Translation Hosting resources requires a project token. The project token can be found in the 'Integrations > Project credentials > Project Token', it can be exposed and used in client-side applications.

SimpleLocalize: Project Token location

Personal Tokens

Personal tokens are used to authorize requests to the Projects API and you can generate them in account settings section. Each user can have up to 5 personal tokens. Requests sent to endpoint that requires Personal Tokens need to have Authorization header with the token as a value.

SimpleLocalize: Personal Tokens location

Rate limits

All API endpoints are rate-limited to 60 req/minute (per IP address) and 300 req/minute (per project). Some endpoints have additional limits:

  • Export and import endpoints are limited to 60 req/minute (per project),
  • Publication endpoint is limited to 10 req/minute (per project),
  • POST /api/v1/translations endpoint is limited to 60 req/minute (per project).

If you exceed this limit, you will get a response with 429 HTTP code. When you receive this response, wait some time and try again. If you get the same error again, please wait longer between retries (e.g., double the wait time). Repeat this until the request succeeds. In some cases, you might get a CORS error if the request is sent from the browser, because OPTIONS requests are also rate-limited.

Cross-Origin Resource Sharing (CORS)

SimpleLocalize API supports CORS for all API endpoints. You can read more about it here.