Getting started

​

API Endpoints

​

EU data center

https://api.phrase.com/v2/

​

US data center

https://api.us.app.phrase.com/v2/

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:

User-Agent: Example Mobile App (example@phrase.com)
User-Agent: ACME Inc Python Client (http://example.com/contact)

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:

$ curl -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects?page=2"

When performing a POST, PUT, PATCH or DELETE request, we recommend sending parameters that are not already included in the URL, as JSON body:

$ curl -H 'Content-Type: application/json' -d '{"name":"My new project"}' -u EMAIL_OR_ACCESS_TOKEN https://api.phrase.com/v2/projects

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:

{
  "message": "JSON could not be parsed"
}

​

Validation Errors

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

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "Project",
      "field": "name",
      "message": "can't be blank"
    }
  ]
}

​

Date Format

Times and dates are returned and expected in ISO 8601 date format:

YYYY-MM-DDTHH:MM:SSZ

Instead of ‘Z’ for UTC time zone you can specify your time zone’s locale offset using the following notation:

YYYY-MM-DDTHH:MM:SS±hh:mm

Example for CET (1 hour behind UTC):

2015-03-31T13:00+01:00

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:

$ curl "https://api.phrase.com/v2/projects?callback=myFunction"

The response will include the normal output for that endpoint, along with a meta section including header data:

myFunction({
  {
    "meta": {
      "status": 200,
      ...
    },
    "data": [
      {
        "id": "1234abcd1234abc1234abcd1234abc"
        ...
      }
    ]
  }
});

To authenticate a JSONP request, you can send a valid access token as the ?access_token parameter along the request:

$ curl "https://api.phrase.com/v2/projects?callback=myFunction&access_token=ACCESS-TOKEN"