Skip to main content

​
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:
VerbDescription
GETRetrieve one or multiple resources
POSTCreate a resource
PUTUpdate a resource
PATCHUpdate a resource (partially)
DELETEDelete 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: Example Mobile App ([email protected])
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"