Skip to main content

​
API Endpoints

​
EU data center

​
US data center

The API is only accessible via HTTPS and the current version is v2, which results in a base URL like: https://api.phrase.com/v2/ depending on the datacenter.

​
Usage

curl is used primarily to send requests to Phrase Strings in the examples. On most you’ll find a second variant using the Phrase Strings API v2 client that might be more convenient to handle. For further information check its documentation.

​
Use of HTTP Verbs

Phrase Strings API v2 tries to use the appropriate HTTP verb for accessing each endpoint according to REST specification where possible:

​
Identification via User-Agent

You must include the User-Agent header with the name of your application or project. It might be a good idea to include some sort of contact information as well, so that we can get in touch if necessary (e.g. to warn you about Rate-Limiting or badly formed requests). Examples of excellent User-Agent headers:
If you don’t send this header, you will receive a response with 400 Bad Request.

​
Lists

When you request a list of resources, the API will typically only return an array of resources including their most important attributes. For a detailed representation of the resource you should request its detailed representation. Lists are usually paginated.

​
Parameters

Many endpoints support additional parameters, e.g. for pagination. When passing them in a GET request you can send them as HTTP query string parameters:
When performing a POST, PUT, PATCH or DELETE request, we recommend sending parameters that are not already included in the URL, as JSON body:
Encoding parameters as JSON means better support for types (boolean, integer) and usually better readability. Don’t forget to set the correct Content-Type for your request. The Content-Type header is omitted in some of the following examples for better readbility.

​
Errors

​
Request Errors

If a request contains invalid JSON or is missing a required parameter (besides resource attributes), the status 400 Bad Request is returned:

​
Validation Errors

When the validation for a resource fails, the status 422 Unprocessable Entity is returned, along with information on the affected fields:

​
Date Format

Times and dates are returned and expected in ISO 8601 date format:
Instead of ‘Z’ for UTC time zone you can specify your time zone’s locale offset using the following notation:
Example for CET (1 hour behind UTC):
Please note that in HTTP headers, we will use the appropriate recommended date formats instead of ISO 8601.

​
JSONP

The Phrase Strings API supports JSONP for all GET requests in order to deal with cross-domain request issues. Just send a ?callback parameter along with the request to specify the Javascript function name to be called with the response content:
The response will include the normal output for that endpoint, along with a meta section including header data:
To authenticate a JSONP request, you can send a valid access token as the ?access_token parameter along the request:

​
Conditional GET requests / HTTP Caching

Conditional GET requests are currently only supported for the Download a locale and List all translations endpoints.
We will return an ETag or Last-Modified header with most GET requests. When you request a resource we recommend to store this value and submit them on subsequent requests as If-Modified-Since and If-None-Match headers. If the resource has not changed in the meantime, we will return the status 304 Not Modified instead of rendering and returning the resource again. In most cases this is less time-consuming and makes your application/integration faster. Please note that all conditional requests that return a response with status 304 don’t count against your rate limits. See Rate Limiting.