This document describes the resources that make up the WebTranslateIt API. If you have any problems or requests, please contact support.

This API is considered stable. No breaking changes will occur.

Schema#

All API access is over HTTPS and accessed from:

https://webtranslateit.com/api/

Data may be returned by WebTranslateIt as JSON, YAML and XML, depending on the endpoints.

Authentication#

Authentication is made by so-called API tokens. Older projects get 2 unique legacy keys you can find in the project settings (new projects start in the “API tokens only” mode, see API tokens below):

• the read-write token. A token that allows calls to all API endpoints,
• the read-only token. A token that allows calls to GET API endpoints (Project API, File API and Statistics API).

Send the token in an Authorization: Bearer header, and put current (or the numeric project id) where the token used to go in the URL:

curl -H "Authorization: Bearer PROJECT_TOKEN" \
  "https://webtranslateit.com/api/projects/current.json"

Read-only and read-write tokens work the same way: the token you send decides what the call may do, and a read-only token is refused on anything that writes. The numeric id in the URL must be the id of the project the token belongs to; any other id answers 404. A malformed Bearer header answers 401.

If the URL already carries a token, that token is used and the Authorization header is ignored, so a proxy or gateway that adds its own header does not break existing integrations.

Organization-level endpoints take an Organization API token, which you will find in your organization settings. Send it the same way, with current or the numeric organization id in the URL (/api/organizations/current.json), or with no token in the URL at all when creating a project (POST /api/projects.json).

API tokens#

Besides the keys above (called legacy keys below), you can create API tokens. They are shown once, can be revoked one by one, can expire, and you can see when each was last used. There are two kinds:

• Personal tokens act as you on one project or organization. Create them under Settings → API tokens. A personal token never does more than you can do: write access needs you to be a project manager or organization admin, and it stops working if you lose that role.
• Integration tokens belong to the project or organization, not to a person, so they keep working when someone leaves. Managers create them in the project’s Settings → API tab, and organization admins in the organization’s API tokens tab.

Tokens look like wti_pr_…, wti_pw_…, wti_ir_… or wti_iw_…: personal (p) or integration (i), then read (r) or read-write (w). Tokens are shown only once, when you create them, so copy them right away. Send them in the Authorization: Bearer header, like a legacy key, with current or the numeric id in the URL. They are refused in the URL itself.

curl -H "Authorization: Bearer wti_pr_YOUR_TOKEN" \
  "https://webtranslateit.com/api/projects/current.json"

Each project and organization has an authentication mode, which managers change in the same place:

• Legacy keys only: legacy keys work, API tokens do not. Existing projects keep this mode until a manager changes it.
• Both: legacy keys and API tokens work. Use it while you migrate.
• API tokens only: the mode new projects start in. Only API tokens work. Legacy keys answer 401 with the code legacy_token_disabled. Switching back brings the legacy keys back as brand new keys, and invalidates chart embed and activity feed links handed out before; copy the new ones from the Download tab and the activity page.

Before switching a project to API tokens only, know what the legacy keys were still doing:

• Scripts, CI jobs and .wti files that contain a legacy key stop working. Give them an API token instead.
• Chart embeds and Atom feed URLs that contain the read-only key stop working. The project’s Download tab and activity page hand out signed URLs (?signature=…) that work in every mode and need no key; Renew keys invalidates them.
• Webhook payloads switch their api_url to /api/projects/<project id>/…, which the consumer fetches with its own API token.
• The web app’s own download links (File Manager, terms, people and team exports) use your sign-in, not the keys, so they keep working.

An organization token only works on projects that accept API tokens themselves. A revoked or expired token answers 401.

The token in the URL path (/api/projects/PROJECT_TOKEN.json) still works, and all the examples in these docs use it so they are ready to run. Prefer the header for anything you run for real: URLs end up in server logs, proxies, browser history and CI output, while headers do not. Without the header, current and the numeric id are refused with a 401.

Throughout these docs, PROJECT_TOKEN and ORGANIZATION_TOKEN mark the place to paste your own token, in the URL. Every example is otherwise ready to run:

curl "https://webtranslateit.com/api/projects/PROJECT_TOKEN.json"

const response = await fetch(
  'https://webtranslateit.com/api/projects/PROJECT_TOKEN.json'
)
const { project } = await response.json()

import requests

response = requests.get(
    "https://webtranslateit.com/api/projects/PROJECT_TOKEN.json"
)
project = response.json()["project"]

require 'net/http'
require 'json'

uri = URI('https://webtranslateit.com/api/projects/PROJECT_TOKEN.json')
project = JSON.parse(Net::HTTP.get(uri))['project']

<?php
$ch = curl_init('https://webtranslateit.com/api/projects/PROJECT_TOKEN.json');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$project = json_decode(curl_exec($ch), true)['project'];
curl_close($ch);

{
  "project": {
    "name": "Doughnut",
    "id": 406,
    "source_locale": { "name": "English", "code": "en" },
    "target_locales": [{ "name": "French", "code": "fr" }],
    "project_files": []
  }
}

Treat a read-write token like a password: it can delete files and segments, so keep it out of client-side code and out of version control.

Rate Limiting#

We rate limit the API endpoints based on IPs to 25 req/sec. Subsequent requests are ignored and get a 429 response.

CORS#

All API endpoints are accessible via Cross-origin resource sharing (CORS), which means that all endpoints can be requested from another domain from which the first resource was served.

HTTP Verbs#

The WebTranslateIt API uses appropriate HTTP verbs for each action.

• GET Used for retrieving resources.
• POST Used for creating resources.
• PATCH Used for replacing resources (although PUT can also be used).
• DELETE Used for deleting resources.

Endpoints#

11 different resources can be accessed. Their specification is separated into different sections in the documentation:

• Project API
• User API
• File API
• Stats API
• Locale API
• String API
• Translation API
• TermBase API
• TermBase Translation API
• Organization API
• Collaboration API

We made a ruby client that uses these endpoints. Use it or take a look at it as an implementation example.