Keys

GET /v2/projects/:project_id/keys

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

This endpoint is paginated.

Parameters

Name Type Description
sort
optional
string Sort by field. Can be one of: name, created_at, updated_at.
Default: name
order
optional
string Order direction. Can be one of: asc, desc.
Default: asc
q
optional
string Specify a query to find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • 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:{>=| for date range queries
Find more examples here.
locale_id
optional
id Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.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": [ "feature-xyz", "latest-upload" ], "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": [ "feature-xyz", "latest-upload" ], "data_type": "string", "created_at": "2015-01-28T09:52:53Z", "updated_at": "2015-01-28T09:52:53Z" } ]

GET /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": [ "feature-xyz", "latest-upload" ], "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": "" }

POST /v2/projects/:project_id/keys

Create a new key.

Parameters

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

Example Request

curl "https://api.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": [ "feature-xyz", "latest-upload" ], "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": "" }

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

Update an existing key.

Parameters

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

Example Request

curl "https://api.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": [ "feature-xyz", "latest-upload" ], "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": "" }

DELETE /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 /v2/projects/:project_id/keys

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

Parameters

Name Type Description
q
optional
string Specify a query to find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • 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:{>=| for date range queries
Find more examples here.
locale_id
optional
id Locale used to determine the translation state of a key when filtering for untranslated or translated keys.

Example Request

curl "https://api.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 }

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

Tags all keys matching query. Same constraints as list.

Parameters

Name Type Description
q
optional
string Specify a query to find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • 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:{>=| for date range queries
Find more examples here.
locale_id
optional
id Locale used to determine the translation state of a key when filtering for untranslated or translated keys.
tags string Tag or comma-separated list of tags to add to the matching collection of keys

Example Request

curl "https://api.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 }

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

Removes specified tags from keys matching query.

Parameters

Name Type Description
q
optional
string Specify a query to find keys by name (including wildcards).

The following qualifiers are also supported in the search term:
  • 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:{>=| for date range queries
Find more examples here.
locale_id
optional
id Locale used to determine the translation state of a key when filtering for untranslated or translated keys.
tags string Tag or comma-separated list of tags to add to the matching collection of keys

Example Request

curl "https://api.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 }