API v2

PhraseApp API

PhraseApp is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in PhraseApp for your account.

Schema

The API is only accessible via HTTPS, the base URL is https://api.phraseapp.com/, and the current version is v2 which results in the base URL for all requests: https://api.phraseapp.com/api/v2/.

Usage

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

Use of HTTP Verbs

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

Verb Description
GET Retrieve one or multiple resources
POST Create a resource
PUT Update a resource
PATCH Update a resource (partially)
DELETE Delete a resource

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: Frederiks Mobile App (frederik@phraseapp.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.phraseapp.com/api/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.phraseapp.com/api/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.

Authentication

For more detailled information on authentication, check out the API v2 Authentication Guide.

There are two different ways to authenticate when performing API requests:

  • E-Mail and password
  • Oauth Access Token

E-Mail and password

To get started easily, you can use HTTP Basic authentication with your email and password:

curl -u username:password "https://api.phraseapp.com/api/v2/projects"

OAuth via Access Tokens

You can create and manage access tokens in your profile settings in Translation Center or via the Authorizations API.

Simply pass the access token as the username of your request:

curl -u ACCESS_TOKEN: "https://api.phraseapp.com/api/v2/projects"

or send the access token via the Authorization header field:

curl -H "Authorization: token ACCESS_TOKEN" https://api.phraseapp.com/api/v2/projects

For more detailled information on authentication, check out the API v2 Authentication Guide.

Pagination

Endpoints that return a list or resources will usually return paginated results and include 25 items by default. To access further pages, use the page parameter:

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

Some endpoints also allow a custom page size by using the per_page parameter:

curl -u EMAIL_OR_ACCESS_TOKEN "https://api.phraseapp.com/api/v2/projects?page=2&per_page=50"

Unless specified otherwise in the description of the respective endpoint, per_page allows you to specify a page size up to 100 items.

We provide you with pagination URLs in the Link Header field. Make use of this information to avoid building pagination URLs yourself.

Link: <https://api.phraseapp.com/api/v2/projects?page=1>; rel="first", <https://api.phraseapp.com/api/v2/projects?page=3>; rel="prev", <https://api.phraseapp.com/api/v2/projects?page=5>; rel="next", <https://api.phraseapp.com/api/v2/projects?page=9>; rel="last"

Possible rel values are:

Value Description
next URL of the next page of results
last URL of the last page of results
first URL of the first page of results
prev URL of the previous page of results

Rate Limiting

Some API endpoints are subject to rate limiting to ensure good performance for all customers. The rate limit is calculated per project:

  • 200 requests per 5 minutes
  • 2 concurrent (parallel) requests

For your convenience we send information on the current rate limit within the response headers:

Header Description
X-Rate-Limit-Limit Number of max requests allowed in the current time period
X-Rate-Limit-Remaining Number of remaining requests in the current time period
X-Rate-Limit-Reset Timestamp of end of current time period as UNIX timestamp

If you should run into the rate limit, you will receive the HTTP status code 429: Too many requests.

If you should need higher rate limits, contact us.

Conditional GET requests / HTTP Caching

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. We recommend to use this mechanism whenever possible.

curl -i -u EMAIL_OR_ACCESS_TOKEN "https://api.phraseapp.com/api/v2/projects"
HTTP/1.1 200 OK
ETag: "abcd1234abcdefefabcd1234efab1234"
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
Status: 200 OK

curl -i -u EMAIL_OR_ACCESS_TOKEN "https://api.phraseapp.com/api/v2/projects" -H 'If-None-Match: "abcd1234abcdefefabcd1234efab1234"'
HTTP/1.1 304 Not Modified
ETag: "abcd1234abcdefefabcd1234efab1234"
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
Status: 304 Not Modified

curl -i -u EMAIL_OR_ACCESS_TOKEN "https://api.phraseapp.com/api/v2/projects" -H "If-Modified-Since: Wed, 28 Jan 2015 15:31:30 UTC"
HTTP/1.1 304 Not Modified
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
Status: 304 Not Modified

JSONP

The PhraseApp 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.phraseapp.com/api/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.phraseapp.com/api/v2/projects?callback=myFunction&access_token=ACCESS-TOKEN"

Supported formats

Check out the extensive format guide for information on all supported localization file types you can manage with PhraseApp.

Table of contents

General

Formats