Phrase API Reference

Phrase 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 Phrase for your account.

Schema

API Endpoint

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

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

Usage

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

Use of HTTP Verbs

Phrase 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.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.

Authentication

For more detailed 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.phrase.com/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.phrase.com/v2/projects"

or send the access token via the Authorization header field:

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

For more detailed 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.phrase.com/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.phrase.com/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.

Link-Headers

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

Link: ; rel="first", ; rel="prev", ; rel="next", ; 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

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

500 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.phrase.com/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.phrase.com/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.phrase.com/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 Phrase 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"

Authentication

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

E-Mail and password
Oauth Access Token

E-Mail and password

To hit the ground running with the Phrase API, just use HTTP Basic authentication with your email and password:

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

Every HTTP client ships with built-in support for HTTP Basic authentication, so this is the easiest way to get started.

If you do not enter your password in the command, cURL will prompt you for it.

OAuth via Access Tokens

OAuth is preferred over Basic authentication because OAuth tokens can be limited to specific scopes, and can be revoked by users at any time. You can create and manage OAuth access tokens in your profile settings in Translation Center or via the Authorizations API.

Send via Basic authentication

To authorize using Basic authentication, simply pass the access token as the username of your request:

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

You must not provide a password. Put a colon after the actual access token to skip the password prompt in cURL.

Send via header

We recommend sending the access token via the Authorization header field when possible:

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

Send via parameter

As JSONP (and other) requests cannot send HTTP Basic Auth credentials, a special query parameter access_token can be used:

curl "https://api.phrase.com/v2/projects?access_token=ACCESS_TOKEN"

You should only use this transport method if sending the authentication via header or Basic authentication is not possible.

Two-Factor-Authentication

Users with Two-Factor-Authentication enabled have to send a valid token along their request with certain authentication methods (such as Basic authentication). The necessity of a Two-Factor-Authentication token is indicated by the X-PhraseApp-OTP: required; :MFA-type header in the response. The :MFA-typefield indicates the source of the token, e.g. app (refers to your Authenticator application):

X-PhraseApp-OTP: required; app

To provide a Two-Factor-Authentication token you can simply send it in the header of the request:

curl -H "X-PhraseApp-OTP: MFA-TOKEN" -u EMAIL https://api.phrase.com/v2/projects

Since Two-Factor-Authentication tokens usually expire quickly, we recommend using an alternative authentication method such as OAuth access tokens.

Multiple Accounts

Some endpoints require the account ID to be specified if the authenticated user is a member of multiple accounts. You can find the eight-digit account ID inside Translation Center by switching to the desired account and then visiting the account details page. If required, you can specify the account just like a normal parameter within the request.

Usage examples

Learn how to work more efficiently with Phrase API v2 with these workflow-oriented examples.

Find excluded translations with a certain content

GET /v2/projects/:project_id/translations

List excluded translations for the given project which start with the term PhraseApp.

Parameters

Name	Type	Description
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `reviewed:{true\|false}` for reviewed status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20excluded:true" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp translations list <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* excluded:true'

Find unverified translations with a certain content

GET /v2/projects/:project_id/translations

List unverified translations for the given project which start with the term PhraseApp and are not verified.

Parameters

Name	Type	Description
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `reviewed:{true\|false}` for reviewed status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20unverified:true" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp translations list <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* unverified:true'

Verify translations selected by query

PATCH /v2/projects/:project_id/translations/verify

Verify all translations that are matching the query my dog.

Parameters

Name	Type	Description
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `reviewed:{true\|false}` for reviewed status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/verify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"my dog unverified:true","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'

phraseapp translations verify <project_id> \
--query "my dog unverified:true" \
--sort updated_at \
--order desc

Find recently updated keys

GET /v2/projects/:project_id/keys

Find updated keys with with the updated_at qualifier like updated_at:>=2013-02-21T00:00:00Z. This example returns keys that have been updated on or after 2013-02-21.

Parameters

Name	Type	Description
`sort` optional	`string`	Sort by field. Can be one of: name, created_at, updated_at. Default: name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`locale_id`

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?sort=updated_at&order=desc&q=updated_at:%3E=2013-02-21T00:00:00Z&locale_id=abcd1234abcd1234abcd1234abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp keys list <project_id> \
--sort updated_at \
--order desc \
--query "updated_at:>=2013-02-21T00:00:00Z" \
--locale-id abcd1234abcd1234abcd1234abcd1234

Find keys with a certain tag

GET /v2/projects/:project_id/keys

Keys with certain tags can be filtered with the qualifier tags:.

Parameters

Name	Type	Description
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=tags:admin" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp keys list <project_id> \
--query "tags:admin"

Add tags to collection of keys

PATCH /v2/projects/:project_id/keys/tag

Add the tags landing-page and release-1.2 to all keys that start with dog and are translated in the locale abcd1234abcd1234abcd1234abcd1234.

Parameters

Name	Type	Description
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`tags`	`string`	Tag or comma-separated list of tags to add to the matching collection of keys
`locale_id` optional	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/tag" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp keys tag <project_id> \
--query 'dog* translated:true' \
--tags landing-page,release-1.2 \
--locale-id abcd1234abcd1234abcd1234abcd1234

Remove tags from collection of keys

PATCH /v2/projects/:project_id/keys/untag

Remove the tags landing-page and release-1.2 from all keys that start with dog and are translated in the locale abcd1234abcd1234abcd1234abcd1234.

Parameters

Name	Type	Description
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`tags`	`string`	Tag or comma-separated list of tags to remove from the matching collection of keys
`locale_id` optional	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/untag" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp keys untag <project_id> \
--query 'dog* translated:true' \
--tags landing-page,release-1.2 \
--locale-id abcd1234abcd1234abcd1234abcd1234

Find keys with broad text match

GET /v2/projects/:project_id/keys

Example query my dog

Parameters

Name	Type	Description
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.

Matches

My dog is lazy
my dog is lazy
angry dog in my house

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=my%20dog" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp keys list <project_id> \
--query "my dog"

Find keys with exact text match

GET /v2/projects/:project_id/keys

Example query "my dog is lazy"

Parameters

Name	Type	Description
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.

Matches

~~My dog is lazy~~
my dog is lazy
~~angry dog in my house~~

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=my%20dog%20is%20lazy" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp keys list <project_id> \
--query "my dog is lazy"

Find keys with wildcard character matching

GET /v2/projects/:project_id/keys

Example query *dog is*

Parameters

Name	Type	Description
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.

Matches

My dog is lazy
my dog is lazy
~~angry dog in my house~~

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?q=*dog%20is*" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp keys list <project_id> \
--query '*dog is*'

Upload an Excel file with several translations

POST /v2/projects/:project_id/uploads

Suppose you have an excel file where the 'A' column contains the key names, the 'B' column contains English translations, the 'C' column contains German translations and the 'D' column contains comments. Furthermore, the actual content starts in the second row, since the first row is reserved for a header. You can upload this file and import all translations at once!

Parameters

Name	Type	Description
`file`	`file`	File to be imported
`file_format`	`string`	File format. Auto-detected when possible and not specified.
`locale_mapping[en]`	`string`	Name of the column containing translations for locale en.
`locale_mapping[de]`	`string`	Name of the column containing translations for locale de.
`format_options[comment_column]`	`string`	Name of the column containing descriptions for keys.
`format_options[key_name_column]`	`string`	Name of the column containing the names of the keys.
`format_options[first_content_row]`	`string`	Name of the first row containing actual translations.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/uploads" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F file=@/path/to/my/file.xlsx \
  -F file_format=xlsx \
  -F locale_mapping[en]=B \
  -F locale_mapping[de]=C \
  -F format_options[comment_column]=D \
  -F format_options[key_name_column]=A \
  -F format_options[first_content_row]=2

phraseapp upload create <project_id> \
--file /path/to/my/file.xlsx \
--file-format xlsx \
--locale-mapping[en] B \
--locale-mapping[de] C \
--format-options[comment-column] D \
--format-options[key-name-column] A \
--format-options[first-content-row] 2

Projects

List projects

GET /v2/projects

List all projects the current user has access to.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/projects" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp projects list

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "project_image_url": "http://assets.example.com/project.png",
    "account": "account",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "project_image_url": "http://assets.example.com/project.png",
    "account": "account",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single project

GET /v2/projects/:id

Get details on a single project.

Example Request

curl "https://api.phrase.com/v2/projects/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp project show <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "My Android Project",
  "main_format": "xml",
  "project_image_url": "http://assets.example.com/project.png",
  "account": "account",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "slug": "my-android-project",
  "shares_translation_memory": true
}

Create a project

POST /v2/projects

Create a new project.

Parameters

Name	Type	Description
`name`	`string`	Name of the project
`main_format` optional	`string`	Main file format specified by its API Extension name. Used for locale downloads if no format is specified. For API Extension names of available file formats see Format Guide or our Formats API Endpoint.
`shares_translation_memory` optional	`boolean`	Indicates whether the project should share the account's translation memory Default: false
`project_image` optional	`file`	Image to identify the project
`remove_project_image` optional	`boolean`	Indicates whether the project image should be deleted. Default: false
`account_id` optional	`string`	Account ID to specify the actual account the project should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/projects" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F name=My%20Android%20Project \
  -F main_format=yml \
  -F shares_translation_memory=true \
  -F project_image=@/path/to/my/project-screenshot.png \
  -F account_id=abcd1234

phraseapp project create \
--name "My Android Project" \
--main-format yml \
--shares-translation-memory true \
--project-image /path/to/my/project-screenshot.png \
--account-id abcd1234

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "My Android Project",
  "main_format": "xml",
  "project_image_url": "http://assets.example.com/project.png",
  "account": "account",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "slug": "my-android-project",
  "shares_translation_memory": true
}

Update a project

PATCH /v2/projects/:id

Update an existing project.

Parameters

Name	Type	Description
`name`	`string`	Name of the project
`main_format` optional	`string`	Main file format specified by its API Extension name. Used for locale downloads if no format is specified. For API Extension names of available file formats see Format Guide or our Formats API Endpoint.
`shares_translation_memory` optional	`boolean`	Indicates whether the project should share the account's translation memory Default: false
`project_image` optional	`file`	Image to identify the project
`remove_project_image` optional	`boolean`	Indicates whether the project image should be deleted. Default: false
`account_id` optional	`string`	Account ID to specify the actual account the project should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/projects/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -F name=My%20Android%20Project \
  -F main_format=yml \
  -F shares_translation_memory=true \
  -F project_image=@/path/to/my/project-screenshot.png \
  -F account_id=abcd1234

phraseapp project update <id> \
--name "My Android Project" \
--main-format yml \
--shares-translation-memory true \
--project-image /path/to/my/project-screenshot.png \
--account-id abcd1234

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "My Android Project",
  "main_format": "xml",
  "project_image_url": "http://assets.example.com/project.png",
  "account": "account",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "slug": "my-android-project",
  "shares_translation_memory": true
}

Delete a project

DELETE /v2/projects/:id

Delete an existing project.

Example Request

curl "https://api.phrase.com/v2/projects/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp project delete <id>

Response

Status: 204

Locales

List locales

GET /v2/projects/:project_id/locales

List all locales for the given project.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/locales?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp locales list <project_id> \
--branch my-feature-branch

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "de",
    "code": "de-DE",
    "default": true,
    "main": false,
    "rtl": false,
    "plural_forms": [
      "zero",
      "one",
      "other"
    ],
    "source_locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "en",
      "code": "en-GB"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "de",
    "code": "de-DE",
    "default": true,
    "main": false,
    "rtl": false,
    "plural_forms": [
      "zero",
      "one",
      "other"
    ],
    "source_locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "en",
      "code": "en-GB"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single locale

GET /v2/projects/:project_id/locales/:id

Get details on a single locale for a given project.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/locales/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp locale show <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "de",
  "code": "de-DE",
  "default": true,
  "main": false,
  "rtl": false,
  "plural_forms": [
    "zero",
    "one",
    "other"
  ],
  "source_locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "en",
    "code": "en-GB"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "statistics": {
    "keys_total_count": 2120,
    "keys_untranslated_count": 100,
    "words_total_count": 3102102,
    "translations_completed_count": 1920,
    "translations_unverified_count": 32,
    "unverified_words_count": 129,
    "missing_words_count": 3920
  }
}

Create a locale

POST /v2/projects/:project_id/locales

Create a new locale.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`name`	`string`	Locale name
`code`	`string`	Locale ISO code
`default` optional	`boolean`	Indicates whether locale is the default locale. If set to true, the previous default locale the project is no longer the default locale. Default: false
`main` optional	`boolean`	Indicates whether locale is a main locale. Main locales are part of the Verification System feature. Default: false
`rtl` optional	`boolean`	Indicates whether locale is a RTL (Right-to-Left) locale. Default: auto-detected
`source_locale_id` optional	`id`	Source locale. Can be the name or public id of the locale. Preferred is the public id.
`unverify_new_translations` optional	`boolean`	Indicates that new translations for this locale should be marked as unverified. Part of the Advanced Workflows feature. Default: false
`unverify_updated_translations` optional	`boolean`	Indicates that updated translations for this locale should be marked as unverified. Part of the Advanced Workflows feature. Default: false
`autotranslate` optional	`boolean`	If set, translations for this locale will be fetched automatically, right after creation. Default: false

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/locales" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","name":"de","code":"de-DE","source_locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp locale create <project_id> \
--branch my-feature-branch \
--name de \
--code de-DE \
--source-locale-id abcd1234abcd1234abcd1234abcd1234

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "de",
  "code": "de-DE",
  "default": true,
  "main": false,
  "rtl": false,
  "plural_forms": [
    "zero",
    "one",
    "other"
  ],
  "source_locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "en",
    "code": "en-GB"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "statistics": {
    "keys_total_count": 2120,
    "keys_untranslated_count": 100,
    "words_total_count": 3102102,
    "translations_completed_count": 1920,
    "translations_unverified_count": 32,
    "unverified_words_count": 129,
    "missing_words_count": 3920
  }
}

Update a locale

PATCH /v2/projects/:project_id/locales/:id

Update an existing locale.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`name`	`string`	Locale name
`code`	`string`	Locale ISO code
`default` optional	`boolean`	Indicates whether locale is the default locale. If set to true, the previous default locale the project is no longer the default locale. Default: false
`main` optional	`boolean`	Indicates whether locale is a main locale. Main locales are part of the Verification System feature. Default: false
`rtl` optional	`boolean`	Indicates whether locale is a RTL (Right-to-Left) locale. Default: auto-detected
`source_locale_id` optional	`id`	Source locale. Can be the name or public id of the locale. Preferred is the public id.
`unverify_new_translations` optional	`boolean`	Indicates that new translations for this locale should be marked as unverified. Part of the Advanced Workflows feature. Default: false
`unverify_updated_translations` optional	`boolean`	Indicates that updated translations for this locale should be marked as unverified. Part of the Advanced Workflows feature. Default: false
`autotranslate` optional	`boolean`	If set, translations for this locale will be fetched automatically, right after creation. Default: false

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/locales/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","name":"de","code":"de-DE","source_locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp locale update <project_id> <id> \
--branch my-feature-branch \
--name de \
--code de-DE \
--source-locale-id abcd1234abcd1234abcd1234abcd1234

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "de",
  "code": "de-DE",
  "default": true,
  "main": false,
  "rtl": false,
  "plural_forms": [
    "zero",
    "one",
    "other"
  ],
  "source_locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "en",
    "code": "en-GB"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "statistics": {
    "keys_total_count": 2120,
    "keys_untranslated_count": 100,
    "words_total_count": 3102102,
    "translations_completed_count": 1920,
    "translations_unverified_count": 32,
    "unverified_words_count": 129,
    "missing_words_count": 3920
  }
}

Delete a locale

DELETE /v2/projects/:project_id/locales/:id

Delete an existing locale.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/locales/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp locale delete <project_id> <id> \
--branch my-feature-branch

Response

Status: 204

Download a locale

GET /v2/projects/:project_id/locales/:id/download

Download a locale in a specific file format.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`file_format`	`string`	File format name. See the format guide for all supported file formats.
`tags` optional	`string`	Limit results to keys tagged with a list of comma separated tag names.
`tag` optional	`string`	This parameter is deprecated. Please use the "tags" parameter instead
`include_empty_translations` optional	`boolean`	Indicates whether keys without translations should be included in the output as well. Default: false
`include_translated_keys` optional	`boolean`	Include translated keys in the locale file. Use in combination with include_empty_translations to obtain only untranslated keys. Default: true
`keep_notranslate_tags` optional	`boolean`	Indicates whether [NOTRANSLATE] tags should be kept. Default: false
`convert_emoji` optional	`boolean`	Indicates whether Emoji symbols should be converted to actual Emojis. Working with Emojis. Default: false
`format_options` optional	`hash`	Additional formatting and render options. See the format guide for a list of options available for each format. Specify format options like this: `...&format_options[foo]=bar`
`encoding` optional	`string`	Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1".
deprecated `skip_unverified_translations` optional	`boolean`	Indicates whether the locale file should skip all unverified translations. This parameter is deprecated and should be replaced with `include_unverified_translations`. Default: false
`include_unverified_translations` optional	`boolean`	if set to false unverified translations are excluded Default: true
`use_last_reviewed_version` optional	`boolean`	If set to true the last reviewed version of a translation is used. This is only available if the review workflow (currently in beta) is enabled for the project. Default: false
`fallback_locale_id` optional	`string`	If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the public ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to `true`.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/locales/:id/download?branch=my-feature-branch&file_format=yml&tags=feature1,feature2&tag=feature" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp locale download <project_id> <id> \
--branch my-feature-branch \
--file-format yml \
--tags feature1,feature2 \
--tag feature

Response

Status: 200
en:
  title: a Title
  page:
    other_content: Other content"

Keys

List keys

GET /v2/projects/:project_id/keys

List all keys for the given project. Alternatively you can POST requests to /search.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`sort` optional	`string`	Sort by field. Can be one of: name, created_at, updated_at. Default: name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`locale_id` optional	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys?branch=my-feature-branch&sort=updated_at&order=desc&q=mykey*%20translated:true&locale_id=abcd1234abcd1234abcd1234abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp keys list <project_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'mykey* translated:true' \
--locale-id abcd1234abcd1234abcd1234abcd1234

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "description": "My description for this key...",
    "name_hash": "1b31d2580ce324f246f66b3be00ed399",
    "plural": false,
    "tags": [
      "awesome-feature",
      "needs-proofreading"
    ],
    "data_type": "string",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "description": "My description for this key...",
    "name_hash": "1b31d2580ce324f246f66b3be00ed399",
    "plural": false,
    "tags": [
      "awesome-feature",
      "needs-proofreading"
    ],
    "data_type": "string",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Search keys

POST /v2/projects/:project_id/keys/search

Search keys for the given project matching query.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`sort` optional	`string`	Sort by field. Can be one of: name, created_at, updated_at. Default: name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`locale_id` optional	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/search" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","sort":"updated_at","order":"desc","q":"mykey* translated:true","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp keys search <project_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'mykey* translated:true' \
--locale-id abcd1234abcd1234abcd1234abcd1234

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "description": "My description for this key...",
    "name_hash": "1b31d2580ce324f246f66b3be00ed399",
    "plural": false,
    "tags": [
      "awesome-feature",
      "needs-proofreading"
    ],
    "data_type": "string",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "description": "My description for this key...",
    "name_hash": "1b31d2580ce324f246f66b3be00ed399",
    "plural": false,
    "tags": [
      "awesome-feature",
      "needs-proofreading"
    ],
    "data_type": "string",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single key

GET /v2/projects/:project_id/keys/:id

Get details on a single key for a given project.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp key show <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "home.index.headline",
  "description": "My description for this key...",
  "name_hash": "1b31d2580ce324f246f66b3be00ed399",
  "plural": false,
  "tags": [
    "awesome-feature",
    "needs-proofreading"
  ],
  "data_type": "string",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "name_plural": "home.index.headlines",
  "comments_count": 2,
  "max_characters_allowed": 140,
  "screenshot_url": "http://assets.example.com/screenshot.png",
  "unformatted": false,
  "xml_space_preserve": false,
  "original_file": "",
  "format_value_type": "",
  "creator": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  }
}

Create a key

POST /v2/projects/:project_id/keys

Create a new key.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`name`	`string`	Key name
`description` optional	`string`	Key description (usually includes contextual information for translators)
`plural` optional	`boolean`	Indicates whether key supports pluralization Default: false
`name_plural` optional	`string`	Plural name for the key (used in some file formats, e.g. Gettext)
`data_type` optional	`string`	Type of the key. Can be one of the following: string, number, boolean, number, array. Default: string
`tags` optional	`string`	List of tags separated by comma to be associated with the key.
`max_characters_allowed` optional	`integer`	Max. number of characters translations for this key can have.
deprecated `screenshot` optional	`file`	Screenshot/image for the key. This parameter is deprecated. Please use the Screenshots endpoint instead.
deprecated `remove_screenshot` optional	`boolean`	Indicates whether the screenshot will be deleted. This parameter is deprecated. Please use the Screenshots endpoint instead. Default: false
`unformatted` optional	`boolean`	Indicates whether the key should be exported as "unformatted". Supported by Android XML and other formats. Default: false
`xml_space_preserve` optional	`boolean`	Indicates whether the key should be exported with "xml:space=preserve". Supported by several XML-based formats. Default: false
`original_file` optional	`string`	Original file attribute. Used in some formats, e.g. XLIFF.
`localized_format_string` optional	`string`	NSStringLocalizedFormatKey attribute. Used in .stringsdict format.
`localized_format_key` optional	`string`	NSStringLocalizedFormatKey attribute. Used in .stringsdict format.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F branch=my-feature-branch \
  -F name=home.index.headline \
  -F description=Some%20description%20worth%20knowing... \
  -F name_plural=home.index.headlines \
  -F data_type=number \
  -F tags=awesome-feature,needs-proofreading \
  -F max_characters_allowed=140 \
  -F screenshot=@/path/to/my/screenshot.png

phraseapp key create <project_id> \
--branch my-feature-branch \
--name home.index.headline \
--description "Some description worth knowing..." \
--name-plural home.index.headlines \
--data-type number \
--tags awesome-feature,needs-proofreading \
--max-characters-allowed 140 \
--screenshot /path/to/my/screenshot.png

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "home.index.headline",
  "description": "My description for this key...",
  "name_hash": "1b31d2580ce324f246f66b3be00ed399",
  "plural": false,
  "tags": [
    "awesome-feature",
    "needs-proofreading"
  ],
  "data_type": "string",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "name_plural": "home.index.headlines",
  "comments_count": 2,
  "max_characters_allowed": 140,
  "screenshot_url": "http://assets.example.com/screenshot.png",
  "unformatted": false,
  "xml_space_preserve": false,
  "original_file": "",
  "format_value_type": "",
  "creator": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  }
}

Update a key

PATCH /v2/projects/:project_id/keys/:id

Update an existing key.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`name`	`string`	Key name
`description` optional	`string`	Key description (usually includes contextual information for translators)
`plural` optional	`boolean`	Indicates whether key supports pluralization Default: false
`name_plural` optional	`string`	Plural name for the key (used in some file formats, e.g. Gettext)
`data_type` optional	`string`	Type of the key. Can be one of the following: string, number, boolean, number, array. Default: string
`tags` optional	`string`	List of tags separated by comma to be associated with the key.
`max_characters_allowed` optional	`integer`	Max. number of characters translations for this key can have.
deprecated `screenshot` optional	`file`	Screenshot/image for the key. This parameter is deprecated. Please use the Screenshots endpoint instead.
deprecated `remove_screenshot` optional	`boolean`	Indicates whether the screenshot will be deleted. This parameter is deprecated. Please use the Screenshots endpoint instead. Default: false
`unformatted` optional	`boolean`	Indicates whether the key should be exported as "unformatted". Supported by Android XML and other formats. Default: false
`xml_space_preserve` optional	`boolean`	Indicates whether the key should be exported with "xml:space=preserve". Supported by several XML-based formats. Default: false
`original_file` optional	`string`	Original file attribute. Used in some formats, e.g. XLIFF.
`localized_format_string` optional	`string`	NSStringLocalizedFormatKey attribute. Used in .stringsdict format.
`localized_format_key` optional	`string`	NSStringLocalizedFormatKey attribute. Used in .stringsdict format.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -F branch=my-feature-branch \
  -F name=home.index.headline \
  -F description=Some%20description%20worth%20knowing... \
  -F name_plural=home.index.headlines \
  -F data_type=number \
  -F tags=awesome-feature,needs-proofreading \
  -F max_characters_allowed=140 \
  -F screenshot=@/path/to/my/screenshot.png

phraseapp key update <project_id> <id> \
--branch my-feature-branch \
--name home.index.headline \
--description "Some description worth knowing..." \
--name-plural home.index.headlines \
--data-type number \
--tags awesome-feature,needs-proofreading \
--max-characters-allowed 140 \
--screenshot /path/to/my/screenshot.png

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "home.index.headline",
  "description": "My description for this key...",
  "name_hash": "1b31d2580ce324f246f66b3be00ed399",
  "plural": false,
  "tags": [
    "awesome-feature",
    "needs-proofreading"
  ],
  "data_type": "string",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "name_plural": "home.index.headlines",
  "comments_count": 2,
  "max_characters_allowed": 140,
  "screenshot_url": "http://assets.example.com/screenshot.png",
  "unformatted": false,
  "xml_space_preserve": false,
  "original_file": "",
  "format_value_type": "",
  "creator": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  }
}

Delete a key

DELETE /v2/projects/:project_id/keys/:id

Delete an existing key.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp key delete <project_id> <id> \
--branch my-feature-branch

Response

Status: 204

Delete collection of keys

DELETE /v2/projects/:project_id/keys

Delete all keys matching query. Same constraints as list. Please limit the number of affected keys to about 1,000 as you might experience timeouts otherwise.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`locale_id` optional	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch","q":"mykey* translated:true","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp keys delete <project_id> \
--branch my-feature-branch \
--query 'mykey* translated:true' \
--locale-id abcd1234abcd1234abcd1234abcd1234

Response

Status: 200
{
  "records_affected": 2
}

Add tags to collection of keys

PATCH /v2/projects/:project_id/keys/tag

Tags all keys matching query. Same constraints as list.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`locale_id` optional	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.
`tags`	`string`	Tag or comma-separated list of tags to add to the matching collection of keys

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/tag" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","q":"mykey* translated:true","locale_id":"abcd1234abcd1234abcd1234abcd1234","tags":"landing-page,release-1.2"}' \
  -H 'Content-Type: application/json'

phraseapp keys tag <project_id> \
--branch my-feature-branch \
--query 'mykey* translated:true' \
--locale-id abcd1234abcd1234abcd1234abcd1234 \
--tags landing-page,release-1.2

Response

Status: 200
{
  "records_affected": 2
}

Remove tags from collection of keys

PATCH /v2/projects/:project_id/keys/untag

Removes specified tags from keys matching query.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find keys by name (including wildcards). The following qualifiers are also supported in the search term: `ids:key_id,...` for queries on a comma-separated list of ids `name:key_name` for text queries on key names `tags:tag_name` to filter for keys with certain tags `translated:{true\|false}` for translation status (also requires `locale_id` to be specified) `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries `unmentioned_in_upload:upload_id` to filter keys unmentioned within upload Find more examples here.
`locale_id` optional	`id`	Locale used to determine the translation state of a key when filtering for untranslated or translated keys.
`tags`	`string`	Tag or comma-separated list of tags to remove from the matching collection of keys

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/untag" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","q":"mykey* translated:true","locale_id":"abcd1234abcd1234abcd1234abcd1234","tags":"landing-page,release-1.2"}' \
  -H 'Content-Type: application/json'

phraseapp keys untag <project_id> \
--branch my-feature-branch \
--query 'mykey* translated:true' \
--locale-id abcd1234abcd1234abcd1234abcd1234 \
--tags landing-page,release-1.2

Response

Status: 200
{
  "records_affected": 2
}

Translations

List all translations

GET /v2/projects/:project_id/translations

List translations for the given project. If you want to download all translations for one locale we recommend to use the locales#download endpoint.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations?branch=my-feature-branch&sort=updated_at&order=desc&q=PhraseApp*%2520unverified:true%2520excluded:true%2520tags:feature,center" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp translations list <project_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center'

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

List translations by locale

GET /v2/projects/:project_id/locales/:locale_id/translations

List translations for a specific locale. If you want to download all translations for one locale we recommend to use the locales#download endpoint.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/translations?branch=my-feature-branch&sort=updated_at&order=desc&q=PhraseApp*%2520unverified:true%2520excluded:true%2520tags:feature,center" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp translations by_locale <project_id> <locale_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center'

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

List translations by key

GET /v2/projects/:project_id/keys/:key_id/translations

List translations for a specific key.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/translations?branch=my-feature-branch&sort=updated_at&order=desc&q=PhraseApp*%2520unverified:true%2520excluded:true%2520tags:feature,center" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp translations by_key <project_id> <key_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center'

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Search translations

POST /v2/projects/:project_id/translations/search

Search translations for the given project. Provides the same search interface as translations#index but allows POST requests to avoid limitations imposed by GET requests. If you want to download all translations for one locale we recommend to use the locales#download endpoint.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/search" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","sort":"updated_at","order":"desc","q":"PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center"}' \
  -H 'Content-Type: application/json'

phraseapp translations search <project_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center'

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "unverified": false,
    "excluded": false,
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    "placeholders": [
      "%{count}"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single translation

GET /v2/projects/:project_id/translations/:id

Get details on a single translation.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp translation show <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "content": "My translation",
  "unverified": false,
  "excluded": false,
  "plural_suffix": "",
  "key": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "plural": false
  },
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "de",
    "code": "de-DE"
  },
  "placeholders": [
    "%{count}"
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "word_count": 2
}

Create a translation

POST /v2/projects/:project_id/translations

Create a translation.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`locale_id`	`id`	Locale. Can be the name or public id of the locale. Preferred is the public id.
`key_id`	`id`	Key
`content`	`string`	Translation content
`plural_suffix` optional	`string`	Plural suffix. Can be one of: zero, one, two, few, many, other. Must be specified if the key associated to the translation is pluralized. Default: <blank>
`unverified` optional	`boolean`	Indicates whether translation is unverified. Part of the Advanced Workflows feature. Default: false
`excluded` optional	`boolean`	Indicates whether translation is excluded. Default: false

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","locale_id":"abcd1234cdef1234abcd1234cdef1234","key_id":"abcd1234cdef1234abcd1234cdef1234","content":"My translation"}' \
  -H 'Content-Type: application/json'

phraseapp translation create <project_id> \
--branch my-feature-branch \
--locale-id abcd1234cdef1234abcd1234cdef1234 \
--key-id abcd1234cdef1234abcd1234cdef1234 \
--content "My translation"

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "content": "My translation",
  "unverified": false,
  "excluded": false,
  "plural_suffix": "",
  "key": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "plural": false
  },
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "de",
    "code": "de-DE"
  },
  "placeholders": [
    "%{count}"
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "word_count": 2
}

Update a translation

PATCH /v2/projects/:project_id/translations/:id

Update an existing translation.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`content`	`string`	Translation content
`plural_suffix` optional	`string`	Plural suffix. Can be one of: zero, one, two, few, many, other. Must be specified if the key associated to the translation is pluralized. Default: <blank>
`unverified` optional	`boolean`	Indicates whether translation is unverified. Part of the Advanced Workflows feature. Default: false
`excluded` optional	`boolean`	Indicates whether translation is excluded. Default: false

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","content":"My translation"}' \
  -H 'Content-Type: application/json'

phraseapp translation update <project_id> <id> \
--branch my-feature-branch \
--content "My translation"

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "content": "My translation",
  "unverified": false,
  "excluded": false,
  "plural_suffix": "",
  "key": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "plural": false
  },
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "de",
    "code": "de-DE"
  },
  "placeholders": [
    "%{count}"
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "word_count": 2
}

Verify translations selected by query

PATCH /v2/projects/:project_id/translations/verify

Verify translations matching query.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/verify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","q":"PhraseApp*%20unverified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'

phraseapp translations verify <project_id> \
--branch my-feature-branch \
--query 'PhraseApp*%20unverified:true%20tags:feature,center' \
--sort updated_at \
--order desc

Response

Status: 200
{
  "records_affected": 96
}

Mark translations selected by query as unverified

PATCH /v2/projects/:project_id/translations/unverify

Mark translations matching query as unverified.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/unverify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","q":"PhraseApp*%20verified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'

phraseapp translations unverify <project_id> \
--branch my-feature-branch \
--query 'PhraseApp*%20verified:true%20tags:feature,center' \
--sort updated_at \
--order desc

Response

Status: 200
{
  "records_affected": 96
}

Review translations selected by query

PATCH /v2/projects/:project_id/translations/review

Review translations matching query.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/review" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","q":"PhraseApp*%reviewed:false%20tags:feature,center"}' \
  -H 'Content-Type: application/json'

phraseapp translations review <project_id> \
--branch my-feature-branch \
--query 'PhraseApp*%reviewed:false%20tags:feature,center'

Response

Status: 200
{
  "records_affected": 96
}

Set exclude from export flag on translations selected by query

PATCH /v2/projects/:project_id/translations/exclude

Exclude translations matching query from locale export.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/exclude" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","q":"PhraseApp*%20verified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'

phraseapp translations exclude <project_id> \
--branch my-feature-branch \
--query 'PhraseApp*%20verified:true%20tags:feature,center' \
--sort updated_at \
--order desc

Response

Status: 200
{
  "records_affected": 96
}

Remove exlude from import flag from translations selected by query

PATCH /v2/projects/:project_id/translations/include

Include translations matching query in locale export.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`q` optional	`string`	Specify a query to find translations by content (including wildcards). The following qualifiers are supported in the query: `id:translation_id,...` for queries on a comma-separated list of ids `tags:XYZ` for tags on the translation `unverified:{true\|false}` for verification status `excluded:{true\|false}` for exclusion status `updated_at:{>=\|<=}2013-02-21T00:00:00Z` for date range queries Find more examples here.
`sort` optional	`string`	Sort criteria. Can be one of: key_name, created_at, updated_at. Default: key_name
`order` optional	`string`	Order direction. Can be one of: asc, desc. Default: asc

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/include" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","q":"PhraseApp*%20verified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'

phraseapp translations include <project_id> \
--branch my-feature-branch \
--query 'PhraseApp*%20verified:true%20tags:feature,center' \
--sort updated_at \
--order desc

Response

Status: 200
{
  "records_affected": 96
}

Uploads

Formats

We support all common localization file formats. For a detailed overview, see our Format Guide.

Processing

Uploads will be processed asynchronously and thus the data might not be imported yet although the upload is completed. Therefore we recommend to evaluate the returned state field for information on the import progress.

Available States

State	Description
`initialized`	Data received.
`waiting_for_preview`	Upload is waiting for preview to be finished.
`waiting`	Upload is waiting for processing.
`processing`	Upload is being processed, data is currently imported.
`success`	Upload is complete and all data is imported.
`error`	Upload or import process failed.

Upload a new file

POST /v2/projects/:project_id/uploads

Upload a new language file. Creates necessary resources in your project.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`file`	`file`	File to be imported
`file_format` optional	`string`	File format. Auto-detected when possible and not specified.
`locale_id` optional	`id`	Locale of the file's content. Can be the name or public id of the locale. Preferred is the public id.
`tags` optional	`string`	List of tags separated by comma to be associated with the new keys contained in the upload.
`update_translations` optional	`boolean`	Indicates whether existing translations should be updated with the file content. Default: false
`update_descriptions` optional	`boolean`	Existing key descriptions will be updated with the file content. Empty descriptions overwrite existing descriptions. Default: false
`convert_emoji` optional	`boolean`	Indicates whether the file contains Emoji symbols that should be converted. Working with Emojis. Default: false
`skip_upload_tags` optional	`boolean`	Indicates whether the upload should not create upload tags. Default: false
`skip_unverification` optional	`boolean`	Indicates whether the upload should unverify updated translations. Default: false
`file_encoding` optional	`string`	Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1".
`locale_mapping` optional	`hash`	Optional, format specific mapping between locale names and the columns the translations to those locales are contained in.
`format_options` optional	`hash`	Additional options available for specific formats. See our format guide for complete list.
`autotranslate` optional	`boolean`	If set, translations for the uploaded language will be fetched automatically. Default: false
`mark_reviewed` optional	`boolean`	Indicated whether the imported translations should be marked as reviewed. This setting is available if the review workflow (currently beta) is enabled for the project. Default: false

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/uploads" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F branch=my-feature-branch \
  -F file=@/path/to/my/file.json \
  -F file_format=json \
  -F locale_id=abcd1234cdef1234abcd1234cdef1234 \
  -F tags=awesome-feature,needs-proofreading \
  -F locale_mapping=%7B%22en%22:%20%222%22%7D \
  -F format_options=%7B%22foo%22:%20%22bar%22%7D

phraseapp upload create <project_id> \
--branch my-feature-branch \
--file /path/to/my/file.json \
--file-format json \
--locale-id abcd1234cdef1234abcd1234cdef1234 \
--tags awesome-feature,needs-proofreading \
--locale-mapping "{"en": "2"}" \
--format-options "{"foo": "bar"}"

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "filename": "example.json",
  "format": "json",
  "state": "success",
  "summary": {
    "locales_created": 2,
    "translation_keys_created": 162,
    "translations_created": 291,
    "translations_updated": 3,
    "tags_created": 2
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

View upload details

GET /v2/projects/:project_id/uploads/:id

View details and summary for a single upload.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/uploads/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp upload show <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "filename": "example.json",
  "format": "json",
  "state": "success",
  "summary": {
    "locales_created": 2,
    "translation_keys_created": 162,
    "translations_created": 291,
    "translations_updated": 3,
    "tags_created": 2
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

List uploads

GET /v2/projects/:project_id/uploads

List all uploads for the given project.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/uploads?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp uploads list <project_id> \
--branch my-feature-branch

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "filename": "example.json",
    "format": "json",
    "state": "success",
    "summary": {
      "locales_created": 2,
      "translation_keys_created": 162,
      "translations_created": 291,
      "translations_updated": 3,
      "tags_created": 2
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "filename": "example.json",
    "format": "json",
    "state": "success",
    "summary": {
      "locales_created": 2,
      "translation_keys_created": 162,
      "translations_created": 291,
      "translations_updated": 3,
      "tags_created": 2
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Blacklisted Keys

List blacklisted keys

GET /v2/projects/:project_id/blacklisted_keys

List all rules for blacklisting keys for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/blacklisted_keys" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp blacklisted_keys list <project_id>

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "date.formats.*",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "date.formats.*",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single blacklisted key

GET /v2/projects/:project_id/blacklisted_keys/:id

Get details on a single rule for blacklisting keys for a given project.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/blacklisted_keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp blacklisted_key show <project_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "date.formats.*",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a blacklisted key

POST /v2/projects/:project_id/blacklisted_keys

Create a new rule for blacklisting keys.

Parameters

Name	Type	Description
`name`	`string`	Blacklisted key name

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/blacklisted_keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"name":"date.formats.*"}' \
  -H 'Content-Type: application/json'

phraseapp blacklisted_key create <project_id> \
--name 'date.formats.*'

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "date.formats.*",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a blacklisted key

PATCH /v2/projects/:project_id/blacklisted_keys/:id

Update an existing rule for blacklisting keys.

Parameters

Name	Type	Description
`name`	`string`	Blacklisted key name

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/blacklisted_keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"name":"date.formats.*"}' \
  -H 'Content-Type: application/json'

phraseapp blacklisted_key update <project_id> <id> \
--name 'date.formats.*'

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "date.formats.*",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a blacklisted key

DELETE /v2/projects/:project_id/blacklisted_keys/:id

Delete an existing rule for blacklisting keys.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/blacklisted_keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp blacklisted_key delete <project_id> <id>

Response

Status: 204

Versions / History

List all versions

GET /v2/projects/:project_id/translations/:translation_id/versions

List all versions for the given translation.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:translation_id/versions?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp versions list <project_id> <translation_id> \
--branch my-feature-branch

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "en",
      "code": "en-GB"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "changed_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "content": "My translation",
    "plural_suffix": "",
    "key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "plural": false
    },
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "en",
      "code": "en-GB"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "changed_at": "2015-01-28T09:52:53Z"
  }
]

Get a single version

GET /v2/projects/:project_id/translations/:translation_id/versions/:id

Get details on a single version.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:translation_id/versions/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp version show <project_id> <translation_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "content": "My translation",
  "plural_suffix": "",
  "key": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "plural": false
  },
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "en",
    "code": "en-GB"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "changed_at": "2015-01-28T09:52:53Z",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  }
}

Jobs

List jobs

GET /v2/projects/:project_id/jobs

List all jobs for the given project.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`owned_by`	`string`	filter by user owning job
`assigned_to`	`string`	filter by user assigned to job
`state`	`string`	filter by state of job Valid states are `draft`, `in_progress`, `completed`

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs?branch=my-feature-branch&owned_by=abcd1234cdef1234abcd1234cdef1234&assigned_to=abcd1234cdef1234abcd1234cdef1234&state=completed" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp jobs list <project_id> \
--branch my-feature-branch \
--owned-by abcd1234cdef1234abcd1234cdef1234 \
--assigned-to abcd1234cdef1234abcd1234cdef1234 \
--state completed

Response

Status: 200
[
  {
    "id": "626ea67628690c73ac86ac81eec2d185",
    "name": "Translations for new Feature",
    "briefing": "Some instructions for the translators",
    "due_date": "2017-02-28T09:52:53Z",
    "state": "completed",
    "created_at": "2017-01-28T09:52:53Z",
    "updated_at": "2017-01-28T09:52:53Z"
  },
  {
    "id": "626ea67628690c73ac86ac81eec2d185",
    "name": "Translations for new Feature",
    "briefing": "Some instructions for the translators",
    "due_date": "2017-02-28T09:52:53Z",
    "state": "completed",
    "created_at": "2017-01-28T09:52:53Z",
    "updated_at": "2017-01-28T09:52:53Z"
  }
]

Get a single job

GET /v2/projects/:project_id/jobs/:id

Get details on a single job for a given project.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp job show <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "name": "Translations for new Feature",
  "briefing": "Some instructions for the translators",
  "due_date": "2017-02-28T09:52:53Z",
  "state": "completed",
  "created_at": "2017-01-28T09:52:53Z",
  "updated_at": "2017-01-28T09:52:53Z",
  "owner": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "job_tag_name": "Job_123",
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "keys": [
    {
      "id": "dbcd1234cdef1234abcd1234cdef1234",
      "name": "greeting.hello"
    }
  ]
}

Create a job

POST /v2/projects/:project_id/jobs

Create a new job.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`name`	`string`	Job name
`briefing` optional	`string`	Briefing for the translators
`due_date` optional	`datetime`	Date the job should be finished
`tags`	`array` of `strings`	tags of keys that should be included within the job
`translation_key_ids`	`array` of `strings`	ids of keys that should be included within the job

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","name":"de","briefing":"de-DE","due_date":"2017-08-15","tags":["myUploadTag"],"translation_key_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'

phraseapp job create <project_id> \
--branch my-feature-branch \
--name de \
--briefing de-DE \
--due-date 2017-08-15 \
--tags "myUploadTag" \
--translation-key-ids "abcd1234cdef1234abcd1234cdef1234"

Response

Status: 201
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "name": "Translations for new Feature",
  "briefing": "Some instructions for the translators",
  "due_date": "2017-02-28T09:52:53Z",
  "state": "completed",
  "created_at": "2017-01-28T09:52:53Z",
  "updated_at": "2017-01-28T09:52:53Z",
  "owner": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "job_tag_name": "Job_123",
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "keys": [
    {
      "id": "dbcd1234cdef1234abcd1234cdef1234",
      "name": "greeting.hello"
    }
  ]
}

Update a job

PATCH /v2/projects/:project_id/jobs/:id

Update an existing job.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`name`	`string`	Job name
`briefing` optional	`string`	Briefing for the translators
`due_date` optional	`datetime`	Date the job should be finished

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","name":"de","briefing":"de-DE","due_date":"2017-08-15"}' \
  -H 'Content-Type: application/json'

phraseapp job update <project_id> <id> \
--branch my-feature-branch \
--name de \
--briefing de-DE \
--due-date 2017-08-15

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "name": "Translations for new Feature",
  "briefing": "Some instructions for the translators",
  "due_date": "2017-02-28T09:52:53Z",
  "state": "completed",
  "created_at": "2017-01-28T09:52:53Z",
  "updated_at": "2017-01-28T09:52:53Z",
  "owner": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "job_tag_name": "Job_123",
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "keys": [
    {
      "id": "dbcd1234cdef1234abcd1234cdef1234",
      "name": "greeting.hello"
    }
  ]
}

Delete a job

DELETE /v2/projects/:project_id/jobs/:id

Delete an existing job.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp job delete <project_id> <id> \
--branch my-feature-branch

Response

Status: 204

Start a job

POST /v2/projects/:project_id/jobs/:id/start

Starts an existing job in state draft.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id/start" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp job start <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "name": "Translations for new Feature",
  "briefing": "Some instructions for the translators",
  "due_date": "2017-02-28T09:52:53Z",
  "state": "completed",
  "created_at": "2017-01-28T09:52:53Z",
  "updated_at": "2017-01-28T09:52:53Z",
  "owner": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "job_tag_name": "Job_123",
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "keys": [
    {
      "id": "dbcd1234cdef1234abcd1234cdef1234",
      "name": "greeting.hello"
    }
  ]
}

Complete a job

POST /v2/projects/:project_id/jobs/:id/complete

Mark a job as completed.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id/complete" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp job complete <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "name": "Translations for new Feature",
  "briefing": "Some instructions for the translators",
  "due_date": "2017-02-28T09:52:53Z",
  "state": "completed",
  "created_at": "2017-01-28T09:52:53Z",
  "updated_at": "2017-01-28T09:52:53Z",
  "owner": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "job_tag_name": "Job_123",
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "keys": [
    {
      "id": "dbcd1234cdef1234abcd1234cdef1234",
      "name": "greeting.hello"
    }
  ]
}

Reopen a job

POST /v2/projects/:project_id/jobs/:id/reopen

Mark a job as uncompleted.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id/reopen" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp job reopen <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "name": "Translations for new Feature",
  "briefing": "Some instructions for the translators",
  "due_date": "2017-02-28T09:52:53Z",
  "state": "completed",
  "created_at": "2017-01-28T09:52:53Z",
  "updated_at": "2017-01-28T09:52:53Z",
  "owner": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "job_tag_name": "Job_123",
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "keys": [
    {
      "id": "dbcd1234cdef1234abcd1234cdef1234",
      "name": "greeting.hello"
    }
  ]
}

Add keys to job

POST /v2/projects/:project_id/jobs/:id/keys

Add multiple keys to a existing job.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`translation_key_ids`	`array` of `strings`	ids of keys that should added to the job

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","translation_key_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'

phraseapp job keys create <project_id> <id> \
--branch my-feature-branch \
--translation-key-ids "abcd1234cdef1234abcd1234cdef1234"

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "name": "Translations for new Feature",
  "briefing": "Some instructions for the translators",
  "due_date": "2017-02-28T09:52:53Z",
  "state": "completed",
  "created_at": "2017-01-28T09:52:53Z",
  "updated_at": "2017-01-28T09:52:53Z",
  "owner": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "job_tag_name": "Job_123",
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "keys": [
    {
      "id": "dbcd1234cdef1234abcd1234cdef1234",
      "name": "greeting.hello"
    }
  ]
}

Remove keys from job

DELETE /v2/projects/:project_id/jobs/:id/keys

Remove multiple keys from existing job.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`translation_key_ids`	`array` of `strings`	ids of keys that should added to the job

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch","translation_key_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'

phraseapp job keys delete <project_id> <id> \
--branch my-feature-branch \
--translation-key-ids "abcd1234cdef1234abcd1234cdef1234"

Response

Status: 204

Job Locales

List job locales

GET /v2/projects/:project_id/jobs/:job_id/locales

List all job locales for a given job.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp job_locales list <project_id> <job_id> \
--branch my-feature-branch

Response

Status: 200
[
  {
    "id": "626ea67628690c73ac86ac81eec2d185",
    "job": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Job 1",
      "state": "completed"
    },
    "users": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "username": "joe.doe",
        "name": "Joe Doe"
      }
    ],
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  },
  {
    "id": "626ea67628690c73ac86ac81eec2d185",
    "job": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Job 1",
      "state": "completed"
    },
    "users": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "username": "joe.doe",
        "name": "Joe Doe"
      }
    ],
    "locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  }
]

Get a single job locale

GET /v2/projects/:project_id/jobs/:job_id/locale/:id

Get a single job locale for a given job.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locale/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp job_locale show <project_id> <job_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "job": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Job 1",
    "state": "completed"
  },
  "users": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    }
  ],
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "English",
    "code": "en-GB"
  }
}

Create a job locale

POST /v2/projects/:project_id/jobs/:job_id/locales

Create a new job locale.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`locale_id`	`string`	locale id
`user_ids` optional	`array` of `strings`	Array of user ids to be assigned to the job locale

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","locale_id":"abcd1234cdef1234abcd1234cdef1234","user_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'

phraseapp job_locales create <project_id> <job_id> \
--branch my-feature-branch \
--locale-id abcd1234cdef1234abcd1234cdef1234 \
--user-ids "abcd1234cdef1234abcd1234cdef1234"

Response

Status: 201
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "job": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Job 1",
    "state": "completed"
  },
  "users": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    }
  ],
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "English",
    "code": "en-GB"
  }
}

Update a job locale

PATCH /v2/projects/:project_id/jobs/:job_id/locales/:id

Update an existing job locale.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`locale_id`	`string`	locale id
`user_ids` optional	`array` of `strings`	Array of user ids to be assigned to the job locale

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","locale_id":"abcd1234cdef1234abcd1234cdef1234","user_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'

phraseapp job_locale update <project_id> <job_id> <id> \
--branch my-feature-branch \
--locale-id abcd1234cdef1234abcd1234cdef1234 \
--user-ids "abcd1234cdef1234abcd1234cdef1234"

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "job": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Job 1",
    "state": "completed"
  },
  "users": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    }
  ],
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "English",
    "code": "en-GB"
  }
}

Delete a job locale

DELETE /v2/projects/:project_id/jobs/:job_id/locales/:id

Delete an existing job locale.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp job_locale delete <project_id> <job_id> <id> \
--branch my-feature-branch

Response

Status: 204

Complete a job locale

POST /v2/projects/:project_id/jobs/:job_id/locales/:id/complete

Mark a job locale as completed.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:id/complete" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp job_locale complete <project_id> <job_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "job": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Job 1",
    "state": "completed"
  },
  "users": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    }
  ],
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "English",
    "code": "en-GB"
  }
}

Reopen a job locale

POST /v2/projects/:project_id/jobs/:job_id/locales/:id/reopen

Mark a job locale as uncompleted.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:id/reopen" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp job_locale reopen <project_id> <job_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "626ea67628690c73ac86ac81eec2d185",
  "job": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Job 1",
    "state": "completed"
  },
  "users": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    }
  ],
  "locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "English",
    "code": "en-GB"
  }
}

Comments

List comments

GET /v2/projects/:project_id/keys/:key_id/comments

List all comments for a key.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp comments list <project_id> <key_id> \
--branch my-feature-branch

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "message": "Some message...",
    "user": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "message": "Some message...",
    "user": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    },
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single comment

GET /v2/projects/:project_id/keys/:key_id/comments/:id

Get details on a single comment.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp comment show <project_id> <key_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "message": "Some message...",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a comment

POST /v2/projects/:project_id/keys/:key_id/comments

Create a new comment for a key.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`message`	`string`	Comment message

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","message":"Some message..."}' \
  -H 'Content-Type: application/json'

phraseapp comment create <project_id> <key_id> \
--branch my-feature-branch \
--message "Some message..."

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "message": "Some message...",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a comment

PATCH /v2/projects/:project_id/keys/:key_id/comments/:id

Update an existing comment.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`message`	`string`	Comment message

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch","message":"Some message..."}' \
  -H 'Content-Type: application/json'

phraseapp comment update <project_id> <key_id> <id> \
--branch my-feature-branch \
--message "Some message..."

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "message": "Some message...",
  "user": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a comment

DELETE /v2/projects/:project_id/keys/:key_id/comments/:id

Delete an existing comment.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp comment delete <project_id> <key_id> <id> \
--branch my-feature-branch

Response

Status: 204

Mark a comment as read

PATCH /v2/projects/:project_id/keys/:key_id/comments/:id/read

Mark a comment as read.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments/:id/read" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp comment mark read <project_id> <key_id> <id> \
--branch my-feature-branch

Response

Status: 204

Mark a comment as unread

DELETE /v2/projects/:project_id/keys/:key_id/comments/:id/read

Mark a comment as unread.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments/:id/read" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp comment mark unread <project_id> <key_id> <id> \
--branch my-feature-branch

Response

Status: 204

Check if comment is read

GET /v2/projects/:project_id/keys/:key_id/comments/:id/read

Check if comment was marked as read. Returns 204 if read, 404 if unread.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/keys/:key_id/comments/:id/read?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp comment mark check <project_id> <key_id> <id> \
--branch my-feature-branch

Response

Status: 204

Branches

Branch creation

Branches will be created asynchronously. State of branch creation is returned as state.

Available States

State	Description
`initialized`	Data received.
`processing`	Branch is currently creating.
`success`	Branch was created successfully
`error`	Branch creation failed.

List branches

GET /v2/projects/:project_id/branches

List all branches the of the current project.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp branches list <project_id>

Response

Status: 200
[
  {
    "name": "new-branch",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "merged_at": "2015-01-28T09:52:53Z",
    "merged_by": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    },
    "created_by": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    },
    "state": "success"
  },
  {
    "name": "new-branch",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "merged_at": "2015-01-28T09:52:53Z",
    "merged_by": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    },
    "created_by": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "username": "joe.doe",
      "name": "Joe Doe"
    },
    "state": "success"
  }
]

Get a single branch

GET /v2/projects/:project_id/branches/:id

Get details on a single branch for a given project.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp branch show <project_id> <id>

Response

Status: 200
{
  "name": "new-branch",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "merged_at": "2015-01-28T09:52:53Z",
  "merged_by": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "created_by": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "state": "success"
}

Create a branch

POST /v2/projects/:project_id/branches

Create a new branch.

Parameters

Name	Type	Description
`name`	`string`	Name of the branch

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"name":"my-branch"}' \
  -H 'Content-Type: application/json'

phraseapp branch create <project_id> \
--name my-branch

Response

Status: 201
{
  "name": "new-branch",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "merged_at": "2015-01-28T09:52:53Z",
  "merged_by": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "created_by": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "state": "success"
}

Update a branch

PATCH /v2/projects/:project_id/branches/:id

Update an existing branch.

Parameters

Name	Type	Description
`name`	`string`	Name of the branch

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"name":"my-branch"}' \
  -H 'Content-Type: application/json'

phraseapp branch update <project_id> <id> \
--name my-branch

Response

Status: 200
{
  "name": "new-branch",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "merged_at": "2015-01-28T09:52:53Z",
  "merged_by": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "created_by": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "username": "joe.doe",
    "name": "Joe Doe"
  },
  "state": "success"
}

Delete a branch

DELETE /v2/projects/:project_id/branches/:id

Delete an existing branch.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp branch delete <project_id> <id>

Response

Status: 204

Merge a branch

PATCH /v2/projects/:project_id/branches/:id/merge

Merge an existing branch.

Parameters

Name	Type	Description
`strategy` optional	`string`	strategy used for merge blocking, use_master or use_branch Default: blocking

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:id/merge" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"strategy":"use_master"}' \
  -H 'Content-Type: application/json'

phraseapp branch merge <project_id> <id> \
--strategy use_master

Response

Status: 200

Compare branches

GET /v2/projects/:project_id/branches/:id/compare

Compare branch with main branch.

Parameters

Name	Type	Description
`name`	`string`	Name of the branch

Note: This endpoint is currently in beta and might change in the future.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:id/compare?name=my-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp branch compare <project_id> <id> \
--name my-branch

Response

Status: 200

Glossary

Note: Glossary API is still in beta and might be subject to change. Glossaries are available in the Pro Plan and higher.

List glossaries

GET /v2/accounts/:account_id/glossaries

List all glossaries the current user has access to.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp glossaries list <account_id>

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My glossary",
    "projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My glossary",
    "projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single glossary

GET /v2/accounts/:account_id/glossaries/:id

Get details on a single glossary.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp glossary show <account_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "My glossary",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a glossary

POST /v2/accounts/:account_id/glossaries

Create a new glossary.

Parameters

Name	Type	Description
`name`	`string`	Name of the glossary
`project_ids` optional	`string`	List of project ids the glossary should be assigned to.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"name":"My glossary","project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235"}' \
  -H 'Content-Type: application/json'

phraseapp glossary create <account_id> \
--name "My glossary" \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "My glossary",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a glossary

PATCH /v2/accounts/:account_id/glossaries/:id

Update an existing glossary.

Parameters

Name	Type	Description
`name`	`string`	Name of the glossary
`project_ids` optional	`string`	List of project ids the glossary should be assigned to.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"name":"My glossary","project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235"}' \
  -H 'Content-Type: application/json'

phraseapp glossary update <account_id> <id> \
--name "My glossary" \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "My glossary",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a glossary

DELETE /v2/accounts/:account_id/glossaries/:id

Delete an existing glossary.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp glossary delete <account_id> <id>

Response

Status: 204

Glossary Terms

Note: Glossary API is still in beta and might be subject to change. Glossaries are available in the Pro Plan and higher.

List glossary terms

GET /v2/accounts/:account_id/glossaries/:glossary_id/terms

List all glossary terms the current user has access to.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp glossary_terms list <account_id> <glossary_id>

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1233",
    "term": "Save",
    "description": "This term is used on the 'Save' buttons of our website",
    "translatable": true,
    "case_sensitive": true,
    "translations": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "locale_code": "fr-FR",
        "content": "Entasser",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      },
      {
        "id": "abcd1234cdef1234abcd1234cdef1235",
        "locale_code": "de-DE",
        "content": "Speichern",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1233",
    "term": "Save",
    "description": "This term is used on the 'Save' buttons of our website",
    "translatable": true,
    "case_sensitive": true,
    "translations": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "locale_code": "fr-FR",
        "content": "Entasser",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      },
      {
        "id": "abcd1234cdef1234abcd1234cdef1235",
        "locale_code": "de-DE",
        "content": "Speichern",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single glossary term

GET /v2/accounts/:account_id/glossaries/:glossary_id/terms/:id

Get details on a single glossary term.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp glossary_term show <account_id> <glossary_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1233",
  "term": "Save",
  "description": "This term is used on the 'Save' buttons of our website",
  "translatable": true,
  "case_sensitive": true,
  "translations": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "locale_code": "fr-FR",
      "content": "Entasser",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    },
    {
      "id": "abcd1234cdef1234abcd1234cdef1235",
      "locale_code": "de-DE",
      "content": "Speichern",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a glossary term

POST /v2/accounts/:account_id/glossaries/:glossary_id/terms

Create a new glossary term.

Parameters

Name	Type	Description
`term`	`string`	Glossary term
`description` optional	`string`	Description of term Default:
`translatable` optional	`boolean`	Indicates whether the term should be used for all languages or can be translated Default: false
`case_sensitive` optional	`boolean`	Indicates whether the term is case sensitive Default: false

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"term":"MyCompany","description":"Use this when refering to our company","translatable":true,"case_sensitive":true}' \
  -H 'Content-Type: application/json'

phraseapp glossary_term create <account_id> <glossary_id> \
--term MyCompany \
--description "Use this when refering to our company" \
--translatable true \
--case-sensitive true

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1233",
  "term": "Save",
  "description": "This term is used on the 'Save' buttons of our website",
  "translatable": true,
  "case_sensitive": true,
  "translations": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "locale_code": "fr-FR",
      "content": "Entasser",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    },
    {
      "id": "abcd1234cdef1234abcd1234cdef1235",
      "locale_code": "de-DE",
      "content": "Speichern",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a glossary term

PATCH /v2/accounts/:account_id/glossaries/:glossary_id/terms/:id

Update an existing glossary term.

Parameters

Name	Type	Description
`term`	`string`	Glossary term
`description` optional	`string`	Description of term Default:
`translatable` optional	`boolean`	Indicates whether the term should be used for all languages or can be translated Default: false
`case_sensitive` optional	`boolean`	Indicates whether the term is case sensitive Default: false

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"term":"MyCompany","description":"Use this when refering to our company","translatable":true,"case_sensitive":true}' \
  -H 'Content-Type: application/json'

phraseapp glossary_term update <account_id> <glossary_id> <id> \
--term MyCompany \
--description "Use this when refering to our company" \
--translatable true \
--case-sensitive true

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1233",
  "term": "Save",
  "description": "This term is used on the 'Save' buttons of our website",
  "translatable": true,
  "case_sensitive": true,
  "translations": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "locale_code": "fr-FR",
      "content": "Entasser",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    },
    {
      "id": "abcd1234cdef1234abcd1234cdef1235",
      "locale_code": "de-DE",
      "content": "Speichern",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a glossary term

DELETE /v2/accounts/:account_id/glossaries/:glossary_id/terms/:id

Delete an existing glossary term.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp glossary_term delete <account_id> <glossary_id> <id>

Response

Status: 204

Glossary Term Translations

Note: Glossary API is still in beta and might be subject to change. Glossaries are available in the Pro Plan and higher.

Create a glossary term translation

POST /v2/accounts/:account_id/glossaries/:glossary_id/terms/:term_id/translations

Create a new glossary term translation.

Parameters

Name	Type	Description
`locale_code`	`string`	Identifies the language for this translation
`content` optional	`string`	The content of the translation

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms/:term_id/translations" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"locale_code":"en-US","content":"My translated term"}' \
  -H 'Content-Type: application/json'

phraseapp glossary_term_translation create <account_id> <glossary_id> <term_id> \
--locale-code en-US \
--content "My translated term"

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "locale_code": "en-US",
  "content": "Save",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a glossary term translation

PATCH /v2/accounts/:account_id/glossaries/:glossary_id/terms/:term_id/translations/:id

Update an existing glossary term translation.

Parameters

Name	Type	Description
`locale_code`	`string`	Identifies the language for this translation
`content` optional	`string`	The content of the translation

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms/:term_id/translations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"locale_code":"en-US","content":"My translated term"}' \
  -H 'Content-Type: application/json'

phraseapp glossary_term_translation update <account_id> <glossary_id> <term_id> <id> \
--locale-code en-US \
--content "My translated term"

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "locale_code": "en-US",
  "content": "Save",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a glossary term translation

DELETE /v2/accounts/:account_id/glossaries/:glossary_id/terms/:term_id/translations/:id

Delete an existing glossary term translation.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/glossaries/:glossary_id/terms/:term_id/translations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp glossary_term_translation delete <account_id> <glossary_id> <term_id> <id>

Response

Status: 204

Bitbucket Sync

List Bitbucket syncs

GET /v2/bitbucket_syncs

List all Bitbucket repositories for which synchronisation with Phrase is activated.

Parameters

Name	Type	Description
`account_id` optional	`string`	Account ID to specify the actual account the project should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/bitbucket_syncs?account_id=abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp bitbucket_syncs list \
--account-id abcd1234

Response

Status: 200
[
  {
    "id": "aad1ar91-0331-4181-b90p-4crdnv0bd812",
    "repository_name": "some-repository",
    "last_export_to_bitbucket_at": "2015-01-28T09:52:53Z",
    "last_import_from_bitbucket_at": "2015-01-28T09:52:53Z",
    "valid_phraseapp_yaml": true,
    "phraseapp_projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ]
  },
  {
    "id": "aad1ar91-0331-4181-b90p-4crdnv0bd812",
    "repository_name": "some-repository",
    "last_export_to_bitbucket_at": "2015-01-28T09:52:53Z",
    "last_import_from_bitbucket_at": "2015-01-28T09:52:53Z",
    "valid_phraseapp_yaml": true,
    "phraseapp_projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ]
  }
]

Export from Phrase to Bitbucket

POST /v2/bitbucket_syncs/:id/export

Export translations from Phrase to Bitbucket according to the .phraseapp.yml file within the Bitbucket Repository.

Parameters

Name	Type	Description
`account_id` optional	`string`	Account ID to specify the actual account the project should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/bitbucket_syncs/:id/export" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"account_id":"abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp bitbucket_sync export <id> \
--account-id abcd1234

Response

Status: 200
{
  "status_path": "https://bitbucket.sync.phraseapp.com/export_to_bitbucket_status"
}

Import to Phrase from Bitbucket

POST /v2/bitbucket_syncs/:id/import

Import translations from Bitbucket to Phrase according to the .phraseapp.yml file within the Bitbucket repository.

Parameters

Name	Type	Description
`account_id` optional	`string`	Account ID to specify the actual account the project should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/bitbucket_syncs/:id/import" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"account_id":"abcd1234"}' \
  -H 'Content-Type: application/json'

phraseapp bitbucket_sync import <id> \
--account-id abcd1234

Response

Status: 200

Webhooks

This resource is not available in Phrase On-Premise

List webhooks

GET /v2/projects/:project_id/webhooks

List all webhooks for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/webhooks" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp webhooks list <project_id>

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "callback_url": "http://example.com/hooks/phraseapp-notifications",
    "description": "My webhook for chat notifications",
    "events": "locales:create,translations:update",
    "active": true,
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "callback_url": "http://example.com/hooks/phraseapp-notifications",
    "description": "My webhook for chat notifications",
    "events": "locales:create,translations:update",
    "active": true,
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single webhook

GET /v2/projects/:project_id/webhooks/:id

Get details on a single webhook.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/webhooks/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp webhook show <project_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "callback_url": "http://example.com/hooks/phraseapp-notifications",
  "description": "My webhook for chat notifications",
  "events": "locales:create,translations:update",
  "active": true,
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a webhook

POST /v2/projects/:project_id/webhooks

Create a new webhook.

Parameters

Name	Type	Description
`callback_url`	`string`	Callback URL to send requests to
`description` optional	`string`	Webhook description
`events`	`string`	List of event names to trigger the webhook (separated by comma)
`active` optional	`boolean`	Whether webhook is active or inactive Default: true

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/webhooks" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"callback_url":"http://example.com/hooks/phraseapp-notifications","description":"My webhook for chat notifications","events":"locales:create,translations:update"}' \
  -H 'Content-Type: application/json'

phraseapp webhook create <project_id> \
--callback-url "http://example.com/hooks/phraseapp-notifications" \
--description "My webhook for chat notifications" \
--events "locales:create,translations:update"

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "callback_url": "http://example.com/hooks/phraseapp-notifications",
  "description": "My webhook for chat notifications",
  "events": "locales:create,translations:update",
  "active": true,
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a webhook

PATCH /v2/projects/:project_id/webhooks/:id

Update an existing webhook.

Parameters

Name	Type	Description
`callback_url`	`string`	Callback URL to send requests to
`description` optional	`string`	Webhook description
`events`	`string`	List of event names to trigger the webhook (separated by comma)
`active` optional	`boolean`	Whether webhook is active or inactive Default: true

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/webhooks/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"callback_url":"http://example.com/hooks/phraseapp-notifications","description":"My webhook for chat notifications","events":"locales:create,translations:update"}' \
  -H 'Content-Type: application/json'

phraseapp webhook update <project_id> <id> \
--callback-url "http://example.com/hooks/phraseapp-notifications" \
--description "My webhook for chat notifications" \
--events "locales:create,translations:update"

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "callback_url": "http://example.com/hooks/phraseapp-notifications",
  "description": "My webhook for chat notifications",
  "events": "locales:create,translations:update",
  "active": true,
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a webhook

DELETE /v2/projects/:project_id/webhooks/:id

Delete an existing webhook.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/webhooks/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp webhook delete <project_id> <id>

Response

Status: 204

Test a webhook

POST /v2/projects/:project_id/webhooks/:id/test

Perform a test request for a webhook.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/webhooks/:id/test" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST

phraseapp webhook test <project_id> <id>

Response

Status: 200

Distributions

This resource is not available in Phrase On-Premise

Note: Distributions API is still in beta and might be subject to change. Distributions are part of Over The Air which is available in the Lite, Pro and Exclusive plans.

List distributions

GET /v2/accounts/:account_id/distributions

List all distributions for the given account.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp distributions list <account_id>

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "Android Distribution",
    "project": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    },
    "platforms": [
      "android"
    ],
    "release_count": 10,
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "Android Distribution",
    "project": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    },
    "platforms": [
      "android"
    ],
    "release_count": 10,
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single distribution

GET /v2/accounts/:account_id/distributions/:id

Get details on a single distribution.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp distribution show <account_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "Android Distribution",
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "platforms": [
    "android"
  ],
  "releases": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "version": 1,
      "project": {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      },
      "platforms": [
        "android"
      ],
      "environments": [
        "development"
      ],
      "locale_codes": [
        "de",
        "en"
      ],
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a distribution

POST /v2/accounts/:account_id/distributions

Create a new distribution.

Parameters

Name	Type	Description
`name`	`string`	Name of the distribution
`project_id`	`string`	Project id the distribution should be assigned to.
`platforms`	`array` of `strings`	List of platforms the distribution should support.
`fallback_to_non_regional_locale` optional	`boolean`	Indicates whether to fallback to non regional locale when locale can not be found Default: false
`fallback_to_default_locale` optional	`boolean`	Indicates whether to fallback to projects default locale when locale can not be found Default: false

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"name":"My Android Distribution","project_id":"abcd1234abcd1234abcd1234","platforms":["android","ios"],"fallback_to_non_regional_locale":true,"fallback_to_default_locale":true}' \
  -H 'Content-Type: application/json'

phraseapp distribution create <account_id> \
--name "My Android Distribution" \
--project-id abcd1234abcd1234abcd1234 \
--platforms "android,ios" \
--fallback-to-non-regional-locale true \
--fallback-to-default-locale true

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "Android Distribution",
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "platforms": [
    "android"
  ],
  "releases": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "version": 1,
      "project": {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      },
      "platforms": [
        "android"
      ],
      "environments": [
        "development"
      ],
      "locale_codes": [
        "de",
        "en"
      ],
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a distribution

PATCH /v2/accounts/:account_id/distributions/:id

Update an existing distribution.

Parameters

Name	Type	Description
`name`	`string`	Name of the distribution
`project_id`	`string`	Project id the distribution should be assigned to.
`platforms`	`array` of `strings`	List of platforms the distribution should support.
`fallback_to_non_regional_locale` optional	`boolean`	Indicates whether to fallback to non regional locale when locale can not be found Default: false
`fallback_to_default_locale` optional	`boolean`	Indicates whether to fallback to projects default locale when locale can not be found Default: false

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"name":"My Android Distribution","project_id":"abcd1234abcd1234abcd1234","platforms":["android","ios"],"fallback_to_non_regional_locale":true,"fallback_to_default_locale":true}' \
  -H 'Content-Type: application/json'

phraseapp distribution update <account_id> <id> \
--name "My Android Distribution" \
--project-id abcd1234abcd1234abcd1234 \
--platforms "android,ios" \
--fallback-to-non-regional-locale true \
--fallback-to-default-locale true

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "name": "Android Distribution",
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "platforms": [
    "android"
  ],
  "releases": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "version": 1,
      "project": {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      },
      "platforms": [
        "android"
      ],
      "environments": [
        "development"
      ],
      "locale_codes": [
        "de",
        "en"
      ],
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a distribution

DELETE /v2/accounts/:account_id/distributions/:id

Delete an existing distribution.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp distribution delete <account_id> <id>

Response

Status: 204

Releases

This resource is not available in Phrase On-Premise

Note: Releases API is still in beta and might be subject to change. Releases are part of Over The Air which is available in the Lite, Pro and Exclusive plans.

List releases

GET /v2/accounts/:account_id/distributions/:distribution_id/releases

List all releases for the given distribution.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:distribution_id/releases" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp releases list <account_id> <distribution_id>

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "version": 1,
    "project": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    },
    "platforms": [
      "android"
    ],
    "environments": [
      "development"
    ],
    "locale_codes": [
      "de",
      "en"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "version": 1,
    "project": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    },
    "platforms": [
      "android"
    ],
    "environments": [
      "development"
    ],
    "locale_codes": [
      "de",
      "en"
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single release

GET /v2/accounts/:account_id/distributions/:distribution_id/releases/:id

Get details on a single release.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:distribution_id/releases/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp release show <account_id> <distribution_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "version": 1,
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "platforms": [
    "android"
  ],
  "environments": [
    "development",
    "production"
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a release

POST /v2/accounts/:account_id/distributions/:distribution_id/releases

Create a new release.

Parameters

Name	Type	Description
`description` optional	`string`	Description of the release
`platforms`	`array` of `strings`	List of platforms the release should support.
`branch` optional	`string`	Branch used for release

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:distribution_id/releases" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"description":"My first Release","platforms":["android","ios"],"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp release create <account_id> <distribution_id> \
--description "My first Release" \
--platforms "android,ios" \
--branch my-feature-branch

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "version": 1,
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "platforms": [
    "android"
  ],
  "environments": [
    "development",
    "production"
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Update a release

PATCH /v2/accounts/:account_id/distributions/:distribution_id/releases/:id

Update an existing release.

Parameters

Name	Type	Description
`description` optional	`string`	Description of the release
`platforms`	`array` of `strings`	List of platforms the release should support.
`branch` optional	`string`	Branch used for release

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:distribution_id/releases/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"description":"My first Release","platforms":["android","ios"],"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp release update <account_id> <distribution_id> <id> \
--description "My first Release" \
--platforms "android,ios" \
--branch my-feature-branch

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "version": 1,
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "platforms": [
    "android"
  ],
  "environments": [
    "development",
    "production"
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete a release

DELETE /v2/accounts/:account_id/distributions/:distribution_id/releases/:id

Delete an existing release.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:distribution_id/releases/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp release delete <account_id> <distribution_id> <id>

Response

Status: 204

Publish a release

POST /v2/accounts/:account_id/distributions/:distribution_id/releases/:id/publish

Publish a release for production.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/distributions/:distribution_id/releases/:id/publish" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST

phraseapp release publish <account_id> <distribution_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "version": 1,
  "project": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "My Android Project",
    "main_format": "xml",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  "platforms": [
    "android"
  ],
  "environments": [
    "development",
    "production"
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Orders

This resource is not available in Phrase On-Premise

List of categories [TextMaster]

When ordering translations from TextMaster, you need to specify a category ID along with your order. See this list for information on the category ID and their equivalent description.

Category ID	Description
C001	Agriculture
C002	Aerospace
C003	Animals/Pets/Plants
C004	Arts/Culture/Literature
C005	Automotive/Transportation
C006	Computers/Technology/Software
C007	Telecom
C008	Real Estate/Construction/Building
C009	Consumer Goods
C010	Education
C011	Entertainment
C012	Ecology/Environment
C013	Health/Biotechnology/Pharma
C014	Internet
C015	Policy/Government/Public
C016	Publishing/Media/Communication
C017	Religion
C018	Food/Beverages
C019	Retail
C020	Fashion/Luxury/Textiles
C021	Travel/Tourism
C022	Natural Resources/Energy
C023	Banking/Financial Services/Insurance
C024	Legal Affairs/Tax/Law
C025	Raw Materials/Industrial Goods
C026	Lifestyle/Leisure/Hobbies
C027	Sports
C028	Home/Family/Friends/Children
C029	Economy/Financial Markets
C030	Science
C031	Human Resources/Employment
C032	Adult (Pornography, Violence, etc.)

List orders

GET /v2/projects/:project_id/orders

List all orders for the given project.

This endpoint is paginated.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/orders?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp orders list <project_id> \
--branch my-feature-branch

Response

Status: 200
[
  {
    "id": "30AB4884",
    "lsp": "gengo",
    "amount_in_cents": 1152,
    "currency": "usd",
    "message": "Please make everything sound really nice :)",
    "state": "confirmed",
    "translation_type": "pro",
    "progress_percent": 50,
    "source_locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "en",
      "code": "en-GB"
    },
    "target_locales": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "de",
        "code": "de-DE"
      },
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "fr",
        "code": "fr-FR"
      }
    ],
    "tag": "latest-upload",
    "styleguide": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "title": "My Styleguide"
    },
    "unverify_translations_upon_delivery": true,
    "quality": true,
    "priority": true,
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "30AB4884",
    "lsp": "gengo",
    "amount_in_cents": 1152,
    "currency": "usd",
    "message": "Please make everything sound really nice :)",
    "state": "confirmed",
    "translation_type": "pro",
    "progress_percent": 50,
    "source_locale": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "en",
      "code": "en-GB"
    },
    "target_locales": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "de",
        "code": "de-DE"
      },
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "fr",
        "code": "fr-FR"
      }
    ],
    "tag": "latest-upload",
    "styleguide": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "title": "My Styleguide"
    },
    "unverify_translations_upon_delivery": true,
    "quality": true,
    "priority": true,
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single order

GET /v2/projects/:project_id/orders/:id

Get details on a single order.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/orders/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp order show <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "30AB4884",
  "lsp": "gengo",
  "amount_in_cents": 1152,
  "currency": "usd",
  "message": "Please make everything sound really nice :)",
  "state": "confirmed",
  "translation_type": "pro",
  "progress_percent": 50,
  "source_locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "en",
    "code": "en-GB"
  },
  "target_locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "fr",
      "code": "fr-FR"
    }
  ],
  "tag": "latest-upload",
  "styleguide": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "title": "My Styleguide"
  },
  "unverify_translations_upon_delivery": true,
  "quality": true,
  "priority": true,
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create a new order

POST /v2/projects/:project_id/orders

Create a new order. Access token scope must include orders.create.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use
`lsp`	`string`	Name of the LSP that should process this order. Can be one of gengo, textmaster.
`source_locale_id`	`id`	Source locale for the order. Can be the name or public id of the source locale. Preferred is the public id.
`target_locale_ids`	`array` of `strings`	List of target locales you want the source content translate to. Can be the name or public id of the target locales. Preferred is the public id.
`translation_type`	`string`	Name of the quality level, availability depends on the LSP. Can be one of: standard, pro (for orders processed by Gengo) and one of regular, premium, enterprise (for orders processed by TextMaster)
`tag` optional	`string`	Tag you want to order translations for.
`message` optional	`string`	Message that is displayed to the translators for description.
`styleguide_id` optional	`id`	Style guide for translators to be sent with the order.
`unverify_translations_upon_delivery` optional	`boolean`	Unverify translations upon delivery. Default: false
`include_untranslated_keys` optional	`boolean`	Order translations for keys with untranslated content in the selected target locales. Default: true
`include_unverified_translations` optional	`boolean`	Order translations for keys with unverified content in the selected target locales. Default: false
`category`	`string`	Category to use (required for orders processed by TextMaster).
`quality` optional	`boolean`	Extra proofreading option to ensure consistency in vocabulary and style. Only available for orders processed by TextMaster. Default: false
`priority` optional	`boolean`	Indicates whether the priority option should be ordered which decreases turnaround time by 30%. Available only for orders processed by TextMaster. Default: false

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/orders" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","lsp":"textmaster","source_locale_id":"abcd1234abcd1234abcd1234abcd1234","target_locale_ids":["1234abcd1234abcd1234abcd1234abcd","abcd1234abcd1234abcd1234abcd1234"],"translation_type":"premium","tag":"my-awesome-feature","message":"Please make everything sound really nice :)","styleguide_id":"1234abcd1234abcd1234abcd1234abcd","category":"C021"}' \
  -H 'Content-Type: application/json'

phraseapp order create <project_id> \
--branch my-feature-branch \
--lsp textmaster \
--source-locale-id abcd1234abcd1234abcd1234abcd1234 \
--target-locale-ids "1234abcd1234abcd1234abcd1234abcd,abcd1234abcd1234abcd1234abcd1234" \
--translation-type premium \
--tag my-awesome-feature \
--message "Please make everything sound really nice :)" \
--styleguide-id 1234abcd1234abcd1234abcd1234abcd \
--category C021

Response

Status: 201
{
  "id": "30AB4884",
  "lsp": "gengo",
  "amount_in_cents": 1152,
  "currency": "usd",
  "message": "Please make everything sound really nice :)",
  "state": "confirmed",
  "translation_type": "pro",
  "progress_percent": 50,
  "source_locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "en",
    "code": "en-GB"
  },
  "target_locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "fr",
      "code": "fr-FR"
    }
  ],
  "tag": "latest-upload",
  "styleguide": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "title": "My Styleguide"
  },
  "unverify_translations_upon_delivery": true,
  "quality": true,
  "priority": true,
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Confirm an order

PATCH /v2/projects/:project_id/orders/:id/confirm

Confirm an existing order and send it to the provider for translation. Same constraints as for create.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/orders/:id/confirm" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp order confirm <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{
  "id": "30AB4884",
  "lsp": "gengo",
  "amount_in_cents": 1152,
  "currency": "usd",
  "message": "Please make everything sound really nice :)",
  "state": "confirmed",
  "translation_type": "pro",
  "progress_percent": 50,
  "source_locale": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "en",
    "code": "en-GB"
  },
  "target_locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "de",
      "code": "de-DE"
    },
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "fr",
      "code": "fr-FR"
    }
  ],
  "tag": "latest-upload",
  "styleguide": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "title": "My Styleguide"
  },
  "unverify_translations_upon_delivery": true,
  "quality": true,
  "priority": true,
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Cancel an order

DELETE /v2/projects/:project_id/orders/:id

Cancel an existing order. Must not yet be confirmed.

Parameters

Name	Type	Description
`branch` optional	`string`	specify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/orders/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'

phraseapp order delete <project_id> <id> \
--branch my-feature-branch

Response

Status: 204

Style guides

This resource is not available in Phrase On-Premise

List style guides

GET /v2/projects/:project_id/styleguides

List all styleguides for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/styleguides" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp styleguides list <project_id>

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "title": "My Style Guide",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "title": "My Style Guide",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single style guide

GET /v2/projects/:project_id/styleguides/:id

Get details on a single style guide.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/styleguides/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp styleguide show <project_id> <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "title": "My Style Guide",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "public_url": "https://phrase.com/styleguide/my-project/26f065cf597be340",
  "audience": "customer-facing",
  "target_audience": "teenager",
  "grammatical_person": "first_person_singular",
  "vocabulary_type": "technical",
  "business": "We are a travel site that helps customers find the best hotels and flights.",
  "company_branding": "ACME Inc. should never be translated.",
  "formatting": "Never use capital letters",
  "glossary_terms": "Appartement, cabin, loft",
  "grammar_consistency": "",
  "literal_translation": "Neutral",
  "overall_tone": "Tone should be fun and light",
  "samples": "http://www.myexample.com/my/document/path/to/samples.pdf"
}

Create a style guide

POST /v2/projects/:project_id/styleguides

Create a new style guide.

Parameters

Name	Type	Description
`title`	`string`	Style guide title
`audience` optional	`string`	Audience description
`target_audience` optional	`string`	Can be one of: not_specified, children, teenager, young_adults, adults, old_adults.
`grammatical_person` optional	`string`	Can be one of: not_specified, first_person_singular, second_person_singular, third_person_singular_masculine, third_person_singular_feminine, third_person_singular_neuter, first_person_plural, second_person_plural, third_person_plural.
`vocabulary_type` optional	`string`	Can be one of: not_specified, popular, technical, fictional.
`business` optional	`string`	Description of the business
`company_branding` optional	`string`	Company branding to remain consistent.
`formatting` optional	`string`	Formatting requirements and character limitations.
`glossary_terms` optional	`string`	List of terms and/or phrases that need to be translated consistently.
`grammar_consistency` optional	`string`	Formal or informal pronouns, consistent conjugation, grammatical gender
`literal_translation` optional	`string`	Can be one of: Cultural/Conversational, Literal, Neutral.
`overall_tone` optional	`string`	Tone requirement descriptions
`samples` optional	`string`	Provide links to sample product pages, FAQ pages, etc. to give the translator a point of reference. You can also provide past translations. Even snippets or short paragraphs are helpful for maintaining consistency.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/styleguides" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"title":"Web application style guide","audience":"customer-facing","target_audience":"teenager","grammatical_person":"first_person_singular","vocabulary_type":"technical","business":"We are a travel site that helps customers find the best hotels and flights.","company_branding":"ACME Inc. should never be translated.","formatting":"Never use capital letters","glossary_terms":"Appartement, cabin, loft","grammar_consistency":"","literal_translation":"Neutral","overall_tone":"Tone should be fun and light","samples":"http://www.myexample.com/my/document/path/to/samples.pdf"}' \
  -H 'Content-Type: application/json'

phraseapp styleguide create <project_id> \
--title "Web application style guide" \
--audience customer-facing \
--target-audience teenager \
--grammatical-person first_person_singular \
--vocabulary-type technical \
--business "We are a travel site that helps customers find the best hotels and flights." \
--company-branding "ACME Inc. should never be translated." \
--formatting "Never use capital letters" \
--glossary-terms "Appartement, cabin, loft" \
--grammar-consistency  \
--literal-translation Neutral \
--overall-tone "Tone should be fun and light" \
--samples "http://www.myexample.com/my/document/path/to/samples.pdf"

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "title": "My Style Guide",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "public_url": "https://phrase.com/styleguide/my-project/26f065cf597be340",
  "audience": "customer-facing",
  "target_audience": "teenager",
  "grammatical_person": "first_person_singular",
  "vocabulary_type": "technical",
  "business": "We are a travel site that helps customers find the best hotels and flights.",
  "company_branding": "ACME Inc. should never be translated.",
  "formatting": "Never use capital letters",
  "glossary_terms": "Appartement, cabin, loft",
  "grammar_consistency": "",
  "literal_translation": "Neutral",
  "overall_tone": "Tone should be fun and light",
  "samples": "http://www.myexample.com/my/document/path/to/samples.pdf"
}

Update a style guide

PATCH /v2/projects/:project_id/styleguides/:id

Update an existing style guide.

Parameters

Name	Type	Description
`title`	`string`	Style guide title
`audience` optional	`string`	Audience description
`target_audience` optional	`string`	Can be one of: not_specified, children, teenager, young_adults, adults, old_adults.
`grammatical_person` optional	`string`	Can be one of: not_specified, first_person_singular, second_person_singular, third_person_singular_masculine, third_person_singular_feminine, third_person_singular_neuter, first_person_plural, second_person_plural, third_person_plural.
`vocabulary_type` optional	`string`	Can be one of: not_specified, popular, technical, fictional.
`business` optional	`string`	Description of the business
`company_branding` optional	`string`	Company branding to remain consistent.
`formatting` optional	`string`	Formatting requirements and character limitations.
`glossary_terms` optional	`string`	List of terms and/or phrases that need to be translated consistently.
`grammar_consistency` optional	`string`	Formal or informal pronouns, consistent conjugation, grammatical gender
`literal_translation` optional	`string`	Can be one of: Cultural/Conversational, Literal, Neutral.
`overall_tone` optional	`string`	Tone requirement descriptions
`samples` optional	`string`	Provide links to sample product pages, FAQ pages, etc. to give the translator a point of reference. You can also provide past translations. Even snippets or short paragraphs are helpful for maintaining consistency.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/styleguides/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"title":"Web application style guide","audience":"customer-facing","target_audience":"teenager","grammatical_person":"first_person_singular","vocabulary_type":"technical","business":"We are a travel site that helps customers find the best hotels and flights.","company_branding":"ACME Inc. should never be translated.","formatting":"Never use capital letters","glossary_terms":"Appartement, cabin, loft","grammar_consistency":"","literal_translation":"Neutral","overall_tone":"Tone should be fun and light","samples":"http://www.myexample.com/my/document/path/to/samples.pdf"}' \
  -H 'Content-Type: application/json'

phraseapp styleguide update <project_id> <id> \
--title "Web application style guide" \
--audience customer-facing \
--target-audience teenager \
--grammatical-person first_person_singular \
--vocabulary-type technical \
--business "We are a travel site that helps customers find the best hotels and flights." \
--company-branding "ACME Inc. should never be translated." \
--formatting "Never use capital letters" \
--glossary-terms "Appartement, cabin, loft" \
--grammar-consistency  \
--literal-translation Neutral \
--overall-tone "Tone should be fun and light" \
--samples "http://www.myexample.com/my/document/path/to/samples.pdf"

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "title": "My Style Guide",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "public_url": "https://phrase.com/styleguide/my-project/26f065cf597be340",
  "audience": "customer-facing",
  "target_audience": "teenager",
  "grammatical_person": "first_person_singular",
  "vocabulary_type": "technical",
  "business": "We are a travel site that helps customers find the best hotels and flights.",
  "company_branding": "ACME Inc. should never be translated.",
  "formatting": "Never use capital letters",
  "glossary_terms": "Appartement, cabin, loft",
  "grammar_consistency": "",
  "literal_translation": "Neutral",
  "overall_tone": "Tone should be fun and light",
  "samples": "http://www.myexample.com/my/document/path/to/samples.pdf"
}

Delete a style guide

DELETE /v2/projects/:project_id/styleguides/:id

Delete an existing style guide.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/styleguides/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp styleguide delete <project_id> <id>

Response

Status: 204

Authorizations

The endpoints provided by the Authorizations API are only accessible via Basic authentication with email and password.

When creating a new authorization, the new access token for this authorization will be returned in the immediate response but not later, due to security reasons. When accessing authorizations later, you will only see the last eight chars of the token in plain text (token_last_eight) and the SHA256 digest of the token for reference (hashed_token).

For instructions on how authorization in general works, see our Auth Guide.

Scopes

When creating or updating an OAuth authorization, you can define a list of scopes to limit the access that can be performed by that authorization.

Available Scopes

Scope	Description
`read`	Read projects, locales, keys, translations, orders
`write`	Write projects, locales, keys, translations but not orders
`orders.create`	Create and confirm orders
`team.manage`	Manage invitations and members

List authorizations

GET /v2/authorizations

List all your authorizations.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/authorizations" \
  -u USERNAME

phraseapp authorizations list

Response

Status: 200
[
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "note": "My Deploy Script",
    "token_last_eight": "1234abcd",
    "hashed_token": "abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234",
    "scopes": [
      "read"
    ],
    "expires_at": "2015-03-30T09:52:53Z",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "note": "My Deploy Script",
    "token_last_eight": "1234abcd",
    "hashed_token": "abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234",
    "scopes": [
      "read"
    ],
    "expires_at": "2015-03-30T09:52:53Z",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single authorization

GET /v2/authorizations/:id

Get details on a single authorization.

Example Request

curl "https://api.phrase.com/v2/authorizations/:id" \
  -u USERNAME

phraseapp authorization show <id>

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "note": "My Deploy Script",
  "token_last_eight": "1234abcd",
  "hashed_token": "abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234",
  "scopes": [
    "read"
  ],
  "expires_at": "2015-03-30T09:52:53Z",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Create an authorization

POST /v2/authorizations

Create a new authorization.

Parameters

Name	Type	Description
`note`	`string`	A note to help you remember what the access is used for.
`scopes` optional	`array` of `strings`	A list of scopes that the access can be used for.
`expires_at` optional	`datetime`	Expiration date for the authorization token. Null means no expiration date (default).

Example Request

curl "https://api.phrase.com/v2/authorizations" \
  -u USERNAME \
  -X POST \
  -d '{"note":"My Deploy Script","scopes":["read","write"],"expires_at":"2015-03-30T09:52:53Z"}' \
  -H 'Content-Type: application/json'

phraseapp authorization create \
--note "My Deploy Script" \
--scopes "read,write" \
--expires-at "2015-03-30T09:52:53Z"

Response

Status: 201
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "note": "My Deploy Script",
  "token_last_eight": "1234abcd",
  "hashed_token": "abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234",
  "scopes": [
    "read"
  ],
  "expires_at": "2015-03-30T09:52:53Z",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "token": "abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234"
}

Update an authorization

PATCH /v2/authorizations/:id

Update an existing authorization.

Parameters

Name	Type	Description
`note`	`string`	A note to help you remember what the access is used for.
`scopes` optional	`array` of `strings`	A list of scopes that the access can be used for.
`expires_at` optional	`datetime`	Expiration date for the authorization token. Null means no expiration date (default).

Example Request

curl "https://api.phrase.com/v2/authorizations/:id" \
  -u USERNAME \
  -X PATCH \
  -d '{"note":"My Deploy Script","scopes":["read","write"],"expires_at":"2015-03-30T09:52:53Z"}' \
  -H 'Content-Type: application/json'

phraseapp authorization update <id> \
--note "My Deploy Script" \
--scopes "read,write" \
--expires-at "2015-03-30T09:52:53Z"

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "note": "My Deploy Script",
  "token_last_eight": "1234abcd",
  "hashed_token": "abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234abcd1234cdef1234",
  "scopes": [
    "read"
  ],
  "expires_at": "2015-03-30T09:52:53Z",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Delete an authorization

DELETE /v2/authorizations/:id

Delete an existing authorization. API calls using that token will stop working.

Example Request

curl "https://api.phrase.com/v2/authorizations/:id" \
  -u USERNAME \
  -X DELETE

phraseapp authorization delete <id>

Response

Status: 204

Users

Show current User

GET /v2/user

Show details for current User.

Example Request

curl "https://api.phrase.com/v2/user" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp show user

Response

Status: 200
{
  "id": "abcd1234cdef1234abcd1234cdef1234",
  "username": "joe.doe",
  "name": "Joe Doe",
  "email": "joe@phraseapp.com",
  "position": "Lead Developer",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z"
}

Accounts

List accounts

GET /v2/accounts

List all accounts the current user has access to.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp accounts list

Response

Status: 200
[
  {
    "id": "abcd1234",
    "name": "Company Account",
    "company": "My Awesome Company",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  },
  {
    "id": "abcd1234",
    "name": "Company Account",
    "company": "My Awesome Company",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
]

Get a single account

GET /v2/accounts/:id

Get details on a single account.

Example Request

curl "https://api.phrase.com/v2/accounts/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp account show <id>

Response

Status: 200
{
  "id": "abcd1234",
  "name": "Company Account",
  "company": "My Awesome Company",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "slug": "company-account"
}

Members

With the members endpoints you can do basic team and user management via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them.

List members

GET /v2/accounts/:account_id/members

Get all users active in the account. It also lists resources like projects and locales the member has access to. In case nothing is shown the default access from the role is used. Access token scope must include team.manage.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/members" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp members list <account_id>

Response

Status: 200
[
  {
    "id": "acbdacbdacbdacbdacbdacbd",
    "email": "foo@bar.com",
    "username": "myname",
    "role": "Manager",
    "projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z",
        "locales": [
          {
            "id": "abcd1234cdef1234abcd1234cdef1234",
            "name": "English",
            "code": "en-Gb"
          }
        ]
      }
    ],
    "permissions": [
      {
        "create_upload": true,
        "review_translations": true
      }
    ]
  },
  {
    "id": "acbdacbdacbdacbdacbdacbd",
    "email": "foo@bar.com",
    "username": "myname",
    "role": "Manager",
    "projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z",
        "locales": [
          {
            "id": "abcd1234cdef1234abcd1234cdef1234",
            "name": "English",
            "code": "en-Gb"
          }
        ]
      }
    ],
    "permissions": [
      {
        "create_upload": true,
        "review_translations": true
      }
    ]
  }
]

Get single member

GET /v2/accounts/:account_id/members/:id

Get details on a single user in the account. Access token scope must include team.manage.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/members/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp member show <account_id> <id>

Response

Status: 200
{
  "id": "acbdacbdacbdacbdacbdacbd",
  "email": "foo@bar.com",
  "username": "myname",
  "role": "Manager",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z",
      "locales": [
        {
          "id": "abcd1234cdef1234abcd1234cdef1234",
          "name": "English",
          "code": "en-Gb"
        }
      ]
    }
  ],
  "permissions": [
    {
      "create_upload": true,
      "review_translations": true
    }
  ]
}

Update a member

PATCH /v2/accounts/:account_id/members/:id

Update user permissions in the account. Developers and translators need project_ids and locale_ids assigned to access them. Access token scope must include team.manage.

Parameters

Name	Type	Description
`role`	`string`	Member role, can be any of of Manager, Developer, Translator
`project_ids` optional	`string`	List of project ids the user has access to.
`locale_ids` optional	`string`	List of locale ids the user has access to.
`permissions` optional	`hash`	Additional permissions depending on member role. Available permissions are `create_upload` and `review_translations`

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/members/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"role":"Developer","project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235","locale_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235","permissions":{"create_upload":true,"review_translations":true}}' \
  -H 'Content-Type: application/json'

phraseapp member update <account_id> <id> \
--role Developer \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--locale-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--permissions {"create_upload"=>true, "review_translations"=>true}

Response

Status: 200
{
  "id": "acbdacbdacbdacbdacbdacbd",
  "email": "foo@bar.com",
  "username": "myname",
  "role": "Manager",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z",
      "locales": [
        {
          "id": "abcd1234cdef1234abcd1234cdef1234",
          "name": "English",
          "code": "en-Gb"
        }
      ]
    }
  ],
  "permissions": [
    {
      "create_upload": true,
      "review_translations": true
    }
  ]
}

Remove a user from the account

DELETE /v2/accounts/:account_id/members/:id

Remove a user from the account. The user will be removed from the account but not deleted from Phrase. Access token scope must include team.manage.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/members/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp member delete <account_id> <id>

Response

Status: 204

Invitations

With the invitation endpoint you can manage and invite users to Phrase via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them.

List invitations

GET /v2/accounts/:account_id/invitations

List invitations for an account. It will also list the accessible resources like projects and locales the invited user has access to. In case nothing is shown the default access from the role is used. Access token scope must include team.manage.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/invitations" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp invitations list <account_id>

Response

Status: 200
[
  {
    "id": "acbdacbdacbdacbdacbdacbd",
    "email": "foo@bar.com",
    "role": "Manager",
    "state": "accepted",
    "projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ],
    "locales": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "English",
        "code": "en-GB"
      }
    ],
    "permissions": [
      {
        "create_upload": true,
        "review_translations": true
      }
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "accepted_at": "2015-02-28T09:52:53Z"
  },
  {
    "id": "acbdacbdacbdacbdacbdacbd",
    "email": "foo@bar.com",
    "role": "Manager",
    "state": "accepted",
    "projects": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "My Android Project",
        "main_format": "xml",
        "created_at": "2015-01-28T09:52:53Z",
        "updated_at": "2015-01-28T09:52:53Z"
      }
    ],
    "locales": [
      {
        "id": "abcd1234cdef1234abcd1234cdef1234",
        "name": "English",
        "code": "en-GB"
      }
    ],
    "permissions": [
      {
        "create_upload": true,
        "review_translations": true
      }
    ],
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "accepted_at": "2015-02-28T09:52:53Z"
  }
]

Get a single invitation

GET /v2/accounts/:account_id/invitations/:id

Get details on a single invitation. Access token scope must include team.manage.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/invitations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp invitation show <account_id> <id>

Response

Status: 200
{
  "id": "acbdacbdacbdacbdacbdacbd",
  "email": "foo@bar.com",
  "role": "Manager",
  "state": "accepted",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "permissions": [
    {
      "create_upload": true,
      "review_translations": true
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "accepted_at": "2015-02-28T09:52:53Z"
}

Create a new invitation

POST /v2/accounts/:account_id/invitations

Invite a person to an account. Developers and translators need project_ids and locale_ids assigned to access them. Access token scope must include team.manage.

Parameters

Name	Type	Description
`email`	`string`	The email of the invited user. The `email` can not be updated once created. Create a new invitation for each unique email.
`role`	`string`	Invitiation role, can be any of Manager, Developer, Translator.
`project_ids` optional	`string`	List of project ids the invited user has access to.
`locale_ids` optional	`string`	List of locale ids the invited user has access to.
`permissions` optional	`hash`	Additional permissions depending on invitation role. Available permissions are `create_upload` and `review_translations`

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/invitations" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"email":"example@mail.com","role":"Developer","project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235","locale_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235","permissions":{"create_upload":true,"review_translations":true}}' \
  -H 'Content-Type: application/json'

phraseapp invitation create <account_id> \
--email example@mail.com \
--role Developer \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--locale-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--permissions {"create_upload"=>true, "review_translations"=>true}

Response

Status: 201
{
  "id": "acbdacbdacbdacbdacbdacbd",
  "email": "foo@bar.com",
  "role": "Manager",
  "state": "accepted",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "permissions": [
    {
      "create_upload": true,
      "review_translations": true
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "accepted_at": "2015-02-28T09:52:53Z"
}

Update an invitation

PATCH /v2/accounts/:account_id/invitations/:id

Update an existing invitation (must not be accepted yet). The email cannot be updated. Developers and translators need project_ids and locale_ids assigned to access them. Access token scope must include team.manage.

Parameters

Name	Type	Description
`role`	`string`	Invitiation role, can be any of Manager, Developer, Translator
`project_ids` optional	`string`	List of project ids the invited user has access to
`locale_ids` optional	`string`	List of locale ids the invited user has access to
`permissions` optional	`hash`	Additional permissions depending on invitation role.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/invitations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"role":"Invitiation role","project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235","locale_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235","permissions":{"create_upload":true}}' \
  -H 'Content-Type: application/json'

phraseapp invitation update <account_id> <id> \
--role "Invitiation role" \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--locale-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--permissions {"create_upload"=>true}

Response

Status: 200
{
  "id": "acbdacbdacbdacbdacbdacbd",
  "email": "foo@bar.com",
  "role": "Manager",
  "state": "accepted",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "permissions": [
    {
      "create_upload": true,
      "review_translations": true
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "accepted_at": "2015-02-28T09:52:53Z"
}

Delete an invitation

DELETE /v2/accounts/:account_id/invitations/:id

Delete an existing invitation (must not be accepted yet). Access token scope must include team.manage.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/invitations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp invitation delete <account_id> <id>

Response

Status: 204

Resend an invitation

POST /v2/accounts/:account_id/invitations/:id/resend

Resend the invitation email (must not be accepted yet). Access token scope must include team.manage.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/invitations/:id/resend" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST

phraseapp invitation resend <account_id> <id>

Response

Status: 200
{
  "id": "acbdacbdacbdacbdacbdacbd",
  "email": "foo@bar.com",
  "role": "Manager",
  "state": "accepted",
  "projects": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "My Android Project",
      "main_format": "xml",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  ],
  "locales": [
    {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "English",
      "code": "en-GB"
    }
  ],
  "permissions": [
    {
      "create_upload": true,
      "review_translations": true
    }
  ],
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "accepted_at": "2015-02-28T09:52:53Z"
}

Screenshots

List screenshots

GET /v2/projects/:project_id/screenshots

List all screenshots for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp screenshots list <project_id>

Response

Status: 200
[
  {
    "id": "d2e056aa9e70b01121f41693e344f5ee",
    "name": "A screenshot name",
    "description": "A screenshot description",
    "screenshot_url": "http://assets.example.com/screenshot.png",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "markers_count": 0
  },
  {
    "id": "d2e056aa9e70b01121f41693e344f5ee",
    "name": "A screenshot name",
    "description": "A screenshot description",
    "screenshot_url": "http://assets.example.com/screenshot.png",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "markers_count": 0
  }
]

Get a single screenshot

GET /v2/projects/:project_id/screenshots/:id

Get details on a single screenshot for a given project.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp screenshot show <project_id> <id>

Response

Status: 200
{
  "id": "d2e056aa9e70b01121f41693e344f5ee",
  "name": "A screenshot name",
  "description": "A screenshot description",
  "screenshot_url": "http://assets.example.com/screenshot.png",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "markers_count": 0
}

Create a screenshot

POST /v2/projects/:project_id/screenshots

Create a new screenshot.

Parameters

Name	Type	Description
`name` optional	`string`	Name of the screenshot
`description` optional	`string`	Description of the screenshot
`filename`	`file`	Screenshot file

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F name=A%20screenshot%20name \
  -F description=A%20screenshot%20description \
  -F filename=@/path/to/my/screenshot.png

phraseapp screenshot create <project_id> \
--name "A screenshot name" \
--description "A screenshot description" \
--filename /path/to/my/screenshot.png

Response

Status: 201
{
  "id": "d2e056aa9e70b01121f41693e344f5ee",
  "name": "A screenshot name",
  "description": "A screenshot description",
  "screenshot_url": "http://assets.example.com/screenshot.png",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "markers_count": 0
}

Update a screenshot

PATCH /v2/projects/:project_id/screenshots/:id

Update an existing screenshot.

Parameters

Name	Type	Description
`name` optional	`string`	Name of the screenshot
`description` optional	`string`	Description of the screenshot
`filename`	`file`	Screenshot file

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -F name=A%20screenshot%20name \
  -F description=A%20screenshot%20description \
  -F filename=@/path/to/my/screenshot.png

phraseapp screenshot update <project_id> <id> \
--name "A screenshot name" \
--description "A screenshot description" \
--filename /path/to/my/screenshot.png

Response

Status: 200
{
  "id": "d2e056aa9e70b01121f41693e344f5ee",
  "name": "A screenshot name",
  "description": "A screenshot description",
  "screenshot_url": "http://assets.example.com/screenshot.png",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "markers_count": 0
}

Delete a screenshot

DELETE /v2/projects/:project_id/screenshots/:id

Delete an existing screenshot.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp screenshot delete <project_id> <id>

Response

Status: 204

Screenshot Markers

List screenshot markers

GET /v2/projects/:project_id/screenshots/:id/markers

List all screenshot markers for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:id/markers" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp screenshot_markers list <project_id> <id>

Response

Status: 200
[
  {
    "id": "d2e056aa9e70b01121f41693e344f5ee",
    "presentation": {
      "x": 10,
      "y": 10,
      "w": 10,
      "h": 10
    },
    "presentation_type": "default",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "translation_key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "description": "My description for this key...",
      "name_hash": "1b31d2580ce324f246f66b3be00ed399",
      "plural": false,
      "tags": [
        "awesome-feature",
        "needs-proofreading"
      ],
      "data_type": "string",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  },
  {
    "id": "d2e056aa9e70b01121f41693e344f5ee",
    "presentation": {
      "x": 10,
      "y": 10,
      "w": 10,
      "h": 10
    },
    "presentation_type": "default",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z",
    "translation_key": {
      "id": "abcd1234cdef1234abcd1234cdef1234",
      "name": "home.index.headline",
      "description": "My description for this key...",
      "name_hash": "1b31d2580ce324f246f66b3be00ed399",
      "plural": false,
      "tags": [
        "awesome-feature",
        "needs-proofreading"
      ],
      "data_type": "string",
      "created_at": "2015-01-28T09:52:53Z",
      "updated_at": "2015-01-28T09:52:53Z"
    }
  }
]

Get a single screenshot marker

GET /v2/projects/:project_id/screenshots/:screenshot_id/markers/:id

Get details on a single screenshot marker for a given project.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:screenshot_id/markers/:id" \
  -u USERNAME_OR_ACCESS_TOKEN

phraseapp screenshot_marker show <project_id> <screenshot_id> <id>

Response

Status: 200
{
  "id": "d2e056aa9e70b01121f41693e344f5ee",
  "presentation": {
    "x": 10,
    "y": 10,
    "w": 10,
    "h": 10
  },
  "presentation_type": "default",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "translation_key": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "description": "My description for this key...",
    "name_hash": "1b31d2580ce324f246f66b3be00ed399",
    "plural": false,
    "tags": [
      "awesome-feature",
      "needs-proofreading"
    ],
    "data_type": "string",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
}

Create a screenshot marker

POST /v2/projects/:project_id/screenshots/:screenshot_id/markers

Create a new screenshot marker.

Parameters

Name	Type	Description
`key_id`	`id`	Specify the Key ID which should be highlighted on the specified screenshot. The Key must belong to the project.
`presentation`	`string`	Presentation details of the screenshot marker in JSON format. Each Screenshot Marker is represented as a rectangular shaped highlight box with the name of the specified Key attached. You can specify the marker position on the screenshot (`x`-axis and `y`-axis in pixels) from the top left corner of the screenshot and the dimensions of the marker itself (`w` and `h` in pixels).

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:screenshot_id/markers" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"key_id":"abcd1234abcd1234abcd1234abcd1234","presentation":"{ \"x\": 100, \"y\": 100, \"w\": 100, \"h\": 100 }"}' \
  -H 'Content-Type: application/json'

phraseapp screenshot_marker create <project_id> <screenshot_id> \
--key-id abcd1234abcd1234abcd1234abcd1234 \
--presentation "{ "x": 100, "y": 100, "w": 100, "h": 100 }"

Response

Status: 201
{
  "id": "d2e056aa9e70b01121f41693e344f5ee",
  "presentation": {
    "x": 10,
    "y": 10,
    "w": 10,
    "h": 10
  },
  "presentation_type": "default",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "translation_key": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "description": "My description for this key...",
    "name_hash": "1b31d2580ce324f246f66b3be00ed399",
    "plural": false,
    "tags": [
      "awesome-feature",
      "needs-proofreading"
    ],
    "data_type": "string",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
}

Update a screenshot marker

PATCH /v2/projects/:project_id/screenshots/:screenshot_id/markers

Update an existing screenshot marker.

Parameters

Name	Type	Description
`key_id`	`id`	Specify the Key ID which should be highlighted on the specified screenshot. The Key must belong to the project.
`presentation`	`string`	Presentation details of the screenshot marker in JSON format. Each Screenshot Marker is represented as a rectangular shaped highlight box with the name of the specified Key attached. You can specify the marker position on the screenshot (`x`-axis and `y`-axis in pixels) from the top left corner of the screenshot and the dimensions of the marker itself (`w` and `h` in pixels).

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:screenshot_id/markers" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"key_id":"abcd1234abcd1234abcd1234abcd1234","presentation":"{ \"x\": 100, \"y\": 100, \"w\": 100, \"h\": 100 }"}' \
  -H 'Content-Type: application/json'

phraseapp screenshot_marker update <project_id> <screenshot_id> \
--key-id abcd1234abcd1234abcd1234abcd1234 \
--presentation "{ "x": 100, "y": 100, "w": 100, "h": 100 }"

Response

Status: 200
{
  "id": "d2e056aa9e70b01121f41693e344f5ee",
  "presentation": {
    "x": 10,
    "y": 10,
    "w": 10,
    "h": 10
  },
  "presentation_type": "default",
  "created_at": "2015-01-28T09:52:53Z",
  "updated_at": "2015-01-28T09:52:53Z",
  "translation_key": {
    "id": "abcd1234cdef1234abcd1234cdef1234",
    "name": "home.index.headline",
    "description": "My description for this key...",
    "name_hash": "1b31d2580ce324f246f66b3be00ed399",
    "plural": false,
    "tags": [
      "awesome-feature",
      "needs-proofreading"
    ],
    "data_type": "string",
    "created_at": "2015-01-28T09:52:53Z",
    "updated_at": "2015-01-28T09:52:53Z"
  }
}

Delete a screenshot marker

DELETE /v2/projects/:project_id/screenshots/:screenshot_id/markers

Delete an existing screenshot marker.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/screenshots/:screenshot_id/markers" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE

phraseapp screenshot_marker delete <project_id> <screenshot_id>

Response

Status: 204

Formats

List formats

GET /v2/formats

Get a handy list of all localization file formats supported in Phrase.

This endpoint does not require authentication

Example Request

curl "https://api.phrase.com/v2/formats"

phraseapp formats list

Response

Status: 200
[
  {
    "name": "Ruby/Rails YAML",
    "api_name": "yml",
    "description": "YAML file format for use with Ruby/Rails applications",
    "extension": "yml",
    "default_encoding": "UTF-8",
    "importable": true,
    "exportable": true,
    "default_file": "./config/locales/.yml",
    "renders_default_locale": false,
    "includes_locale_information": true
  },
  {
    "name": "Ruby/Rails YAML",
    "api_name": "yml",
    "description": "YAML file format for use with Ruby/Rails applications",
    "extension": "yml",
    "default_encoding": "UTF-8",
    "importable": true,
    "exportable": true,
    "default_file": "./config/locales/.yml",
    "renders_default_locale": false,
    "includes_locale_information": true
  }
]