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@phrase.com)
User-Agent: ACME Inc Python Client (http://example.com/contact)

If you don't send this header, you will receive a response with 400 Bad Request.

Lists

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

Lists are usually paginated.

Parameters

Many endpoints support additional parameters, e.g. for pagination. When passing them in a GET request you can send them as HTTP query string parameters:

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

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

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

Encoding parameters as JSON means better support for types (boolean, integer) and usually better readability. Don't forget to set the correct Content-Type for your request.

The Content-Type header is omitted in some of the following examples for better readbility.

Errors

Request Errors

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

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

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

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

Date Format

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

YYYY-MM-DDTHH:MM:SSZ

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

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

Example for CET (1 hour behind UTC):

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

Please note that in HTTP headers, we will use the appropriate recommended date formats instead of ISO 8601.

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 user:

  • 1000 requests per 5 minutes
  • 4 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

Note: Conditional GET requests are currently only supported for locales#download and translations#index

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.

$ curl -i -u EMAIL_OR_ACCESS_TOKEN "https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download"
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/1234abcd1234abcdefefabcd1234efab/locales/en/download" -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/1234abcd1234abcdefefabcd1234efab/locales/en/download" -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

NameTypeDescription
sort
optional
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder direction. Can be one of: asc, desc.
Default: asc
q
optional
stringSpecify 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
phrase translations list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* excluded:true' \
--access_token <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

NameTypeDescription
sort
optional
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder direction. Can be one of: asc, desc.
Default: asc
q
optional
stringSpecify 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
phrase translations list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* unverified:true' \
--access_token <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

NameTypeDescription
q
optional
stringSpecify 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
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder 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'
phrase translations verify \
--project_id <project_id> \
--data '{"query":""my dog unverified:true"", "sort":"updated_at", "order":"desc"}' \
--access_token <token>
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

NameTypeDescription
sort
optional
stringSort by field. Can be one of: name, created_at, updated_at.
Default: name
order
optional
stringOrder direction. Can be one of: asc, desc.
Default: asc
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
phrase keys list \
--project_id <project_id> \
--sort updated_at \
--order desc \
--query "updated_at:>=2013-02-21T00:00:00Z" \
--locale_id abcd1234abcd1234abcd1234abcd1234 \
--access_token <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

NameTypeDescription
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
phrase keys list \
--project_id <project_id> \
--query "tags:admin" \
--access_token <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

NameTypeDescription
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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 stringTag or comma-separated list of tags to add to the matching collection of keys
locale_id
optional
idLocale 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'
phrase keys tag \
--project_id <project_id> \
--data '{"query":"'dog* translated:true'", "tags":"landing-page,release-1.2", "locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token <token>
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

NameTypeDescription
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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 stringTag or comma-separated list of tags to remove from the matching collection of keys
locale_id
optional
idLocale 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'
phrase keys untag \
--project_id <project_id> \
--data '{"query":"'dog* translated:true'", "tags":"landing-page,release-1.2", "locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token <token>
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

NameTypeDescription
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
phrase keys list \
--project_id <project_id> \
--query "my dog" \
--access_token <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" (note backslashes before any whitespace character in the example query)

Parameters

NameTypeDescription
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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=name:my%5C%20dog%5C%20is%5C%20lazy" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase keys list \
--project_id <project_id> \
--query "name:my\ dog\ is\ lazy" \
--access_token <token>
phraseapp keys list <project_id> \
--query "name:my\ dog\ is\ lazy"

Find keys with wildcard character matching

GET /v2/projects/:project_id/keys

Example query *dog is*

Parameters

NameTypeDescription
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
phrase keys list \
--project_id <project_id> \
--query '*dog is*' \
--access_token <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

NameTypeDescription
file fileFile to be imported
file_format stringFile format. Auto-detected when possible and not specified.
locale_mapping[en] stringName of the column containing translations for locale en.
locale_mapping[de] stringName of the column containing translations for locale de.
format_options[comment_column] stringName of the column containing descriptions for keys.
format_options[tag_column] stringName of the column containing tags for keys.
format_options[key_name_column] stringName of the column containing the names of the keys.
format_options[first_content_row] stringName 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[tag_column]=E \
  -F format_options[key_name_column]=A \
  -F format_options[first_content_row]=2
phrase uploads create \
--project_id <project_id> \
--data '{"file":"/path/to/my/file.xlsx", "file_format":"xlsx", "locale_mapping[en]":"B", "locale_mapping[de]":"C", "format_options[comment_column]":"D", "format_options[tag_column]":"E", "format_options[key_name_column]":"A", "format_options[first_content_row]":"2"}' \
--access_token <token>
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[tag-column] E \
--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
phrase projects list \
--access_token <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
phrase projects show \
--id <id> \
--access_token <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

NameTypeDescription
name stringName of the project
main_format
optional
stringMain 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
booleanIndicates whether the project should share the account's translation memory
Default: false
project_image
optional
fileImage to identify the project
remove_project_image
optional
booleanIndicates whether the project image should be deleted.
Default: false
account_id
optional
stringAccount 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
phrase projects create \
--data '{"name":""My Android Project"", "main_format":"yml", "shares_translation_memory":"true", "project_image":"/path/to/my/project-screenshot.png", "account_id":"abcd1234"}' \
--access_token <token>
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

NameTypeDescription
name stringName of the project
main_format
optional
stringMain 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
booleanIndicates whether the project should share the account's translation memory
Default: false
project_image
optional
fileImage to identify the project
remove_project_image
optional
booleanIndicates whether the project image should be deleted.
Default: false
account_id
optional
stringAccount 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
phrase projects update \
--id <id> \
--data '{"name":""My Android Project"", "main_format":"yml", "shares_translation_memory":"true", "project_image":"/path/to/my/project-screenshot.png", "account_id":"abcd1234"}' \
--access_token <token>
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
phrase projects delete \
--id <id> \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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
phrase locales list \
--project_id <project_id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify 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
phrase locales show \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify the branch to use
name stringLocale name
code stringLocale ISO code
default
optional
booleanIndicates 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
booleanIndicates whether locale is a main locale. Main locales are part of the Verification System feature.
Default: false
rtl
optional
booleanIndicates whether locale is a RTL (Right-to-Left) locale.
Default: auto-detected
source_locale_id
optional
idSource locale. Can be the name or public id of the locale. Preferred is the public id.
unverify_new_translations
optional
booleanIndicates that new translations for this locale should be marked as unverified. Part of the Advanced Workflows feature.
Default: false
unverify_updated_translations
optional
booleanIndicates that updated translations for this locale should be marked as unverified. Part of the Advanced Workflows feature.
Default: false
autotranslate
optional
booleanIf 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'
phrase locales create \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "name":"de", "code":"de-DE", "source_locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
name stringLocale name
code stringLocale ISO code
default
optional
booleanIndicates 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
booleanIndicates whether locale is a main locale. Main locales are part of the Verification System feature.
Default: false
rtl
optional
booleanIndicates whether locale is a RTL (Right-to-Left) locale.
Default: auto-detected
source_locale_id
optional
idSource locale. Can be the name or public id of the locale. Preferred is the public id.
unverify_new_translations
optional
booleanIndicates that new translations for this locale should be marked as unverified. Part of the Advanced Workflows feature.
Default: false
unverify_updated_translations
optional
booleanIndicates that updated translations for this locale should be marked as unverified. Part of the Advanced Workflows feature.
Default: false
autotranslate
optional
booleanIf 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'
phrase locales update \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "name":"de", "code":"de-DE", "source_locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase locales delete \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
file_format stringFile format name. See the format guide for all supported file formats.
tags
optional
stringLimit results to keys tagged with a list of comma separated tag names.
tag
DEPRECATED

optional
stringLimit download to tagged keys. This parameter is deprecated. Please use the "tags" parameter instead
include_empty_translations
optional
booleanIndicates whether keys without translations should be included in the output as well.
Default: false
include_translated_keys
optional
booleanInclude translated keys in the locale file. Use in combination with include_empty_translations to obtain only untranslated keys.
Default: true
keep_notranslate_tags
optional
booleanIndicates whether [NOTRANSLATE] tags should be kept.
Default: false
convert_emoji
OBSOLETE

optional
booleanThis option is obsolete. Projects that were created on or after Nov 29th 2019 or that did not contain emoji by then will not require this flag any longer since emoji are now supported natively.
Default: false
format_options
optional
hashAdditional 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
stringEnforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1".
skip_unverified_translations
DEPRECATED

optional
booleanIndicates 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
booleanif set to false unverified translations are excluded
Default: true
use_last_reviewed_version
optional
booleanIf 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
stringIf 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
phrase locales download \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--file_format yml \
--tags feature1,feature2 \
--tag feature \
--access_token <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

NameTypeDescription
branch
optional
stringspecify the branch to use
sort
optional
stringSort by field. Can be one of: name, created_at, updated_at.
Default: name
order
optional
stringOrder direction. Can be one of: asc, desc.
Default: asc
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
idLocale 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
phrase keys list \
--project_id <project_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'mykey* translated:true' \
--locale_id abcd1234abcd1234abcd1234abcd1234 \
--access_token <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" } ]

Get a single key

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

Get details on a single key for a given project.

Parameters

NameTypeDescription
branch
optional
stringspecify 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
phrase keys show \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify the branch to use
name stringKey name
description
optional
stringKey description (usually includes contextual information for translators)
plural
optional
booleanIndicates whether key supports pluralization
Default: false
name_plural
optional
stringPlural name for the key (used in some file formats, e.g. Gettext)
data_type
optional
stringType of the key. Can be one of the following: string, number, boolean, array, markdown.
Default: string
tags
optional
stringList of tags separated by comma to be associated with the key.
max_characters_allowed
optional
integerMax. number of characters translations for this key can have.
screenshot
DEPRECATED

optional
fileScreenshot/image for the key. This parameter is deprecated. Please use the Screenshots endpoint instead.
remove_screenshot
DEPRECATED

optional
booleanIndicates whether the screenshot will be deleted. This parameter is deprecated. Please use the Screenshots endpoint instead.
Default: false
unformatted
optional
booleanIndicates whether the key should be exported as "unformatted". Supported by Android XML and other formats.
Default: false
xml_space_preserve
optional
booleanIndicates whether the key should be exported with "xml:space=preserve". Supported by several XML-based formats.
Default: false
original_file
optional
stringOriginal file attribute. Used in some formats, e.g. XLIFF.
localized_format_string
optional
stringNSStringLocalizedFormatKey attribute. Used in .stringsdict format.
localized_format_key
optional
stringNSStringLocalizedFormatKey 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
phrase keys create \
--project_id <project_id> \
--data '{"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"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
name stringKey name
description
optional
stringKey description (usually includes contextual information for translators)
plural
optional
booleanIndicates whether key supports pluralization
Default: false
name_plural
optional
stringPlural name for the key (used in some file formats, e.g. Gettext)
data_type
optional
stringType of the key. Can be one of the following: string, number, boolean, array, markdown.
Default: string
tags
optional
stringList of tags separated by comma to be associated with the key.
max_characters_allowed
optional
integerMax. number of characters translations for this key can have.
screenshot
DEPRECATED

optional
fileScreenshot/image for the key. This parameter is deprecated. Please use the Screenshots endpoint instead.
remove_screenshot
DEPRECATED

optional
booleanIndicates whether the screenshot will be deleted. This parameter is deprecated. Please use the Screenshots endpoint instead.
Default: false
unformatted
optional
booleanIndicates whether the key should be exported as "unformatted". Supported by Android XML and other formats.
Default: false
xml_space_preserve
optional
booleanIndicates whether the key should be exported with "xml:space=preserve". Supported by several XML-based formats.
Default: false
original_file
optional
stringOriginal file attribute. Used in some formats, e.g. XLIFF.
localized_format_string
optional
stringNSStringLocalizedFormatKey attribute. Used in .stringsdict format.
localized_format_key
optional
stringNSStringLocalizedFormatKey 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
phrase keys update \
--project_id <project_id> \
--id <id> \
--data '{"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"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase keys delete \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
idLocale 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'
phrase keys delete \
--project_id <project_id> \
--branch my-feature-branch \
--query 'mykey* translated:true' \
--locale_id abcd1234abcd1234abcd1234abcd1234 \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
idLocale used to determine the translation state of a key when filtering for untranslated or translated keys.
tags stringTag 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'
phrase keys tag \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "query":"'mykey* translated:true'", "locale_id":"abcd1234abcd1234abcd1234abcd1234", "tags":"landing-page,release-1.2"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify a query to do broad search for 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 exact key names - whitespaces need to be prefixed with a backspace ("\")
  • 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
idLocale used to determine the translation state of a key when filtering for untranslated or translated keys.
tags stringTag 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'
phrase keys untag \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "query":"'mykey* translated:true'", "locale_id":"abcd1234abcd1234abcd1234abcd1234", "tags":"landing-page,release-1.2"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
sort
optional
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder direction. Can be one of: asc, desc.
Default: asc
q
optional
stringSpecify 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
phrase translations list \
--project_id <project_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center' \
--access_token <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}" ], "state": "translated", "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}" ], "state": "translated", "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

NameTypeDescription
branch
optional
stringspecify the branch to use
sort
optional
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder direction. Can be one of: asc, desc.
Default: asc
q
optional
stringSpecify 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
phrase translations by_locale \
--project_id <project_id> \
--locale_id <locale_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center' \
--access_token <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}" ], "state": "translated", "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}" ], "state": "translated", "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

NameTypeDescription
branch
optional
stringspecify the branch to use
sort
optional
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder direction. Can be one of: asc, desc.
Default: asc
q
optional
stringSpecify 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
phrase translations by_key \
--project_id <project_id> \
--key_id <key_id> \
--branch my-feature-branch \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center' \
--access_token <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}" ], "state": "translated", "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}" ], "state": "translated", "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

NameTypeDescription
branch
optional
stringspecify 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
phrase translations show \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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}" ], "state": "translated", "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

NameTypeDescription
branch
optional
stringspecify the branch to use
locale_id idLocale. Can be the name or public id of the locale. Preferred is the public id.
key_id idKey
content stringTranslation content
plural_suffix
optional
stringPlural 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
booleanIndicates whether translation is unverified. Part of the Advanced Workflows feature.
Default: false
excluded
optional
booleanIndicates whether translation is excluded.
Default: false
autotranslate
optional
booleanIndicates whether the translation should be auto-translated. Responses with status 422 if provided for translation within a non-default locale or the project does not have the Autopilot feature enabled.
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'
phrase translations create \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "locale_id":"abcd1234cdef1234abcd1234cdef1234", "key_id":"abcd1234cdef1234abcd1234cdef1234", "content":""My translation""}' \
--access_token <token>
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}" ], "state": "translated", "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

NameTypeDescription
branch
optional
stringspecify the branch to use
content stringTranslation content
plural_suffix
optional
stringPlural 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
booleanIndicates whether translation is unverified. Part of the Advanced Workflows feature.
Default: false
excluded
optional
booleanIndicates whether translation is excluded.
Default: false
autotranslate
optional
booleanIndicates whether the translation should be auto-translated. Responses with status 422 if provided for translation within a non-default locale or the project does not have the Autopilot feature enabled.
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'
phrase translations update \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "content":""My translation""}' \
--access_token <token>
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}" ], "state": "translated", "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 a translation

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

Verify an existing translation.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:id/verify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'
phrase translations verify \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
phraseapp translation verify <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}" ], "state": "translated", "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 }

Mark a translation as unverified

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

Mark an existing translation as unverified.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:id/unverify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'
phrase translations unverify \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
phraseapp translation unverify <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}" ], "state": "translated", "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 }

Review a translation

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

Mark an existing translation as reviewed.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:id/review" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'
phrase translations review \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
phraseapp translation review <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}" ], "state": "translated", "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 }

Exclude a translation from export

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

Set exclude from export flag on an existing translation.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:id/exclude" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'
phrase translations exclude \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
phraseapp translation exclude <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}" ], "state": "translated", "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 }

Revoke exclusion of a translation in export

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

Remove exclude from export flag from an existing translation.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/translations/:id/include" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'
phrase translations include \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
phraseapp translation include <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}" ], "state": "translated", "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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify 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
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder 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'
phrase translations verify \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "query":"'PhraseApp*%20unverified:true%20tags:feature,center'", "sort":"updated_at", "order":"desc"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify 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
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder 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'
phrase translations unverify \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "query":"'PhraseApp*%20verified:true%20tags:feature,center'", "sort":"updated_at", "order":"desc"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify 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'
phrase translations review \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "query":"'PhraseApp*%reviewed:false%20tags:feature,center'"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify 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
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder 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'
phrase translations exclude \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "query":"'PhraseApp*%20verified:true%20tags:feature,center'", "sort":"updated_at", "order":"desc"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
q
optional
stringSpecify 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
stringSort criteria. Can be one of: key_name, created_at, updated_at.
Default: key_name
order
optional
stringOrder 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'
phrase translations include \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "query":"'PhraseApp*%20verified:true%20tags:feature,center'", "sort":"updated_at", "order":"desc"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
file fileFile to be imported
file_format
optional
stringFile format. Auto-detected when possible and not specified.
locale_id
optional
idLocale of the file's content. Can be the name or public id of the locale. Preferred is the public id.
tags
optional
stringList of tags separated by comma to be associated with the new keys contained in the upload.
update_translations
optional
booleanIndicates whether existing translations should be updated with the file content.
Default: false
update_descriptions
optional
booleanExisting key descriptions will be updated with the file content. Empty descriptions overwrite existing descriptions.
Default: false
convert_emoji
OBSOLETE

optional
booleanThis option is obsolete. Providing the option will cause a bad request error.
Default: false
skip_upload_tags
optional
booleanIndicates whether the upload should not create upload tags.
Default: false
skip_unverification
optional
booleanIndicates whether the upload should unverify updated translations.
Default: false
file_encoding
optional
stringEnforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1".
locale_mapping
optional
hashOptional, format specific mapping between locale names and the columns the translations to those locales are contained in.
format_options
optional
hashAdditional options available for specific formats. See our format guide for complete list.
autotranslate
optional
booleanIf set, translations for the uploaded language will be fetched automatically.
Default: false
mark_reviewed
optional
booleanIndicated 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[en]=2 \
  -F format_options[foo]=bar
phrase uploads create \
--project_id <project_id> \
--data '{"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"}""}' \
--access_token <token>
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", "tag": "tag", "summary": { "locales_created": 2, "translation_keys_created": 162, "translation_keys_updated": 10, "translation_keys_unmentioned": 0, "translations_created": 291, "translations_updated": 3, "tags_created": 2, "translation_keys_ignored": 0 }, "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

NameTypeDescription
branch
optional
stringspecify 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
phrase uploads show \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
phraseapp upload show <project_id> <id> \
--branch my-feature-branch

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "filename": "example.json", "format": "json", "state": "success", "tag": "tag", "summary": { "locales_created": 2, "translation_keys_created": 162, "translation_keys_updated": 10, "translation_keys_unmentioned": 0, "translations_created": 291, "translations_updated": 3, "tags_created": 2, "translation_keys_ignored": 0 }, "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

NameTypeDescription
branch
optional
stringspecify 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
phrase uploads list \
--project_id <project_id> \
--branch my-feature-branch \
--access_token <token>
phraseapp uploads list <project_id> \
--branch my-feature-branch

Response

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

Tags

List tags

GET /v2/projects/:project_id/tags

List all tags for the given project.

This endpoint is paginated.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/tags?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase tags list \
--project_id <project_id> \
--branch my-feature-branch \
--access_token <token>
phraseapp tags list <project_id> \
--branch my-feature-branch

Response

Status: 200
[ { "name": "my-feature", "keys_count": 8, "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" }, { "name": "my-feature", "keys_count": 8, "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ]

Get a single tag

GET /v2/projects/:project_id/tags/:name

Get details and progress information on a single tag for a given project.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/tags/:name?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase tags show \
--project_id <project_id> \
--name <name> \
--branch my-feature-branch \
--access_token <token>
phraseapp tag show <project_id> <name> \
--branch my-feature-branch

Response

Status: 200
{ "name": "my-feature", "keys_count": 8, "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z", "statistics": [ { "locale": { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "de", "code": "de-DE" }, "statistics": { "keys_total_count": 12, "translations_completed_count": 9, "translations_unverified_count": 11, "keys_untranslated_count": 3 } } ] }

Create a tag

POST /v2/projects/:project_id/tags

Create a new tag.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use
name stringName of the tag

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/tags" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"branch":"my-feature-branch","name":"my-feature"}' \
  -H 'Content-Type: application/json'
phrase tags create \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "name":"my-feature"}' \
--access_token <token>
phraseapp tag create <project_id> \
--branch my-feature-branch \
--name my-feature

Response

Status: 201
{ "name": "my-feature", "keys_count": 8, "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z", "statistics": [ { "locale": { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "de", "code": "de-DE" }, "statistics": { "keys_total_count": 12, "translations_completed_count": 9, "translations_unverified_count": 11, "keys_untranslated_count": 3 } } ] }

Delete a tag

DELETE /v2/projects/:project_id/tags/:name

Delete an existing tag.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/tags/:name" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"branch":"my-feature-branch"}' \
  -H 'Content-Type: application/json'
phrase tags delete \
--project_id <project_id> \
--name <name> \
--branch my-feature-branch \
--access_token <token>
phraseapp tag delete <project_id> <name> \
--branch my-feature-branch

Response

Status: 204

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
phrase blacklisted_keys list \
--project_id <project_id> \
--access_token <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
phrase blacklisted_keys show \
--project_id <project_id> \
--id <id> \
--access_token <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

NameTypeDescription
name stringBlacklisted 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'
phrase blacklisted_keys create \
--project_id <project_id> \
--data '{"name":"'date.formats.*'"}' \
--access_token <token>
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

NameTypeDescription
name stringBlacklisted 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'
phrase blacklisted_keys update \
--project_id <project_id> \
--id <id> \
--data '{"name":"'date.formats.*'"}' \
--access_token <token>
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
phrase blacklisted_keys delete \
--project_id <project_id> \
--id <id> \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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
phrase versions list \
--project_id <project_id> \
--translation_id <translation_id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify 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
phrase versions show \
--project_id <project_id> \
--translation_id <translation_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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" } }

Spaces

List Spaces

GET /v2/accounts/:account_id/spaces

List all Spaces for the given account.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase spaces list \
--account_id <account_id> \
--access_token <token>
phraseapp spaces list <account_id>

Response

Status: 200
[ { "id": "2e7574e8f2372906a03110c2a7cfe671", "name": "My first space", "created_at": "2020-02-25T12:17:25Z", "updated_at": "2020-03-13T14:46:57Z", "projects_count": 2, "projects": [ { "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": "abcd11231fadef1234adacd1234cdef1234", "name": "My IOS Project", "main_format": "yml", "project_image_url": "http://assets.example.com/project2.png", "account": "account", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ] }, { "id": "2e7574e8f2372906a03110c2a7cfe671", "name": "My first space", "created_at": "2020-02-25T12:17:25Z", "updated_at": "2020-03-13T14:46:57Z", "projects_count": 2, "projects": [ { "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": "abcd11231fadef1234adacd1234cdef1234", "name": "My IOS Project", "main_format": "yml", "project_image_url": "http://assets.example.com/project2.png", "account": "account", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ] } ]

Get Space

GET /v2/accounts/:account_id/spaces/:id

Show the specified Space.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase spaces show \
--account_id <account_id> \
--id <id> \
--access_token <token>
phraseapp space show <account_id> <id>

Response

Status: 200
{ "id": "2e7574e8f2372906a03110c2a7cfe671", "name": "My first space", "created_at": "2020-02-25T12:17:25Z", "updated_at": "2020-03-13T14:46:57Z", "projects_count": 2, "projects": [ { "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": "abcd11231fadef1234adacd1234cdef1234", "name": "My IOS Project", "main_format": "yml", "project_image_url": "http://assets.example.com/project2.png", "account": "account", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ] }

Create a Space

POST /v2/accounts/:account_id/spaces

Create a new Space.

Parameters

NameTypeDescription
name stringName of the space

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"name":"My Android Projects"}' \
  -H 'Content-Type: application/json'
phrase spaces create \
--account_id <account_id> \
--data '{"name":""My Android Projects""}' \
--access_token <token>
phraseapp space create <account_id> \
--name "My Android Projects"

Response

Status: 201
{ "id": "2e7574e8f2372906a03110c2a7cfe671", "name": "My first space", "created_at": "2020-02-25T12:17:25Z", "updated_at": "2020-03-13T14:46:57Z", "projects_count": 2, "projects": [ { "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": "abcd11231fadef1234adacd1234cdef1234", "name": "My IOS Project", "main_format": "yml", "project_image_url": "http://assets.example.com/project2.png", "account": "account", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ] }

Update Space

PATCH /v2/accounts/:account_id/spaces/:id

Update the specified Space.

Parameters

NameTypeDescription
name
optional
stringNew name of the space

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"name":"My Android Projects"}' \
  -H 'Content-Type: application/json'
phrase spaces update \
--account_id <account_id> \
--id <id> \
--data '{"name":""My Android Projects""}' \
--access_token <token>
phraseapp space update <account_id> <id> \
--name "My Android Projects"

Response

Status: 200
{ "id": "2e7574e8f2372906a03110c2a7cfe671", "name": "My first space", "created_at": "2020-02-25T12:17:25Z", "updated_at": "2020-03-13T14:46:57Z", "projects_count": 2, "projects": [ { "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": "abcd11231fadef1234adacd1234cdef1234", "name": "My IOS Project", "main_format": "yml", "project_image_url": "http://assets.example.com/project2.png", "account": "account", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ] }

Delete Space

DELETE /v2/accounts/:account_id/spaces/:id

Delete the specified Space.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phrase spaces delete \
--account_id <account_id> \
--id <id> \
--access_token <token>
phraseapp space delete <account_id> <id>

Response

Status: 204

List Projects

GET /v2/accounts/:account_id/spaces/:space_id/projects

List all projects for the specified Space.

This endpoint is paginated.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces/:space_id/projects" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase spaces projects \
--account_id <account_id> \
--space_id <space_id> \
--access_token <token>
phraseapp spaces projects list <account_id> <space_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" }, { "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" } ]

Add Project

POST /v2/accounts/:account_id/spaces/:space_id/projects

Adds an existing project to the space.

Parameters

NameTypeDescription
id stringProject ID to add or to the Space

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces/:space_id/projects" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"id":"a4b3c2d1"}' \
  -H 'Content-Type: application/json'
phrase spaces projects \
--account_id <account_id> \
--space_id <space_id> \
--data '{"id":"a4b3c2d1"}' \
--access_token <token>
phraseapp spaces projects create <account_id> <space_id> \
--id a4b3c2d1

Response

Status: 201

Remove Project

DELETE /v2/accounts/:account_id/spaces/:space_id/projects/:id

Removes a specified project from the specified space.

Example Request

curl "https://api.phrase.com/v2/accounts/:account_id/spaces/:space_id/projects/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phrase spaces projects \
--account_id <account_id> \
--space_id <space_id> \
--id <id> \
--access_token <token>
phraseapp spaces projects delete <account_id> <space_id> <id>

Response

Status: 204

Jobs

List jobs

GET /v2/projects/:project_id/jobs

List all jobs for the given project.

This endpoint is paginated.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use
owned_by stringfilter by user owning job
assigned_to stringfilter by user assigned to job
state stringfilter 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
phrase jobs list \
--project_id <project_id> \
--branch my-feature-branch \
--owned_by abcd1234cdef1234abcd1234cdef1234 \
--assigned_to abcd1234cdef1234abcd1234cdef1234 \
--state completed \
--access_token <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

NameTypeDescription
branch
optional
stringspecify 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
phrase jobs show \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify the branch to use
name stringJob name
briefing
optional
stringBriefing for the translators
due_date
optional
datetimeDate the job should be finished
tags array of stringstags of keys that should be included within the job
translation_key_ids array of stringsids 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'
phrase jobs create \
--project_id <project_id> \
--data '{"branch":"my-feature-branch", "name":"de", "briefing":"de-DE", "due_date":"2017-08-15", "tags":""myUploadTag"", "translation_key_ids":""abcd1234cdef1234abcd1234cdef1234""}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
name stringJob name
briefing
optional
stringBriefing for the translators
due_date
optional
datetimeDate 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'
phrase jobs update \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "name":"de", "briefing":"de-DE", "due_date":"2017-08-15"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase jobs delete \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase jobs start \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase jobs complete \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase jobs reopen \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
translation_key_ids array of stringsids 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'
phrase jobs keys \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "translation_key_ids":""abcd1234cdef1234abcd1234cdef1234""}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
translation_key_ids array of stringsids 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'
phrase jobs keys \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--translation_key_ids "abcd1234cdef1234abcd1234cdef1234" \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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
phrase job_locales list \
--project_id <project_id> \
--job_id <job_id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify 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
phrase job_locales show \
--project_id <project_id> \
--job_id <job_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify the branch to use
locale_id stringlocale id
user_ids
optional
array of stringsArray 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'
phrase job_locales create \
--project_id <project_id> \
--job_id <job_id> \
--data '{"branch":"my-feature-branch", "locale_id":"abcd1234cdef1234abcd1234cdef1234", "user_ids":""abcd1234cdef1234abcd1234cdef1234""}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
locale_id stringlocale id
user_ids
optional
array of stringsArray 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'
phrase job_locales update \
--project_id <project_id> \
--job_id <job_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "locale_id":"abcd1234cdef1234abcd1234cdef1234", "user_ids":""abcd1234cdef1234abcd1234cdef1234""}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase job_locales delete \
--project_id <project_id> \
--job_id <job_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase job_locales complete \
--project_id <project_id> \
--job_id <job_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase job_locales reopen \
--project_id <project_id> \
--job_id <job_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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
phrase comments list \
--project_id <project_id> \
--key_id <key_id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify 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
phrase comments show \
--project_id <project_id> \
--key_id <key_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify the branch to use
message stringComment 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'
phrase comments create \
--project_id <project_id> \
--key_id <key_id> \
--data '{"branch":"my-feature-branch", "message":""Some message...""}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify the branch to use
message stringComment 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'
phrase comments update \
--project_id <project_id> \
--key_id <key_id> \
--id <id> \
--data '{"branch":"my-feature-branch", "message":""Some message...""}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase comments delete \
--project_id <project_id> \
--key_id <key_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase comments mark \
--project_id <project_id> \
--key_id <key_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase comments mark \
--project_id <project_id> \
--key_id <key_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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
phrase comments mark \
--project_id <project_id> \
--key_id <key_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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
phrase branches list \
--project_id <project_id> \
--access_token <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/:name

Get details on a single branch for a given project.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:name" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase branches show \
--project_id <project_id> \
--name <name> \
--access_token <token>
phraseapp branch show <project_id> <name>

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

NameTypeDescription
name stringName 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'
phrase branches create \
--project_id <project_id> \
--data '{"name":"my-branch"}' \
--access_token <token>
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/:name

Update an existing branch.

Parameters

NameTypeDescription
name stringName of the branch

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:name" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"name":"my-branch"}' \
  -H 'Content-Type: application/json'
phrase branches update \
--project_id <project_id> \
--name <name> \
--data '{"name":"my-branch"}' \
--access_token <token>
phraseapp branch update <project_id> <name> \
--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/:name

Delete an existing branch.

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:name" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phrase branches delete \
--project_id <project_id> \
--name <name> \
--access_token <token>
phraseapp branch delete <project_id> <name>

Response

Status: 204

Merge a branch

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

Merge an existing branch.

Parameters

NameTypeDescription
strategy
optional
stringstrategy used for merge blocking, use_master or use_branch
Default: blocking

Example Request

curl "https://api.phrase.com/v2/projects/:project_id/branches/:name/merge" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"strategy":"use_master"}' \
  -H 'Content-Type: application/json'
phrase branches merge \
--project_id <project_id> \
--name <name> \
--data '{"strategy":"use_master"}' \
--access_token <token>
phraseapp branch merge <project_id> <name> \
--strategy use_master

Response

Status: 200

Compare branches

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

Compare branch with main branch.

Parameters

NameTypeDescription
name stringName 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/:name/compare?name=my-branch" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase branches compare \
--project_id <project_id> \
--name <name> \
--name my-branch \
--access_token <token>
phraseapp branch compare <project_id> <name> \
--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
phrase glossaries list \
--account_id <account_id> \
--access_token <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" } ], "spaces": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Project Space", "projects_count": 1, "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" } ], "spaces": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Project Space", "projects_count": 1, "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
phrase glossaries show \
--account_id <account_id> \
--id <id> \
--access_token <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" } ], "spaces": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Project Space", "projects_count": 1, "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

NameTypeDescription
name stringName of the glossary
project_ids
optional
stringList of project ids the glossary should be assigned to.
space_ids
optional
array of stringsList of space 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","space_ids":["abcd1234abcd1234abcd1234","abcd1234abcd1234abcd1235"]}' \
  -H 'Content-Type: application/json'
phrase glossaries create \
--account_id <account_id> \
--data '{"name":""My glossary"", "project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "space_ids":""abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235""}' \
--access_token <token>
phraseapp glossary create <account_id> \
--name "My glossary" \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--space-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" } ], "spaces": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Project Space", "projects_count": 1, "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

NameTypeDescription
name stringName of the glossary
project_ids
optional
stringList of project ids the glossary should be assigned to.
space_ids
optional
array of stringsList of space 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","space_ids":["abcd1234abcd1234abcd1234","abcd1234abcd1234abcd1235"]}' \
  -H 'Content-Type: application/json'
phrase glossaries update \
--account_id <account_id> \
--id <id> \
--data '{"name":""My glossary"", "project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "space_ids":""abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235""}' \
--access_token <token>
phraseapp glossary update <account_id> <id> \
--name "My glossary" \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--space-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" } ], "spaces": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Project Space", "projects_count": 1, "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
phrase glossaries delete \
--account_id <account_id> \
--id <id> \
--access_token <token>
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
phrase glossary_terms list \
--account_id <account_id> \
--glossary_id <glossary_id> \
--access_token <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
phrase glossary_terms show \
--account_id <account_id> \
--glossary_id <glossary_id> \
--id <id> \
--access_token <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

NameTypeDescription
term stringGlossary term
description
optional
stringDescription of term
Default:
translatable
optional
booleanIndicates whether the term should be used for all languages or can be translated
Default: false
case_sensitive
optional
booleanIndicates 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'
phrase glossary_terms create \
--account_id <account_id> \
--glossary_id <glossary_id> \
--data '{"term":"MyCompany", "description":""Use this when refering to our company"", "translatable":"true", "case_sensitive":"true"}' \
--access_token <token>
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

NameTypeDescription
term stringGlossary term
description
optional
stringDescription of term
Default:
translatable
optional
booleanIndicates whether the term should be used for all languages or can be translated
Default: false
case_sensitive
optional
booleanIndicates 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'
phrase glossary_terms update \
--account_id <account_id> \
--glossary_id <glossary_id> \
--id <id> \
--data '{"term":"MyCompany", "description":""Use this when refering to our company"", "translatable":"true", "case_sensitive":"true"}' \
--access_token <token>
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
phrase glossary_terms delete \
--account_id <account_id> \
--glossary_id <glossary_id> \
--id <id> \
--access_token <token>
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

NameTypeDescription
locale_code stringIdentifies the language for this translation
content
optional
stringThe 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'
phrase glossary_term_translations create \
--account_id <account_id> \
--glossary_id <glossary_id> \
--term_id <term_id> \
--data '{"locale_code":"en-US", "content":""My translated term""}' \
--access_token <token>
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

NameTypeDescription
locale_code stringIdentifies the language for this translation
content
optional
stringThe 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'
phrase glossary_term_translations update \
--account_id <account_id> \
--glossary_id <glossary_id> \
--term_id <term_id> \
--id <id> \
--data '{"locale_code":"en-US", "content":""My translated term""}' \
--access_token <token>
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
phrase glossary_term_translations delete \
--account_id <account_id> \
--glossary_id <glossary_id> \
--term_id <term_id> \
--id <id> \
--access_token <token>
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

NameTypeDescription
account_id
optional
stringAccount 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
phrase bitbucket_sync list \
--account_id abcd1234 \
--access_token <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

NameTypeDescription
account_id
optional
stringAccount 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'
phrase bitbucket_sync export \
--id <id> \
--data '{"account_id":"abcd1234"}' \
--access_token <token>
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

NameTypeDescription
account_id
optional
stringAccount 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'
phrase bitbucket_sync import \
--id <id> \
--data '{"account_id":"abcd1234"}' \
--access_token <token>
phraseapp bitbucket_sync import <id> \
--account-id abcd1234

Response

Status: 200

GitLab Sync

List GitLab syncs

GET /v2/gitlab_syncs

List all GitLab Sync Settings for which synchronisation with Phrase and GitLab is activated.

Parameters

NameTypeDescription
account_id
optional
stringAccount ID to specify the actual account the GitLab Sync should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/gitlab_syncs?account_id=abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase gitlab_syncs list \
--account_id abcd1234 \
--access_token <token>
phraseapp gitlab_sync list \
--account-id abcd1234

Response

Status: 200
[ { "id": "abcd1234cdef1234abcd1234cdef1234", "project_id": "ft5yufdh1234cdef1234abc5d12d4cdef123", "gitlab_project_id": 18188930, "gitlab_branch_name": "master", "auto_import": true, "auto_import_secret": "import_secret", "auto_import_url": "import_url", "self_hosted_api_url": "www.example.com/api/v4", "last_exported_at": "2015-01-28T12:55:14.000+00:00", "last_imported_at": "2015-01-28T12:55:14.000+00:00", "last_status": "success" }, { "id": "abcd1234cdef1234abcd1234cdef1234", "project_id": "ft5yufdh1234cdef1234abc5d12d4cdef123", "gitlab_project_id": 18188930, "gitlab_branch_name": "master", "auto_import": true, "auto_import_secret": "import_secret", "auto_import_url": "import_url", "self_hosted_api_url": "www.example.com/api/v4", "last_exported_at": "2015-01-28T12:55:14.000+00:00", "last_imported_at": "2015-01-28T12:55:14.000+00:00", "last_status": "success" } ]

Get single Sync Setting

GET /v2/gitlab_syncs/:id

Shows a single GitLab Sync Setting.

Parameters

NameTypeDescription
account_id
optional
stringAccount ID to specify the actual account the GitLab Sync should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/gitlab_syncs/:id?account_id=abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase gitlab_syncs show \
--id <id> \
--account_id abcd1234 \
--access_token <token>
phraseapp gitlab_sync show <id> \
--account-id abcd1234

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "project_id": "ft5yufdh1234cdef1234abc5d12d4cdef123", "gitlab_project_id": 18188930, "gitlab_branch_name": "master", "auto_import": true, "auto_import_secret": "import_secret", "auto_import_url": "import_url", "self_hosted_api_url": "www.example.com/api/v4", "last_exported_at": "2015-01-28T12:55:14.000+00:00", "last_imported_at": "2015-01-28T12:55:14.000+00:00", "last_status": "success" }

Update single Sync Setting

PUT /v2/gitlab_syncs/:id

Updates a single GitLab Sync Setting.

Parameters

NameTypeDescription
account_id
optional
stringAccount ID to specify the actual account the GitLab Sync should be created in. Required if the requesting user is a member of multiple accounts.
phrase_project_code stringCode of the related Phrase Project.
gitlab_project_id integerID of the related GitLab Project.
gitlab_branch_name stringName of the GitLab Branch.

Example Request

curl "https://api.phrase.com/v2/gitlab_syncs/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PUT \
  -d '{"account_id":"abcd1234","phrase_project_code":"3456abcd","gitlab_project_id":12345,"gitlab_branch_name":"feature-development"}' \
  -H 'Content-Type: application/json'
phrase gitlab_syncs update \
--id <id> \
--data '{"account_id":"abcd1234", "phrase_project_code":"3456abcd", "gitlab_project_id":"12345", "gitlab_branch_name":"feature-development"}' \
--access_token <token>
phraseapp gitlab_sync update <id> \
--account-id abcd1234 \
--phrase-project-code 3456abcd \
--gitlab-project-id 12345 \
--gitlab-branch-name feature-development

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "project_id": "ft5yufdh1234cdef1234abc5d12d4cdef123", "gitlab_project_id": 18188930, "gitlab_branch_name": "master", "auto_import": true, "auto_import_secret": "import_secret", "auto_import_url": "import_url", "self_hosted_api_url": "www.example.com/api/v4", "last_exported_at": "2015-01-28T12:55:14.000+00:00", "last_imported_at": "2015-01-28T12:55:14.000+00:00", "last_status": "success" }

Delete single Sync Setting

DELETE /v2/gitlab_syncs/:id

Deletes a single GitLab Sync Setting.

Parameters

NameTypeDescription
account_id
optional
stringAccount ID to specify the actual account the GitLab Sync should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/gitlab_syncs/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"account_id":"abcd1234"}' \
  -H 'Content-Type: application/json'
phrase gitlab_syncs delete \
--id <id> \
--account_id abcd1234 \
--access_token <token>
phraseapp gitlab_sync delete <id> \
--account-id abcd1234

Response

Status: 204

Import from GitLab to Phrase

POST /v2/gitlab_syncs/:gitlab_sync_id/import

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

Parameters

NameTypeDescription
account_id
optional
stringAccount ID to specify the actual account the GitLab Sync should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/gitlab_syncs/:gitlab_sync_id/import" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"account_id":"abcd1234"}' \
  -H 'Content-Type: application/json'
phrase gitlab_syncs import \
--gitlab_sync_id <gitlab_sync_id> \
--data '{"account_id":"abcd1234"}' \
--access_token <token>
phraseapp gitlab_sync import <gitlab_sync_id> \
--account-id abcd1234

Response

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

Export from Phrase to GitLab

POST /v2/gitlab_syncs/:gitlab_sync_id/export

Export translations from Phrase to GitLab according to the .phraseapp.yml file within the GitLab repository.

Parameters

NameTypeDescription
account_id
optional
stringAccount ID to specify the actual account the GitLab Sync should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/gitlab_syncs/:gitlab_sync_id/export" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"account_id":"abcd1234"}' \
  -H 'Content-Type: application/json'
phrase gitlab_syncs export \
--gitlab_sync_id <gitlab_sync_id> \
--data '{"account_id":"abcd1234"}' \
--access_token <token>
phraseapp gitlab_sync export <gitlab_sync_id> \
--account-id abcd1234

Response

Status: 200
{ "merge_request_id": 1234, "merge_request_web_url": "https://gitlab.com/account/project/-/merge_requests/1234" }

History of single Sync Setting

GET /v2/gitlab_syncs/:gitlab_sync_id/history

List history for a single Sync Setting.

This endpoint is paginated.

Parameters

NameTypeDescription
account_id
optional
stringAccount ID to specify the actual account the GitLab Sync should be created in. Required if the requesting user is a member of multiple accounts.

Example Request

curl "https://api.phrase.com/v2/gitlab_syncs/:gitlab_sync_id/history?account_id=abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN
phrase gitlab_syncs history \
--gitlab_sync_id <gitlab_sync_id> \
--account_id abcd1234 \
--access_token <token>
phraseapp gitlab_sync history <gitlab_sync_id> \
--account-id abcd1234

Response

Status: 200
[ { "type": "history", "attributes": { "status": "success", "action": "import", "errors": [ "error message one", "error message two" ], "date": "2015-01-28T12:55:14.000+00:00", "details": { "auto_import": false } } }, { "type": "history", "attributes": { "status": "success", "action": "import", "errors": [ "error message one", "error message two" ], "date": "2015-01-28T12:55:14.000+00:00", "details": { "auto_import": false } } } ]

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
phrase webhooks list \
--project_id <project_id> \
--access_token <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
phrase webhooks show \
--project_id <project_id> \
--id <id> \
--access_token <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

NameTypeDescription
callback_url stringCallback URL to send requests to
description
optional
stringWebhook description
events stringList of event names to trigger the webhook (separated by comma)
active
optional
booleanWhether 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'
phrase webhooks create \
--project_id <project_id> \
--data '{"callback_url":""http://example.com/hooks/phraseapp-notifications"", "description":""My webhook for chat notifications"", "events":""locales:create,translations:update""}' \
--access_token <token>
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

NameTypeDescription
callback_url stringCallback URL to send requests to
description
optional
stringWebhook description
events stringList of event names to trigger the webhook (separated by comma)
active
optional
booleanWhether 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'
phrase webhooks update \
--project_id <project_id> \
--id <id> \
--data '{"callback_url":""http://example.com/hooks/phraseapp-notifications"", "description":""My webhook for chat notifications"", "events":""locales:create,translations:update""}' \
--access_token <token>
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
phrase webhooks delete \
--project_id <project_id> \
--id <id> \
--access_token <token>
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
phrase webhooks test \
--project_id <project_id> \
--id <id> \
--access_token <token>
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
phrase distributions list \
--account_id <account_id> \
--access_token <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
phrase distributions show \
--account_id <account_id> \
--id <id> \
--access_token <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

NameTypeDescription
name stringName of the distribution
project_id stringProject id the distribution should be assigned to.
platforms array of stringsList of platforms the distribution should support.
format_options
optional
hashAdditional formatting and render options. Only enclose_in_cdata is available for platform android.
fallback_to_non_regional_locale
optional
booleanIndicates whether to fallback to non regional locale when locale can not be found
Default: false
fallback_to_default_locale
optional
booleanIndicates whether to fallback to projects default locale when locale can not be found
Default: false
use_last_reviewed_version
optional
booleanUse last reviewed instead of latest translation in a project
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"],"format_options":"{xml:{enclose_in_cdata:'1'}}","fallback_to_non_regional_locale":true,"fallback_to_default_locale":true,"use_last_reviewed_version":true}' \
  -H 'Content-Type: application/json'
phrase distributions create \
--account_id <account_id> \
--data '{"name":""My Android Distribution"", "project_id":"abcd1234abcd1234abcd1234", "platforms":""android,ios"", "format_options":""{xml:{enclose_in_cdata:'1'}}"", "fallback_to_non_regional_locale":"true", "fallback_to_default_locale":"true", "use_last_reviewed_version":"true"}' \
--access_token <token>
phraseapp distribution create <account_id> \
--name "My Android Distribution" \
--project-id abcd1234abcd1234abcd1234 \
--platforms "android,ios" \
--format-options "{xml:{enclose_in_cdata:'1'}}" \
--fallback-to-non-regional-locale true \
--fallback-to-default-locale true \
--use-last-reviewed-version 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

NameTypeDescription
name stringName of the distribution
project_id stringProject id the distribution should be assigned to.
platforms array of stringsList of platforms the distribution should support.
format_options
optional
hashAdditional formatting and render options. Only enclose_in_cdata is available for platform android.
fallback_to_non_regional_locale
optional
booleanIndicates whether to fallback to non regional locale when locale can not be found
Default: false
fallback_to_default_locale
optional
booleanIndicates whether to fallback to projects default locale when locale can not be found
Default: false
use_last_reviewed_version
optional
booleanUse last reviewed instead of latest translation in a project
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"],"format_options":"{xml:{enclose_in_cdata:'1'}}","fallback_to_non_regional_locale":true,"fallback_to_default_locale":true,"use_last_reviewed_version":true}' \
  -H 'Content-Type: application/json'
phrase distributions update \
--account_id <account_id> \
--id <id> \
--data '{"name":""My Android Distribution"", "project_id":"abcd1234abcd1234abcd1234", "platforms":""android,ios"", "format_options":""{xml:{enclose_in_cdata:'1'}}"", "fallback_to_non_regional_locale":"true", "fallback_to_default_locale":"true", "use_last_reviewed_version":"true"}' \
--access_token <token>
phraseapp distribution update <account_id> <id> \
--name "My Android Distribution" \
--project-id abcd1234abcd1234abcd1234 \
--platforms "android,ios" \
--format-options "{xml:{enclose_in_cdata:'1'}}" \
--fallback-to-non-regional-locale true \
--fallback-to-default-locale true \
--use-last-reviewed-version 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
phrase distributions delete \
--account_id <account_id> \
--id <id> \
--access_token <token>
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
phrase releases list \
--account_id <account_id> \
--distribution_id <distribution_id> \
--access_token <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
phrase releases show \
--account_id <account_id> \
--distribution_id <distribution_id> \
--id <id> \
--access_token <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

NameTypeDescription
description
optional
stringDescription of the release
platforms array of stringsList of platforms the release should support.
branch
optional
stringBranch 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'
phrase releases create \
--account_id <account_id> \
--distribution_id <distribution_id> \
--data '{"description":""My first Release"", "platforms":""android,ios"", "branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
description
optional
stringDescription of the release
platforms array of stringsList of platforms the release should support.
branch
optional
stringBranch 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'
phrase releases update \
--account_id <account_id> \
--distribution_id <distribution_id> \
--id <id> \
--data '{"description":""My first Release"", "platforms":""android,ios"", "branch":"my-feature-branch"}' \
--access_token <token>
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
phrase releases delete \
--account_id <account_id> \
--distribution_id <distribution_id> \
--id <id> \
--access_token <token>
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
phrase releases publish \
--account_id <account_id> \
--distribution_id <distribution_id> \
--id <id> \
--access_token <token>
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
C001Agriculture
C002Aerospace
C003Animals/Pets/Plants
C004Arts/Culture/Literature
C005Automotive/Transportation
C006Computers/Technology/Software
C007Telecom
C008Real Estate/Construction/Building
C009Consumer Goods
C010Education
C011Entertainment
C012Ecology/Environment
C013Health/Biotechnology/Pharma
C014Internet
C015Policy/Government/Public
C016Publishing/Media/Communication
C017Religion
C018Food/Beverages
C019Retail
C020Fashion/Luxury/Textiles
C021Travel/Tourism
C022Natural Resources/Energy
C023Banking/Financial Services/Insurance
C024Legal Affairs/Tax/Law
C025Raw Materials/Industrial Goods
C026Lifestyle/Leisure/Hobbies
C027Sports
C028Home/Family/Friends/Children
C029Economy/Financial Markets
C030Science
C031Human Resources/Employment
C032Adult (Pornography, Violence, etc.)

List orders

GET /v2/projects/:project_id/orders

List all orders for the given project.

This endpoint is paginated.

Parameters

NameTypeDescription
branch
optional
stringspecify 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
phrase orders list \
--project_id <project_id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify 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
phrase orders show \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <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

NameTypeDescription
branch
optional
stringspecify the branch to use
lsp stringName of the LSP that should process this order. Can be one of gengo, textmaster.
source_locale_id idSource 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 stringsList 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 stringName 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
stringTag you want to order translations for.
message
optional
stringMessage that is displayed to the translators for description.
styleguide_id
optional
idStyle guide for translators to be sent with the order.
unverify_translations_upon_delivery
optional
booleanUnverify translations upon delivery.
Default: false
include_untranslated_keys
optional
booleanOrder translations for keys with untranslated content in the selected target locales.
Default: true
include_unverified_translations
optional
booleanOrder translations for keys with unverified content in the selected target locales.
Default: false
category stringCategory to use (required for orders processed by TextMaster).
quality
optional
booleanExtra proofreading option to ensure consistency in vocabulary and style. Only available for orders processed by TextMaster.
Default: false
priority
optional
booleanIndicates 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'
phrase orders create \
--project_id <project_id> \
--data '{"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"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase orders confirm \
--project_id <project_id> \
--id <id> \
--data '{"branch":"my-feature-branch"}' \
--access_token <token>
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

NameTypeDescription
branch
optional
stringspecify 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'
phrase orders delete \
--project_id <project_id> \
--id <id> \
--branch my-feature-branch \
--access_token <token>
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
phrase styleguides list \
--project_id <project_id> \
--access_token <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
phrase styleguides show \
--project_id <project_id> \
--id <id> \
--access_token <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

NameTypeDescription
title stringStyle guide title
audience
optional
stringAudience description
target_audience
optional
stringCan be one of: not_specified, children, teenager, young_adults, adults, old_adults.
grammatical_person
optional
stringCan 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
stringCan be one of: not_specified, popular, technical, fictional.
business
optional
stringDescription of the business
company_branding
optional
stringCompany branding to remain consistent.
formatting
optional
stringFormatting requirements and character limitations.
glossary_terms
optional
stringList of terms and/or phrases that need to be translated consistently.
grammar_consistency
optional
stringFormal or informal pronouns, consistent conjugation, grammatical gender
literal_translation
optional
stringCan be one of: Cultural/Conversational, Literal, Neutral.
overall_tone
optional
stringTone requirement descriptions
samples
optional
stringProvide 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'
phrase styleguides create \
--project_id <project_id> \
--data '{"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""}' \
--access_token <token>
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

NameTypeDescription
title stringStyle guide title
audience
optional
stringAudience description
target_audience
optional
stringCan be one of: not_specified, children, teenager, young_adults, adults, old_adults.
grammatical_person
optional
stringCan 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
stringCan be one of: not_specified, popular, technical, fictional.
business
optional
stringDescription of the business
company_branding
optional
stringCompany branding to remain consistent.
formatting
optional
stringFormatting requirements and character limitations.
glossary_terms
optional
stringList of terms and/or phrases that need to be translated consistently.
grammar_consistency
optional
stringFormal or informal pronouns, consistent conjugation, grammatical gender
literal_translation
optional
stringCan be one of: Cultural/Conversational, Literal, Neutral.
overall_tone
optional
stringTone requirement descriptions
samples
optional
stringProvide 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'
phrase styleguides update \
--project_id <project_id> \
--id <id> \
--data '{"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""}' \
--access_token <token>
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
phrase styleguides delete \
--project_id <project_id> \
--id <id> \
--access_token <token>
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
phrase authorizations list
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
phrase authorizations show \
--id <id>
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

NameTypeDescription
note stringA note to help you remember what the access is used for.
scopes
optional
array of stringsA list of scopes that the access can be used for.
expires_at
optional
datetimeExpiration 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'
phrase authorizations create \
--data '{"note":""My Deploy Script"", "scopes":""read,write"", "expires_at":""2015-03-30T09:52:53Z""}'
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

NameTypeDescription
note stringA note to help you remember what the access is used for.
scopes
optional
array of stringsA list of scopes that the access can be used for.
expires_at
optional
datetimeExpiration 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'
phrase authorizations update \
--id <id> \
--data '{"note":""My Deploy Script"", "scopes":""read,write"", "expires_at":""2015-03-30T09:52:53Z""}'
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
phrase authorizations delete \
--id <id>
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
phrase shows user \
--access_token <token>
phraseapp show user

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "username": "joe.doe", "name": "Joe Doe", "email": "joe@phrase.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
phrase accounts list \
--access_token <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
phrase accounts show \
--id <id> \
--access_token <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
phrase members list \
--account_id <account_id> \
--access_token <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
phrase members show \
--account_id <account_id> \
--id <id> \
--access_token <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

NameTypeDescription
role stringMember role, can be any of of Manager, Developer, Translator
project_ids
optional
stringList of project ids the user has access to.
locale_ids
optional
stringList of locale ids the user has access to.
permissions
optional
hashAdditional 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'
phrase members update \
--account_id <account_id> \
--id <id> \
--data '{"role":"Developer", "project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "locale_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "permissions":"{"create_upload"=>true, "review_translations"=>true}"}' \
--access_token <token>
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
phrase members delete \
--account_id <account_id> \
--id <id> \
--access_token <token>
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
phrase invitations list \
--account_id <account_id> \
--access_token <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
phrase invitations show \
--account_id <account_id> \
--id <id> \
--access_token <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

NameTypeDescription
email stringThe email of the invited user. The email can not be updated once created. Create a new invitation for each unique email.
role stringInvitiation role, can be any of Manager, Developer, Translator.
project_ids
optional
stringList of project ids the invited user has access to.
locale_ids
optional
stringList of locale ids the invited user has access to.
permissions
optional
hashAdditional 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'
phrase invitations create \
--account_id <account_id> \
--data '{"email":"example@mail.com", "role":"Developer", "project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "locale_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "permissions":"{"create_upload"=>true, "review_translations"=>true}"}' \
--access_token <token>
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

NameTypeDescription
role stringInvitiation role, can be any of Manager, Developer, Translator
project_ids
optional
stringList of project ids the invited user has access to
locale_ids
optional
stringList of locale ids the invited user has access to
permissions
optional
hashAdditional 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'
phrase invitations update \
--account_id <account_id> \
--id <id> \
--data '{"role":""Invitiation role"", "project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "locale_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235", "permissions":"{"create_upload"=>true}"}' \
--access_token <token>
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
phrase invitations delete \
--account_id <account_id> \
--id <id> \
--access_token <token>
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
phrase invitations resend \
--account_id <account_id> \
--id <id> \
--access_token <token>
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
phrase screenshots list \
--project_id <project_id> \
--access_token <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
phrase screenshots show \
--project_id <project_id> \
--id <id> \
--access_token <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

NameTypeDescription
name
optional
stringName of the screenshot
description
optional
stringDescription of the screenshot
filename fileScreenshot 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
phrase screenshots create \
--project_id <project_id> \
--data '{"name":""A screenshot name"", "description":""A screenshot description"", "filename":"/path/to/my/screenshot.png"}' \
--access_token <token>
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

NameTypeDescription
name
optional
stringName of the screenshot
description
optional
stringDescription of the screenshot
filename fileScreenshot 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
phrase screenshots update \
--project_id <project_id> \
--id <id> \
--data '{"name":""A screenshot name"", "description":""A screenshot description"", "filename":"/path/to/my/screenshot.png"}' \
--access_token <token>
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
phrase screenshots delete \
--project_id <project_id> \
--id <id> \
--access_token <token>
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
phrase screenshot_markers list \
--project_id <project_id> \
--id <id> \
--access_token <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
phrase screenshot_markers show \
--project_id <project_id> \
--screenshot_id <screenshot_id> \
--id <id> \
--access_token <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

NameTypeDescription
key_id idSpecify the Key ID which should be highlighted on the specified screenshot. The Key must belong to the project.
presentation stringPresentation 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'
phrase screenshot_markers create \
--project_id <project_id> \
--screenshot_id <screenshot_id> \
--data '{"key_id":"abcd1234abcd1234abcd1234abcd1234", "presentation":""{ "x": 100, "y": 100, "w": 100, "h": 100 }""}' \
--access_token <token>
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

NameTypeDescription
key_id idSpecify the Key ID which should be highlighted on the specified screenshot. The Key must belong to the project.
presentation stringPresentation 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'
phrase screenshot_markers update \
--project_id <project_id> \
--screenshot_id <screenshot_id> \
--data '{"key_id":"abcd1234abcd1234abcd1234abcd1234", "presentation":""{ "x": 100, "y": 100, "w": 100, "h": 100 }""}' \
--access_token <token>
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
phrase screenshot_markers delete \
--project_id <project_id> \
--screenshot_id <screenshot_id> \
--access_token <token>
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"
phrase formats list \
--access_token <token>
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 } ]