PhraseApp API Reference

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

Schema

API Endpoint

https://api.phraseapp.com/api/v2/

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

Usage

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

Use of HTTP Verbs

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

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

Identification via User-Agent

You must include the User-Agent header with the name of your application or project. It might be a good idea to include some sort of contact information as well, so that we can get in touch if necessary (e.g. to warn you about Rate-Limiting or badly formed requests). Examples of excellent User-Agent headers:

User-Agent: Frederiks Mobile App (frederik@phraseapp.com)
User-Agent: ACME Inc Python Client (http://example.com/contact)

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

Lists

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

Lists are usually paginated.

Parameters

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

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

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

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

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

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

Errors

Request Errors

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

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

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

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

Date Format

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

YYYY-MM-DDTHH:MM:SSZ

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

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

Example for CET (1 hour behind UTC):

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

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

Authentication

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

OAuth via Access Tokens

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

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

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

or send the access token via the Authorization header field:

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

For more 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.phraseapp.com/api/v2/projects?page=2"

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

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

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

Link-Headers

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

Link: ; rel="first", ; rel="prev", ; rel="next", ; rel="last"

Possible rel values are:

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

Rate Limiting

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

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

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

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

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

If you should need higher rate limits, contact us.

Conditional GET requests / HTTP Caching

We will return an ETag or Last-Modified header with most GET requests. When you request a resource we recommend to store this value and submit them on subsequent requests as If-Modified-Since and If-None-Match headers. If the resource has not changed in the meantime, we will return the status 304 Not Modified instead of rendering and returning the resource again. In most cases this is less time-consuming and makes your application/integration faster.

Please note that all conditional requests that return a response with status 304 don't count against your rate limits. We recommend to use this mechanism whenever possible.

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

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

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

JSONP

The PhraseApp API supports JSONP for all GET requests in order to deal with cross-domain request issues. Just send a ?callback parameter along with the request to specify the Javascript function name to be called with the response content:

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

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

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

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

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

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 PhraseApp API, just use HTTP Basic authentication with your email and password:

curl -u username:password "https://api.phraseapp.com/api/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.phraseapp.com/api/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.phraseapp.com/api/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.phraseapp.com/api/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.phraseapp.com/api/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 PhraseApp API v2 with these workflow-oriented examples.

Find excluded translations with a certain content

GET /api/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
  • 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.phraseapp.com/api/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20excluded:true" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp translations list <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* excluded:true'

Find unverified translations with a certain content

GET /api/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
  • 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.phraseapp.com/api/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20unverified:true" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp translations list <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp* unverified:true'

Verify translations selected by query

PATCH /api/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
  • 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.phraseapp.com/api/v2/projects/:project_id/translations/verify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"my dog unverified:true","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'
phraseapp translations verify <project_id> \
--query "my dog unverified:true" \
--sort updated_at \
--order desc

Find recently updated keys

GET /api/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 find keys by name (including wildcards).

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

Example Request

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

Find keys with a certain tag

GET /api/v2/projects/:project_id/keys

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

Parameters

NameTypeDescription
q
optional
stringSpecify a query to find keys by name (including wildcards).

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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys?q=tags:admin" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp keys list <project_id> \
--query "tags:admin"

Add tags to collection of keys

PATCH /api/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 find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • ids:key_id,... for queries on a comma-separated list of ids
  • name:key_name for text queries on key names
  • tags:tag_name to filter for keys with certain tags
  • translated:{true|false} for translation status (also requires locale_id to be specified)
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
Find more examples here.
tagsstringTag 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.phraseapp.com/api/v2/projects/:project_id/keys/tag" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'
phraseapp keys tag <project_id> \
--query 'dog* translated:true' \
--tags landing-page,release-1.2 \
--locale-id abcd1234abcd1234abcd1234abcd1234

Remove tags from collection of keys

PATCH /api/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 find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • ids:key_id,... for queries on a comma-separated list of ids
  • name:key_name for text queries on key names
  • tags:tag_name to filter for keys with certain tags
  • translated:{true|false} for translation status (also requires locale_id to be specified)
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
Find more examples here.
tagsstringTag 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.phraseapp.com/api/v2/projects/:project_id/keys/untag" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'
phraseapp keys untag <project_id> \
--query 'dog* translated:true' \
--tags landing-page,release-1.2 \
--locale-id abcd1234abcd1234abcd1234abcd1234

Find keys with broad text match

GET /api/v2/projects/:project_id/keys

Example query my dog

Parameters

NameTypeDescription
q
optional
stringSpecify a query to find keys by name (including wildcards).

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

Matches

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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys?q=my%20dog" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp keys list <project_id> \
--query "my dog"

Find keys with exact text match

GET /api/v2/projects/:project_id/keys

Example query "my dog is lazy"

Parameters

NameTypeDescription
q
optional
stringSpecify a query to find keys by name (including wildcards).

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

Matches

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

Example Request

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

Find keys with wildcard character matching

GET /api/v2/projects/:project_id/keys

Example query *dog is*

Parameters

NameTypeDescription
q
optional
stringSpecify a query to find keys by name (including wildcards).

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

Matches

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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys?q=*dog%20is*" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp keys list <project_id> \
--query '*dog is*'

Upload an Excel file with several translations

POST /api/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
filefileFile to be imported
file_formatstringFile 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[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.phraseapp.com/api/v2/projects/:project_id/uploads" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F file=/path/to/my/file.xlsx \
  -F file_format=xlsx \
  -F locale_mapping[en]=B \
  -F locale_mapping[de]=C \
  -F format_options[comment_column]=D \
  -F format_options[key_name_column]=A \
  -F format_options[first_content_row]=2
phraseapp upload create <project_id> \
--file /path/to/my/file.xlsx \
--file-format xlsx \
--locale-mapping[en] B \
--locale-mapping[de] C \
--format-options[comment-column] D \
--format-options[key-name-column] A \
--format-options[first-content-row] 2

Projects

List projects

GET /api/v2/projects

List all projects the current user has access to.

This endpoint is paginated.

Example Request

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

Response

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

Get a single project

GET /api/v2/projects/:id

Get details on a single project.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp project show <id>

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Android Project", "main_format": "xml", "project_image_url": "http://assets.phraseapp.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 /api/v2/projects

Create a new project.

Parameters

NameTypeDescription
namestringName 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.phraseapp.com/api/v2/projects" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F name=My%20Android%20Project \
  -F main_format=yml \
  -F shares_translation_memory=true \
  -F project_image=/path/to/my/project-screenshot.png \
  -F account_id=abcd1234
phraseapp project create \
--name "My Android Project" \
--main-format yml \
--shares-translation-memory true \
--project-image /path/to/my/project-screenshot.png \
--account-id abcd1234

Response

Status: 201
{ "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Android Project", "main_format": "xml", "project_image_url": "http://assets.phraseapp.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 /api/v2/projects/:id

Update an existing project.

Parameters

NameTypeDescription
namestringName 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.phraseapp.com/api/v2/projects/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -F name=My%20Android%20Project \
  -F main_format=yml \
  -F shares_translation_memory=true \
  -F project_image=/path/to/my/project-screenshot.png \
  -F account_id=abcd1234
phraseapp project update <id> \
--name "My Android Project" \
--main-format yml \
--shares-translation-memory true \
--project-image /path/to/my/project-screenshot.png \
--account-id abcd1234

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Android Project", "main_format": "xml", "project_image_url": "http://assets.phraseapp.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 /api/v2/projects/:id

Delete an existing project.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp project delete <id>

Response

Status: 204

Locales

List locales

GET /api/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.phraseapp.com/api/v2/projects/:project_id/locales?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp locales list <project_id> \
--branch my-feature-branch

Response

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

Get a single locale

GET /api/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.phraseapp.com/api/v2/projects/:project_id/locales/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp locale show <project_id> <id> \
--branch my-feature-branch

Response

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

Create a locale

POST /api/v2/projects/:project_id/locales

Create a new locale.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use
namestringLocale name
codestringLocale 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 and only available in Control Package.
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 and only available in Control Package.
Default: false
unverify_updated_translations
optional
booleanIndicates that updated translations for this locale should be marked as unverified. Part of the Advanced Workflows feature and only available in Control Package.
Default: false
autotranslate
optional
booleanIf set, translations for this locale will be fetched automatically, right after creation.
Default: false

Example Request

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

Response

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

Update a locale

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

Update an existing locale.

Parameters

NameTypeDescription
branch
optional
stringspecify the branch to use
namestringLocale name
codestringLocale 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 and only available in Control Package.
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 and only available in Control Package.
Default: false
unverify_updated_translations
optional
booleanIndicates that updated translations for this locale should be marked as unverified. Part of the Advanced Workflows feature and only available in Control Package.
Default: false
autotranslate
optional
booleanIf set, translations for this locale will be fetched automatically, right after creation.
Default: false

Example Request

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

Response

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

Delete a locale

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

Delete an existing locale.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/locales/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp locale delete <project_id> <id>

Response

Status: 204

Download a locale

GET /api/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_formatstringFile format name. See the format guide for all supported file formats.
tag
optional
stringLimit result to keys tagged with the given tag (identified by its name).
include_empty_translations
optional
booleanIndicates whether keys without translations should be included in the output as well.
Default: false
keep_notranslate_tags
optional
booleanIndicates whether [NOTRANSLATE] tags should be kept.
Default: false
convert_emoji
optional
booleanIndicates whether Emoji symbols should be converted to actual Emojis. Working with Emojis.
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
optional
booleanIndicates whether the locale file should skip all unverified translations.
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.phraseapp.com/api/v2/projects/:project_id/locales/:id/download?branch=my-feature-branch&file_format=yml&tag=feature" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp locale download <project_id> <id> \
--branch my-feature-branch \
--file-format yml \
--tag feature

Response

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

Keys

List keys

GET /api/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
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 find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • ids:key_id,... for queries on a comma-separated list of ids
  • name:key_name for text queries on key names
  • tags:tag_name to filter for keys with certain tags
  • translated:{true|false} for translation status (also requires locale_id to be specified)
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
Find more examples here.
locale_id
optional
idLocale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys?sort=updated_at&order=desc&q=mykey*%20translated:true&locale_id=abcd1234abcd1234abcd1234abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp keys list <project_id> \
--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 /api/v2/projects/:project_id/keys/:id

Get details on a single key for a given project.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp key show <project_id> <id>

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.phraseapp.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 /api/v2/projects/:project_id/keys

Create a new key.

Parameters

NameTypeDescription
namestringKey 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, number, array.
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
optional
fileScreenshot/image for the key.
remove_screenshot
optional
booleanIndicates whether the screenshot will be deleted.
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.phraseapp.com/api/v2/projects/:project_id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F name=home.index.headline \
  -F description=Some%20description%20worth%20knowing... \
  -F name_plural=home.index.headlines \
  -F data_type=number \
  -F tags=awesome-feature,needs-proofreading \
  -F max_characters_allowed=140 \
  -F screenshot=/path/to/my/screenshot.png
phraseapp key create <project_id> \
--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.phraseapp.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 /api/v2/projects/:project_id/keys/:id

Update an existing key.

Parameters

NameTypeDescription
namestringKey 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, number, array.
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
optional
fileScreenshot/image for the key.
remove_screenshot
optional
booleanIndicates whether the screenshot will be deleted.
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.phraseapp.com/api/v2/projects/:project_id/keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -F name=home.index.headline \
  -F description=Some%20description%20worth%20knowing... \
  -F name_plural=home.index.headlines \
  -F data_type=number \
  -F tags=awesome-feature,needs-proofreading \
  -F max_characters_allowed=140 \
  -F screenshot=/path/to/my/screenshot.png
phraseapp key update <project_id> <id> \
--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.phraseapp.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 /api/v2/projects/:project_id/keys/:id

Delete an existing key.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp key delete <project_id> <id>

Response

Status: 204

Delete collection of keys

DELETE /api/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
q
optional
stringSpecify a query to find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • ids:key_id,... for queries on a comma-separated list of ids
  • name:key_name for text queries on key names
  • tags:tag_name to filter for keys with certain tags
  • translated:{true|false} for translation status (also requires locale_id to be specified)
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
Find more examples here.
locale_id
optional
idLocale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"q":"mykey* translated:true","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
  -H 'Content-Type: application/json'
phraseapp keys delete <project_id> \
--query 'mykey* translated:true' \
--locale-id abcd1234abcd1234abcd1234abcd1234

Response

Status: 200
{ "records_affected": 2 }

Add tags to collection of keys

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

Tags all keys matching query. Same constraints as list.

Parameters

NameTypeDescription
q
optional
stringSpecify a query to find keys by name (including wildcards).

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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/tag" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"mykey* translated:true","locale_id":"abcd1234abcd1234abcd1234abcd1234","tags":"landing-page,release-1.2"}' \
  -H 'Content-Type: application/json'
phraseapp keys tag <project_id> \
--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 /api/v2/projects/:project_id/keys/untag

Removes specified tags from keys matching query.

Parameters

NameTypeDescription
q
optional
stringSpecify a query to find keys by name (including wildcards).

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

Example Request

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

Response

Status: 200
{ "records_affected": 2 }

Translations

List all translations

GET /api/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
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.phraseapp.com/api/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%2520unverified:true%2520excluded:true%2520tags:feature,center" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp translations list <project_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center'

Response

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

List translations by locale

GET /api/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
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.phraseapp.com/api/v2/projects/:project_id/locales/:locale_id/translations?sort=updated_at&order=desc&q=PhraseApp*%2520unverified:true%2520excluded:true%2520tags:feature,center" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp translations by_locale <project_id> <locale_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center'

Response

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

List translations by key

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

List translations for a specific key.

This endpoint is paginated.

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
  • 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.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/translations?sort=updated_at&order=desc&q=PhraseApp*%2520unverified:true%2520excluded:true%2520tags:feature,center" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp translations by_key <project_id> <key_id> \
--sort updated_at \
--order desc \
--query 'PhraseApp*%20unverified:true%20excluded:true%20tags:feature,center'

Response

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

Get a single translation

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

Get details on a single translation.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/translations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp translation show <project_id> <id>

Response

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

Create a translation

POST /api/v2/projects/:project_id/translations

Create a translation.

Parameters

NameTypeDescription
locale_ididLocale. Can be the name or public id of the locale. Preferred is the public id.
key_ididKey
contentstringTranslation 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 and only available in Control Package.
Default: false
excluded
optional
booleanIndicates whether translation is excluded.
Default: false

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/translations" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"locale_id":"abcd1234cdef1234abcd1234cdef1234","key_id":"abcd1234cdef1234abcd1234cdef1234","content":"My translation"}' \
  -H 'Content-Type: application/json'
phraseapp translation create <project_id> \
--locale-id abcd1234cdef1234abcd1234cdef1234 \
--key-id abcd1234cdef1234abcd1234cdef1234 \
--content "My translation"

Response

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

Update a translation

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

Update an existing translation.

Parameters

NameTypeDescription
contentstringTranslation 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 and only available in Control Package.
Default: false
excluded
optional
booleanIndicates whether translation is excluded.
Default: false

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/translations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"content":"My translation"}' \
  -H 'Content-Type: application/json'
phraseapp translation update <project_id> <id> \
--content "My translation"

Response

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

Verify translations selected by query

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

Only available in the Control Package.
Verify translations matching query.

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
  • 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.phraseapp.com/api/v2/projects/:project_id/translations/verify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"PhraseApp*%20unverified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'
phraseapp translations verify <project_id> \
--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 /api/v2/projects/:project_id/translations/unverify

Only available in the Control Package.
Mark translations matching query as unverified.

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
  • 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.phraseapp.com/api/v2/projects/:project_id/translations/unverify" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"PhraseApp*%20verified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'
phraseapp translations unverify <project_id> \
--query 'PhraseApp*%20verified:true%20tags:feature,center' \
--sort updated_at \
--order desc

Response

Status: 200
{ "records_affected": 96 }

Set exclude from export flag on translations selected by query

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

Exclude translations matching query from locale export.

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
  • 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.phraseapp.com/api/v2/projects/:project_id/translations/exclude" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"PhraseApp*%20verified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'
phraseapp translations exclude <project_id> \
--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 /api/v2/projects/:project_id/translations/include

Include translations matching query in locale export.

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
  • 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.phraseapp.com/api/v2/projects/:project_id/translations/include" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"q":"PhraseApp*%20verified:true%20tags:feature,center","sort":"updated_at","order":"desc"}' \
  -H 'Content-Type: application/json'
phraseapp translations include <project_id> \
--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 /api/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
filefileFile 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
optional
booleanIndicates whether the file contains Emoji symbols that should be converted. Working with Emojis.
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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/uploads" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F branch=my-feature-branch \
  -F file=/path/to/my/file.json \
  -F file_format=json \
  -F locale_id=abcd1234cdef1234abcd1234cdef1234 \
  -F tags=awesome-feature,needs-proofreading \
  -F locale_mapping=%7B%22en%22:%20%222%22%7D \
  -F format_options=%7B%22foo%22:%20%22bar%22%7D
phraseapp upload create <project_id> \
--branch my-feature-branch \
--file /path/to/my/file.json \
--file-format json \
--locale-id abcd1234cdef1234abcd1234cdef1234 \
--tags awesome-feature,needs-proofreading \
--locale-mapping "{"en": "2"}" \
--format-options "{"foo": "bar"}"

Response

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

View upload details

GET /api/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.phraseapp.com/api/v2/projects/:project_id/uploads/:id?branch=my-feature-branch" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp upload show <project_id> <id> \
--branch my-feature-branch

Response

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

List uploads

GET /api/v2/projects/:project_id/uploads

List all uploads for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/uploads" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp uploads list <project_id>

Response

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

Tags

List tags

GET /api/v2/projects/:project_id/tags

List all tags for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/tags" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp tags list <project_id>

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 /api/v2/projects/:project_id/tags/:name

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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/tags/:name" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp tag show <project_id> <name>

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 /api/v2/projects/:project_id/tags

Create a new tag.

Parameters

NameTypeDescription
namestringName of the tag

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/tags" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"name":"my-feature"}' \
  -H 'Content-Type: application/json'
phraseapp tag create <project_id> \
--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 /api/v2/projects/:project_id/tags/:name

Delete an existing tag.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/tags/:name" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp tag delete <project_id> <name>

Response

Status: 204

Blacklisted Keys

List blacklisted keys

GET /api/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.phraseapp.com/api/v2/projects/:project_id/blacklisted_keys" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp blacklisted_keys list <project_id>

Response

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

Get a single blacklisted key

GET /api/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.phraseapp.com/api/v2/projects/:project_id/blacklisted_keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp blacklisted_key show <project_id> <id>

Response

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

Create a blacklisted key

POST /api/v2/projects/:project_id/blacklisted_keys

Create a new rule for blacklisting keys.

Parameters

NameTypeDescription
namestringBlacklisted key name

Example Request

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

Response

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

Update a blacklisted key

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

Update an existing rule for blacklisting keys.

Parameters

NameTypeDescription
namestringBlacklisted key name

Example Request

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

Response

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

Delete a blacklisted key

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

Delete an existing rule for blacklisting keys.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/blacklisted_keys/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp blacklisted_key delete <project_id> <id>

Response

Status: 204

Versions / History

List all versions

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

List all versions for the given translation.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/translations/:translation_id/versions" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp versions list <project_id> <translation_id>

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 /api/v2/projects/:project_id/translations/:translation_id/versions/:id

Get details on a single version.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/translations/:translation_id/versions/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp version show <project_id> <translation_id> <id>

Response

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

Jobs

List jobs

GET /api/v2/projects/:project_id/jobs

List all jobs for the given project.

This endpoint is paginated.

Parameters

NameTypeDescription
owned_bystringfilter by user owning job
assigned_tostringfilter by user assigned to job
statestringfilter by state of job Valid states are draft, in_progress, completed

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs?owned_by=abcd1234cdef1234abcd1234cdef1234&assigned_to=abcd1234cdef1234abcd1234cdef1234&state=completed" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp jobs list <project_id> \
--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 /api/v2/projects/:project_id/jobs/:id

Get details on a single job for a given project.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp job show <project_id> <id>

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 /api/v2/projects/:project_id/jobs

Create a new job.

Parameters

NameTypeDescription
namestringJob name
briefing
optional
stringBriefing for the translators
due_date
optional
datetimeDate the job should be finished
tagsarray of stringstags of keys that should be included within the job
translation_key_idsarray of stringsids of keys that should be included within the job

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"name":"de","briefing":"de-DE","due_date":"2017-08-15","tags":["myUploadTag"],"translation_key_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'
phraseapp job create <project_id> \
--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 /api/v2/projects/:project_id/jobs/:id

Update an existing job.

Parameters

NameTypeDescription
namestringJob name
briefing
optional
stringBriefing for the translators
due_date
optional
datetimeDate the job should be finished

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"name":"de","briefing":"de-DE","due_date":"2017-08-15"}' \
  -H 'Content-Type: application/json'
phraseapp job update <project_id> <id> \
--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 /api/v2/projects/:project_id/jobs/:id

Delete an existing job.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp job delete <project_id> <id>

Response

Status: 204

Start a job

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

Starts an existing job in state draft.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id/start" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST
phraseapp job start <project_id> <id>

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 /api/v2/projects/:project_id/jobs/:id/complete

Mark a job as completed.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id/complete" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST
phraseapp job complete <project_id> <id>

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 /api/v2/projects/:project_id/jobs/:id/reopen

Mark a job as uncompleted.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id/reopen" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST
phraseapp job reopen <project_id> <id>

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 /api/v2/projects/:project_id/jobs/:id/keys

Add multiple keys to a existing job.

Parameters

NameTypeDescription
translation_key_idsarray of stringsids of keys that should added to the job

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"translation_key_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'
phraseapp job keys create <project_id> <id> \
--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 /api/v2/projects/:project_id/jobs/:id/keys

Remove multiple keys from existing job.

Parameters

NameTypeDescription
translation_key_idsarray of stringsids of keys that should added to the job

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:id/keys" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE \
  -d '{"translation_key_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'
phraseapp job keys delete <project_id> <id> \
--translation-key-ids "abcd1234cdef1234abcd1234cdef1234"

Response

Status: 204

Job Locales

List job locales

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

List all job locales for a given job.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:job_id/locales" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp job_locales list <project_id> <job_id>

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 /api/v2/projects/:project_id/jobs/:job_id/locale/:id

Get a single job locale for a given job.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:job_id/locale/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp job_locale show <project_id> <job_id> <id>

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 /api/v2/projects/:project_id/jobs/:job_id/locales

Create a new job locale.

Parameters

NameTypeDescription
locale_idstringlocale id
user_ids
optional
array of stringsArray of user ids to be assigned to the job locale

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:job_id/locales" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"locale_id":"abcd1234cdef1234abcd1234cdef1234","user_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'
phraseapp job_locales create <project_id> <job_id> \
--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 /api/v2/projects/:project_id/jobs/:job_id/locales/:id

Update an existing job locale.

Parameters

NameTypeDescription
locale_idstringlocale id
user_ids
optional
array of stringsArray of user ids to be assigned to the job locale

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:job_id/locales/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"locale_id":"abcd1234cdef1234abcd1234cdef1234","user_ids":["abcd1234cdef1234abcd1234cdef1234"]}' \
  -H 'Content-Type: application/json'
phraseapp job_locale update <project_id> <job_id> <id> \
--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 /api/v2/projects/:project_id/jobs/:job_id/locales/:id

Delete an existing job locale.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:job_id/locales/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp job_locale delete <project_id> <job_id> <id>

Response

Status: 204

Complete a job locale

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

Mark a job locale as completed.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:job_id/locales/:id/complete" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST
phraseapp job_locale complete <project_id> <job_id> <id>

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 /api/v2/projects/:project_id/jobs/:job_id/locales/:id/reopen

Mark a job locale as uncompleted.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/jobs/:job_id/locales/:id/reopen" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST
phraseapp job_locale reopen <project_id> <job_id> <id>

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 /api/v2/projects/:project_id/keys/:key_id/comments

List all comments for a key.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp comments list <project_id> <key_id>

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 /api/v2/projects/:project_id/keys/:key_id/comments/:id

Get details on a single comment.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp comment show <project_id> <key_id> <id>

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 /api/v2/projects/:project_id/keys/:key_id/comments

Create a new comment for a key.

Parameters

NameTypeDescription
messagestringComment message

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"message":"Some message..."}' \
  -H 'Content-Type: application/json'
phraseapp comment create <project_id> <key_id> \
--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 /api/v2/projects/:project_id/keys/:key_id/comments/:id

Update an existing comment.

Parameters

NameTypeDescription
messagestringComment message

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"message":"Some message..."}' \
  -H 'Content-Type: application/json'
phraseapp comment update <project_id> <key_id> <id> \
--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 /api/v2/projects/:project_id/keys/:key_id/comments/:id

Delete an existing comment.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp comment delete <project_id> <key_id> <id>

Response

Status: 204

Mark a comment as read

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

Mark a comment as read.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments/:id/read" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH
phraseapp comment mark read <project_id> <key_id> <id>

Response

Status: 204

Mark a comment as unread

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

Mark a comment as unread.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments/:id/read" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp comment mark unread <project_id> <key_id> <id>

Response

Status: 204

Check if comment is read

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

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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/keys/:key_id/comments/:id/read" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp comment mark check <project_id> <key_id> <id>

Response

Status: 204

Branches

Branches are currently in private beta. Contact us to try it out. This API endpoint may change in the future.

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 /api/v2/projects/:project_id/branches

List all branches the of the current project.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/branches" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp branches list <project_id>

Response

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

Get a single branch

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

Get details on a single branch for a given project.

Example Request

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

Response

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

Create a branch

POST /api/v2/projects/:project_id/branches

Create a new branch.

Parameters

NameTypeDescription
namestringName of the branch

Example Request

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

Response

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

Update a branch

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

Update an existing branch.

Parameters

NameTypeDescription
namestringName of the branch

Example Request

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

Response

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

Delete a branch

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

Delete an existing branch.

Example Request

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

Response

Status: 204

Merge a branch

PATCH /api/v2/projects/:project_id/branches/:id/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.phraseapp.com/api/v2/projects/:project_id/branches/:id/merge" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"strategy":"use_master"}' \
  -H 'Content-Type: application/json'
phraseapp branch merge <project_id> <id> \
--strategy use_master

Response

Status: 200

Glossary

Note: Glossary API is still in beta and might be subject to change. Glossaries are available in the Quality Package.

List glossaries

GET /api/v2/accounts/:account_id/glossaries

List all glossaries the current user has access to.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/glossaries" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp glossaries list <account_id>

Response

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

Get a single glossary

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

Get details on a single glossary.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/glossaries/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp glossary show <account_id> <id>

Response

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

Create a glossary

POST /api/v2/accounts/:account_id/glossaries

Create a new glossary.

Parameters

NameTypeDescription
namestringName of the glossary
project_ids
optional
stringList of project ids the glossary should be assigned to.

Example Request

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

Response

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

Update a glossary

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

Update an existing glossary.

Parameters

NameTypeDescription
namestringName of the glossary
project_ids
optional
stringList of project ids the glossary should be assigned to.

Example Request

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

Response

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

Delete a glossary

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

Delete an existing glossary.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/glossaries/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp glossary delete <account_id> <id>

Response

Status: 204

Glossary Terms

Note: Glossary API is still in beta and might be subject to change. Glossaries are available in the Quality Package.

List glossary terms

GET /api/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.phraseapp.com/api/v2/accounts/:account_id/glossaries/:glossary_id/terms" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp glossary_terms list <account_id> <glossary_id>

Response

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

Get a single glossary term

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

Get details on a single glossary term.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/glossaries/:glossary_id/terms/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp glossary_term show <account_id> <glossary_id> <id>

Response

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

Create a glossary term

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

Create a new glossary term.

Parameters

NameTypeDescription
termstringGlossary 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.phraseapp.com/api/v2/accounts/:account_id/glossaries/:glossary_id/terms" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"term":"MyCompany","description":"Use this when refering to our company","translatable":true,"case_sensitive":true}' \
  -H 'Content-Type: application/json'
phraseapp glossary_term create <account_id> <glossary_id> \
--term MyCompany \
--description "Use this when refering to our company" \
--translatable true \
--case-sensitive true

Response

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

Update a glossary term

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

Update an existing glossary term.

Parameters

NameTypeDescription
termstringGlossary 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.phraseapp.com/api/v2/accounts/:account_id/glossaries/:glossary_id/terms/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"term":"MyCompany","description":"Use this when refering to our company","translatable":true,"case_sensitive":true}' \
  -H 'Content-Type: application/json'
phraseapp glossary_term update <account_id> <glossary_id> <id> \
--term MyCompany \
--description "Use this when refering to our company" \
--translatable true \
--case-sensitive true

Response

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

Delete a glossary term

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

Delete an existing glossary term.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/glossaries/:glossary_id/terms/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp glossary_term delete <account_id> <glossary_id> <id>

Response

Status: 204

Glossary Term Translations

Note: Glossary API is still in beta and might be subject to change. Glossaries are available in the Quality Package.

Create a glossary term translation

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

Create a new glossary term translation.

Parameters

NameTypeDescription
locale_codestringIdentifies the language for this translation
content
optional
stringThe content of the translation

Example Request

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

Response

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

Update a glossary term translation

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

Update an existing glossary term translation.

Parameters

NameTypeDescription
locale_codestringIdentifies the language for this translation
content
optional
stringThe content of the translation

Example Request

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

Response

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

Delete a glossary term translation

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

Delete an existing glossary term translation.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/glossaries/:glossary_id/terms/:term_id/translations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp glossary_term_translation delete <account_id> <glossary_id> <term_id> <id>

Response

Status: 204

Bitbucket Sync

List Bitbucket syncs

GET /api/v2/bitbucket_syncs

List all Bitbucket repositories for which synchronisation with PhraseApp 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.phraseapp.com/api/v2/bitbucket_syncs?account_id=abcd1234" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp bitbucket_syncs list \
--account-id abcd1234

Response

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

Export from PhraseApp to Bitbucket

POST /api/v2/bitbucket_syncs/:id/export

Export translations from PhraseApp 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.phraseapp.com/api/v2/bitbucket_syncs/:id/export" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"account_id":"abcd1234"}' \
  -H 'Content-Type: application/json'
phraseapp bitbucket_sync export <id> \
--account-id abcd1234

Response

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

Import to PhraseApp from Bitbucket

POST /api/v2/bitbucket_syncs/:id/import

Import translations from Bitbucket to PhraseApp 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.phraseapp.com/api/v2/bitbucket_syncs/:id/import" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"account_id":"abcd1234"}' \
  -H 'Content-Type: application/json'
phraseapp bitbucket_sync import <id> \
--account-id abcd1234

Response

Status: 200

Webhooks

This resource is not available in PhraseApp On-Premise

List webhooks

GET /api/v2/projects/:project_id/webhooks

List all webhooks for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/webhooks" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp webhooks list <project_id>

Response

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

Get a single webhook

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

Get details on a single webhook.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/webhooks/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp webhook show <project_id> <id>

Response

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

Create a webhook

POST /api/v2/projects/:project_id/webhooks

Create a new webhook.

Parameters

NameTypeDescription
callback_urlstringCallback URL to send requests to
description
optional
stringWebhook description
eventsstringList 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.phraseapp.com/api/v2/projects/:project_id/webhooks" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"callback_url":"http://example.com/hooks/phraseapp-notifications","description":"My webhook for chat notifications","events":"locales:create,translations:update"}' \
  -H 'Content-Type: application/json'
phraseapp webhook create <project_id> \
--callback-url "http://example.com/hooks/phraseapp-notifications" \
--description "My webhook for chat notifications" \
--events "locales:create,translations:update"

Response

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

Update a webhook

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

Update an existing webhook.

Parameters

NameTypeDescription
callback_urlstringCallback URL to send requests to
description
optional
stringWebhook description
eventsstringList 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.phraseapp.com/api/v2/projects/:project_id/webhooks/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"callback_url":"http://example.com/hooks/phraseapp-notifications","description":"My webhook for chat notifications","events":"locales:create,translations:update"}' \
  -H 'Content-Type: application/json'
phraseapp webhook update <project_id> <id> \
--callback-url "http://example.com/hooks/phraseapp-notifications" \
--description "My webhook for chat notifications" \
--events "locales:create,translations:update"

Response

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

Delete a webhook

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

Delete an existing webhook.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/webhooks/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp webhook delete <project_id> <id>

Response

Status: 204

Test a webhook

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

Perform a test request for a webhook.

Example Request

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

Response

Status: 200

Orders

This resource is not available in PhraseApp 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 /api/v2/projects/:project_id/orders

List all orders for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/orders" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp orders list <project_id>

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 /api/v2/projects/:project_id/orders/:id

Get details on a single order.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/orders/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp order show <project_id> <id>

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 /api/v2/projects/:project_id/orders

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

Parameters

NameTypeDescription
lspstringName of the LSP that should process this order. Can be one of gengo, textmaster.
source_locale_ididSource locale for the order. Can be the name or public id of the source locale. Preferred is the public id.
target_locale_idsarray 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_typestringName 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
categorystringCategory 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.phraseapp.com/api/v2/projects/:project_id/orders" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"lsp":"textmaster","source_locale_id":"abcd1234abcd1234abcd1234abcd1234","target_locale_ids":["1234abcd1234abcd1234abcd1234abcd","abcd1234abcd1234abcd1234abcd1234"],"translation_type":"premium","tag":"my-awesome-feature","message":"Please make everything sound really nice :)","styleguide_id":"1234abcd1234abcd1234abcd1234abcd","category":"C021"}' \
  -H 'Content-Type: application/json'
phraseapp order create <project_id> \
--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 /api/v2/projects/:project_id/orders/:id/confirm

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

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/orders/:id/confirm" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH
phraseapp order confirm <project_id> <id>

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 /api/v2/projects/:project_id/orders/:id

Cancel an existing order. Must not yet be confirmed.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/orders/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp order delete <project_id> <id>

Response

Status: 204

Style guides

This resource is not available in PhraseApp On-Premise

List style guides

GET /api/v2/projects/:project_id/styleguides

List all styleguides for the given project.

This endpoint is paginated.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/styleguides" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp styleguides list <project_id>

Response

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

Get a single style guide

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

Get details on a single style guide.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/styleguides/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp styleguide show <project_id> <id>

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "title": "My Style Guide", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z", "public_url": "https://phraseapp.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 /api/v2/projects/:project_id/styleguides

Create a new style guide.

Parameters

NameTypeDescription
titlestringStyle 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.phraseapp.com/api/v2/projects/:project_id/styleguides" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -d '{"title":"Web application style guide","audience":"customer-facing","target_audience":"teenager","grammatical_person":"first_person_singular","vocabulary_type":"technical","business":"We are a travel site that helps customers find the best hotels and flights.","company_branding":"ACME Inc. should never be translated.","formatting":"Never use capital letters","glossary_terms":"Appartement, cabin, loft","grammar_consistency":"","literal_translation":"Neutral","overall_tone":"Tone should be fun and light","samples":"http://www.myexample.com/my/document/path/to/samples.pdf"}' \
  -H 'Content-Type: application/json'
phraseapp styleguide create <project_id> \
--title "Web application style guide" \
--audience customer-facing \
--target-audience teenager \
--grammatical-person first_person_singular \
--vocabulary-type technical \
--business "We are a travel site that helps customers find the best hotels and flights." \
--company-branding "ACME Inc. should never be translated." \
--formatting "Never use capital letters" \
--glossary-terms "Appartement, cabin, loft" \
--grammar-consistency  \
--literal-translation Neutral \
--overall-tone "Tone should be fun and light" \
--samples "http://www.myexample.com/my/document/path/to/samples.pdf"

Response

Status: 201
{ "id": "abcd1234cdef1234abcd1234cdef1234", "title": "My Style Guide", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z", "public_url": "https://phraseapp.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 /api/v2/projects/:project_id/styleguides/:id

Update an existing style guide.

Parameters

NameTypeDescription
titlestringStyle 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.phraseapp.com/api/v2/projects/:project_id/styleguides/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"title":"Web application style guide","audience":"customer-facing","target_audience":"teenager","grammatical_person":"first_person_singular","vocabulary_type":"technical","business":"We are a travel site that helps customers find the best hotels and flights.","company_branding":"ACME Inc. should never be translated.","formatting":"Never use capital letters","glossary_terms":"Appartement, cabin, loft","grammar_consistency":"","literal_translation":"Neutral","overall_tone":"Tone should be fun and light","samples":"http://www.myexample.com/my/document/path/to/samples.pdf"}' \
  -H 'Content-Type: application/json'
phraseapp styleguide update <project_id> <id> \
--title "Web application style guide" \
--audience customer-facing \
--target-audience teenager \
--grammatical-person first_person_singular \
--vocabulary-type technical \
--business "We are a travel site that helps customers find the best hotels and flights." \
--company-branding "ACME Inc. should never be translated." \
--formatting "Never use capital letters" \
--glossary-terms "Appartement, cabin, loft" \
--grammar-consistency  \
--literal-translation Neutral \
--overall-tone "Tone should be fun and light" \
--samples "http://www.myexample.com/my/document/path/to/samples.pdf"

Response

Status: 200
{ "id": "abcd1234cdef1234abcd1234cdef1234", "title": "My Style Guide", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z", "public_url": "https://phraseapp.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 /api/v2/projects/:project_id/styleguides/:id

Delete an existing style guide.

Example Request

curl "https://api.phraseapp.com/api/v2/projects/:project_id/styleguides/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp styleguide delete <project_id> <id>

Response

Status: 204

Authorizations

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

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

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

Scopes

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

Available Scopes

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

List authorizations

GET /api/v2/authorizations

List all your authorizations.

This endpoint is paginated.

Example Request

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

Response

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

Get a single authorization

GET /api/v2/authorizations/:id

Get details on a single authorization.

Example Request

curl "https://api.phraseapp.com/api/v2/authorizations/:id" \
  -u USERNAME
phraseapp authorization show <id>

Response

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

Create an authorization

POST /api/v2/authorizations

Create a new authorization.

Parameters

NameTypeDescription
notestringA 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.phraseapp.com/api/v2/authorizations" \
  -u USERNAME \
  -X POST \
  -d '{"note":"My Deploy Script","scopes":["read","write"],"expires_at":"2015-03-30T09:52:53Z"}' \
  -H 'Content-Type: application/json'
phraseapp authorization create \
--note "My Deploy Script" \
--scopes "read,write" \
--expires-at "2015-03-30T09:52:53Z"

Response

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

Update an authorization

PATCH /api/v2/authorizations/:id

Update an existing authorization.

Parameters

NameTypeDescription
notestringA 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.phraseapp.com/api/v2/authorizations/:id" \
  -u USERNAME \
  -X PATCH \
  -d '{"note":"My Deploy Script","scopes":["read","write"],"expires_at":"2015-03-30T09:52:53Z"}' \
  -H 'Content-Type: application/json'
phraseapp authorization update <id> \
--note "My Deploy Script" \
--scopes "read,write" \
--expires-at "2015-03-30T09:52:53Z"

Response

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

Delete an authorization

DELETE /api/v2/authorizations/:id

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

Example Request

curl "https://api.phraseapp.com/api/v2/authorizations/:id" \
  -u USERNAME \
  -X DELETE
phraseapp authorization delete <id>

Response

Status: 204

Users

Show current User

GET /api/v2/user

Show details for current User.

Example Request

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

Response

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

Accounts

List accounts

GET /api/v2/accounts

List all accounts the current user has access to.

This endpoint is paginated.

Example Request

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

Response

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

Get a single account

GET /api/v2/accounts/:id

Get details on a single account.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp account show <id>

Response

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

Members

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

List members

GET /api/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.phraseapp.com/api/v2/accounts/:account_id/members" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp members list <account_id>

Response

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

Get single member

GET /api/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.phraseapp.com/api/v2/accounts/:account_id/members/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp member show <account_id> <id>

Response

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

Update a member

PATCH /api/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
rolestringMember 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.

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/members/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X PATCH \
  -d '{"role":"Developer","project_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235","locale_ids":"abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235"}' \
  -H 'Content-Type: application/json'
phraseapp member update <account_id> <id> \
--role Developer \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--locale-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235

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" } ] } ] }

Remove a user from the account

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

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

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/members/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp member delete <account_id> <id>

Response

Status: 204

Invitations

With the invitation endpoint you can manage and invite users to PhraseApp 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 /api/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.phraseapp.com/api/v2/accounts/:account_id/invitations" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp invitations list <account_id>

Response

Status: 200
[ { "id": "acbdacbdacbdacbdacbdacbd", "email": "foo@bar.com", "role": "Manager", "state": "accepted", "projects": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Android Project", "main_format": "xml", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ], "locales": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "English", "code": "en-GB" } ], "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" } ], "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 /api/v2/accounts/:account_id/invitations/:id

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

Example Request

curl "https://api.phraseapp.com/api/v2/accounts/:account_id/invitations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN
phraseapp invitation show <account_id> <id>

Response

Status: 200
{ "id": "acbdacbdacbdacbdacbdacbd", "email": "foo@bar.com", "role": "Manager", "state": "accepted", "projects": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "My Android Project", "main_format": "xml", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ], "locales": [ { "id": "abcd1234cdef1234abcd1234cdef1234", "name": "English", "code": "en-GB" } ], "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 /api/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
emailstringThe email of the invited user. The email can not be updated once created. Create a new invitation for each unique email.
rolestringInvitiation 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.

Example Request

curl "https://api.phraseapp.com/api/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"}' \
  -H 'Content-Type: application/json'
phraseapp invitation create <account_id> \
--email example@mail.com \
--role Developer \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--locale-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235

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" } ], "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 /api/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
rolestringInvitiation 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

Example Request

curl "https://api.phraseapp.com/api/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"}' \
  -H 'Content-Type: application/json'
phraseapp invitation update <account_id> <id> \
--role "Invitiation role" \
--project-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235 \
--locale-ids abcd1234abcd1234abcd1234,abcd1234abcd1234abcd1235

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" } ], "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 /api/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.phraseapp.com/api/v2/accounts/:account_id/invitations/:id" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X DELETE
phraseapp invitation delete <account_id> <id>

Response

Status: 204

Resend an invitation

POST /api/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.phraseapp.com/api/v2/accounts/:account_id/invitations/:id/resend" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST
phraseapp invitation resend <account_id> <id>

Response

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

Formats

List formats

GET /api/v2/formats

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

This endpoint does not require authentication

Example Request

curl "https://api.phraseapp.com/api/v2/formats"
phraseapp formats list

Response

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