> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage examples
Learn how to work more efficiently with Phrase Strings API v2 with these workflow-oriented examples.
## Find excluded translations with a certain content
```
GET /v2/projects/:project_id/translations
```
List excluded translations for the given project which start with the term `PhraseApp`.
### Parameters
| Name | Type | Description |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sort` *(optional)* | `string` | Sort criteria. Can be one of: `key_name`, `created_at`, `updated_at`.
**Default:** `key_name` |
| `order` *(optional)* | `string` | Order direction. Can be one of: `asc`, `desc`.
**Default:** `asc` |
| `q` *(optional)* | `string` | Specify a query to find translations by content (including wildcards).
**Note:** Search is limited to 10,000 results and may not include recently updated data (depending on the project size).
Supported qualifiers:
- `id:translation_id,...` – comma-separated list of IDs
- `tags:XYZ` – tag on the translation
- `unverified:{true\|false}` – verification status
- `reviewed:{true\|false}` – reviewed status
- `excluded:{true\|false}` – exclusion status
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries
|
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20excluded:true" \
-u USERNAME_OR_ACCESS_TOKEN
```
```
phrase translations list \
--project_id \
--sort updated_at \
--order desc \
--query 'PhraseApp* excluded:true' \
--access_token
```
## Find unverified translations with a certain content
```
GET /v2/projects/:project_id/translations
```
List unverified translations for the given project which start with the term `PhraseApp` and are not verified.
### Parameters
| Name | Type | Description |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sort` *(optional)* | `string` | Sort criteria. Can be one of: `key_name`, `created_at`, `updated_at`.
**Default:** `key_name` |
| `order` *(optional)* | `string` | Order direction. Can be one of: `asc`, `desc`.
**Default:** `asc` |
| `q` *(optional)* | `string` | Specify a query to find translations by content (including wildcards).
**Note:** Search is limited to 10,000 results and may not include recently updated data (depending on the project size).
Supported qualifiers:
- `id:translation_id,...` – comma-separated list of IDs
- `tags:XYZ` – tag on the translation
- `unverified:{true\|false}` – verification status
- `reviewed:{true\|false}` – reviewed status
- `excluded:{true\|false}` – exclusion status
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries |
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20unverified:true" \
-u USERNAME_OR_ACCESS_TOKEN
```
```
phrase translations list \
--project_id \
--sort updated_at \
--order desc \
--query 'PhraseApp* unverified:true' \
--access_token
```
## Verify translations selected by query
```
PATCH /v2/projects/:project_id/translations/verify
```
Verify all translations that are matching the query `my dog`.
### Parameters
| Name | Type | Description |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` *(optional)* | `string` | Specify a query to find translations by content (including wildcards).
**Note:** Search is limited to 10,000 results and may not include recently updated data (depending on the project size).
Supported qualifiers:
- `id:translation_id,...` – comma-separated list of IDs
- `tags:XYZ` – tag on the translation
- `unverified:{true\|false}` – verification status
- `reviewed:{true\|false}` – reviewed status
- `excluded:{true\|false}` – exclusion status
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries
|
| `sort` *(optional)* | `string` | Sort criteria. Can be one of: `key_name`, `created_at`, `updated_at`.
**Default:** `key_name` |
| `order` *(optional)* | `string` | Order direction. Can be one of: `asc`, `desc`.
**Default:** `asc` |
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/translations/verify" \
-u USERNAME_OR_ACCESS_TOKEN \
-X PATCH \
-d '{"q":"my dog unverified:true","sort":"updated_at","order":"desc"}' \
-H 'Content-Type: application/json'
```
```
phrase translations verify \
--project_id \
--data '{"query":""my dog unverified:true"", "sort":"updated_at", "order":"desc"}' \
--access_token
```
## Find recently updated keys
```
GET /v2/projects/:project_id/keys
```
Find updated keys with with the `updated_at` qualifier like `updated_at:>=2013-02-21T00:00:00Z`. This example returns keys that have been updated on or after 2013-02-21.
### Parameters
| Name | Type | Description |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sort` *(optional)* | `string` | Sort by field. Can be one of: `name`, `created_at`, `updated_at`.
**Default:** `name` |
| `order` *(optional)* | `string` | Order direction. Can be one of: `asc`, `desc`.
**Default:** `asc` |
| `q` *(optional)* | `string` | Specify a query to do broad search for keys by name (including wildcards).
Supported qualifiers:
- `ids:key_id,...` – queries on a comma-separated list of IDs
- `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`)
- `tags:tag_name,...` – filter for keys with certain tags
- `uploads:upload_id,...` – filter for keys with certain uploads
- `job:{true\|false}` – filter for keys mentioned in a job
- `translated:{true\|false}` – requires `locale_id`
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range filtering
- `unmentioned_in_upload:upload_id` – keys not mentioned in given upload |
| `locale_id` *(optional)* | `string` | Locale used to determine the translation state of a key when filtering for untranslated or translated keys. |
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/keys?sort=updated_at&order=desc&q=updated_at:%3E=2013-02-21T00:00:00Z&locale_id=abcd1234abcd1234abcd1234abcd1234" \
-u USERNAME_OR_ACCESS_TOKEN
```
```
phrase keys list \
--project_id \
--sort updated_at \
--order desc \
--query "updated_at:>=2013-02-21T00:00:00Z" \
--locale_id abcd1234abcd1234abcd1234abcd1234 \
--access_token
```
## Find keys with a certain tag
```
GET /v2/projects/:project_id/keys
```
Keys with certain tags can be filtered with the qualifier `tags:`.
### Parameters
| Name | Type | Description |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` *(optional)* | `string` | Specify a query to do broad search for keys by name (including wildcards).
Supported qualifiers:
- `ids:key_id,...` – queries on a comma-separated list of IDs
- `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`)
- `tags:tag_name,...` – filter for keys with certain tags
- `uploads:upload_id,...` – filter for keys with certain uploads
- `job:{true\|false}` – filter for keys mentioned in an active job
- `translated:{true\|false}` – requires `locale_id`
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date
- `unmentioned_in_upload:upload_id` – filter keys unmentioned in a specific upload
|
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/keys?q=tags:admin" \
-u USERNAME_OR_ACCESS_TOKEN
```
```
phrase keys list \
--project_id \
--query "tags:admin" \
--access_token
```
## Add tags to collection of keys
```
PATCH /v2/projects/:project_id/keys/tag
```
Add the tags `landing-page` and `release-1.2` to all keys that start with `dog` and are translated in the locale `abcd1234abcd1234abcd1234abcd1234`.
### Parameters
| Name | Type | Description |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` *(optional)* | `string` | Specify a query to do broad search for keys by name (including wildcards).
Supported qualifiers:
- `ids:key_id,...` – queries on a comma-separated list of IDs
- `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`)
- `tags:tag_name,...` – filter for keys with certain tags
- `uploads:upload_id,...` – filter for keys with certain uploads
- `job:{true\|false}` – filter for keys mentioned in an active job
- `translated:{true\|false}` – requires `locale_id`
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date
- `unmentioned_in_upload:upload_id` – filter keys unmentioned in a specific upload
|
| `tags` | `string` | Tag or comma-separated list of tags to add to the matching collection of keys |
| `locale_id` *(optional)* | `id` | Locale used to determine the translation state of a key when filtering for untranslated or translated keys. |
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/keys/tag" \
-u USERNAME_OR_ACCESS_TOKEN \
-X PATCH \
-d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
-H 'Content-Type: application/json'
```
```
phrase keys tag \
--project_id \
--data '{"query":"'dog* translated:true'", "tags":"landing-page,release-1.2", "locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token
```
## Remove tags from collection of keys
```
PATCH /v2/projects/:project_id/keys/untag
```
Remove the tags `landing-page` and `release-1.2` from all keys that start with `dog` and are translated in the locale `abcd1234abcd1234abcd1234abcd1234`.
### Parameters
| Name | Type | Description |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` *(optional)* | `string` | Specify a query to do broad search for keys by name (including wildcards).
Supported qualifiers:
- `ids:key_id,...` – queries on a comma-separated list of IDs
- `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`)
- `tags:tag_name,...` – filter for keys with certain tags
- `uploads:upload_id,...` – filter for keys with certain uploads
- `job:{true\|false}` – filter for keys mentioned in an active job
- `translated:{true\|false}` – requires `locale_id`
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date
- `unmentioned_in_upload:upload_id` – filter keys unmentioned in a specific upload
|
| `tags` | `string` | Tag or comma-separated list of tags to remove from the matching collection of keys |
| `locale_id` *(optional)* | `id` | Locale used to determine the translation state of a key when filtering for untranslated or translated keys. |
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/keys/untag" \
-u USERNAME_OR_ACCESS_TOKEN \
-X PATCH \
-d '{"q":"dog* translated:true","tags":"landing-page,release-1.2","locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
-H 'Content-Type: application/json'
```
```
phrase keys untag \
--project_id \
--data '{"query":"'dog* translated:true'", "tags":"landing-page,release-1.2", "locale_id":"abcd1234abcd1234abcd1234abcd1234"}' \
--access_token
```
## Find keys with broad text match
```
GET /v2/projects/:project_id/keys
```
Example query `my dog`.
### Parameters
| Name | Type | Description |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` *(optional)* | `string` | Specify a query to do broad search for keys by name (including wildcards).
Supported qualifiers:
- `ids:key_id,...` – queries on a comma-separated list of IDs
- `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`)
- `tags:tag_name,...` – filter for keys with certain tags
- `uploads:upload_id,...` – filter for keys with certain uploads
- `job:{true\|false}` – filter for keys mentioned in an active job
- `translated:{true\|false}` – requires `locale_id`
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range filter
- `unmentioned_in_upload:upload_id` – keys not mentioned in specific upload |
### Matches
**My dog** is lazy **my dog** is lazy angry **dog** in **my** house
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/keys?q=my%20dog" \
-u USERNAME_OR_ACCESS_TOKEN
```
```
phrase keys list \
--project_id \
--query "my dog" \
--access_token
```
## Find keys with exact text match
```
GET /v2/projects/:project_id/keys
```
Example query `"my dog is lazy"` (note backslashes before any whitespace character in the example query)
### Parameters
| Name | Type | Description |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` *(optional)* | `string` | Specify a query to do broad search for keys by name (including wildcards).
Supported qualifiers:
- `ids:key_id,...` – queries on a comma-separated list of IDs
- `name:key_name,...` – exact key names (comma-separated, escape spaces/commas/colons with `\\`)
- `tags:tag_name,...` – filter for keys with certain tags
- `uploads:upload_id,...` – filter for keys with certain uploads
- `job:{true\|false}` – filter for keys mentioned in an active job
- `translated:{true\|false}` – requires `locale_id` to be specified
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – date range queries
- `unmentioned_in_upload:upload_id` – filter keys unmentioned within upload |
### Matches
~~My dog is lazy~~ my dog is lazy ~~angry dog in my house~~
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/keys?q=name:my%5C%20dog%5C%20is%5C%20lazy" \
-u USERNAME_OR_ACCESS_TOKEN
```
```
phrase keys list \
--project_id \
--query "name:my\ dog\ is\ lazy" \
--access_token
```
## Find keys with wildcard character matching
```
GET /v2/projects/:project_id/keys
```
Example query `*dog is*`
### Parameters
| Name | Type | Description |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `q` *(optional)* | `string` | Specify a query to do broad search for keys by name (including wildcards).
The following qualifiers are supported in the search term:
- `ids:key_id,...` – queries on a comma-separated list of IDs
- `name:key_name,...` – exact key names (comma-separated; escape spaces, commas, and colons with `\\`)
- `tags:tag_name,...` – filter for keys with certain tags
- `uploads:upload_id,...` – filter for keys with certain uploads
- `job:{true\|false}` – filter for keys mentioned in an active job
- `translated:{true\|false}` – filter by translation status (requires `locale_id`)
- `updated_at:{>=\|<=}2013-02-21T00:00:00Z` – filter by date range
- `unmentioned_in_upload:upload_id` – filter keys unmentioned within specific upload |
### Matches
My **dog is** lazy my **dog is** lazy ~~angry dog in my house~~
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/keys?q=*dog%20is*" \
-u USERNAME_OR_ACCESS_TOKEN
```
```
phrase keys list \
--project_id \
--query '*dog is*' \
--access_token
```
## Upload an Excel file with several translations
```
POST /v2/projects/:project_id/uploads
```
Suppose you have an excel file where the 'A' column contains the key names, the 'B' column contains English translations, the 'C' column contains German translations and the 'D' column contains comments. Furthermore, the actual content starts in the second row, since the first row is reserved for a header. You can upload this file and import all translations at once!
### Parameters
| Name | Type | Description |
| ----------------------------------- | -------- | ----------------------------------------------------------- |
| `file` | `file` | File to be imported |
| `file_format` | `string` | File format. Auto-detected when possible and not specified. |
| `locale_mapping[en]` | `string` | Name of the column containing translations for locale `en`. |
| `locale_mapping[de]` | `string` | Name of the column containing translations for locale `de`. |
| `format_options[comment_column]` | `string` | Name of the column containing descriptions for keys. |
| `format_options[tag_column]` | `string` | Name of the column containing tags for keys. |
| `format_options[key_name_column]` | `string` | Name of the column containing the names of the keys. |
| `format_options[first_content_row]` | `string` | Name of the first row containing actual translations. |
### Example Request
```
curl "https://api.phrase.com/v2/projects/:project_id/uploads" \
-u USERNAME_OR_ACCESS_TOKEN \
-X POST \
-F file=@/path/to/my/file.xlsx \
-F file_format=xlsx \
-F locale_mapping[en]=B \
-F locale_mapping[de]=C \
-F format_options[comment_column]=D \
-F format_options[tag_column]=E \
-F format_options[key_name_column]=A \
-F format_options[first_content_row]=2
```
```
phrase uploads create \
--project_id \
--file /path/to/my/file.xlsx \
--file_format xlsx \
--locale_id abcd1234cdef1234abcd1234cdef1234 \
--tags awesome-feature,needs-proofreading \
--locale_mapping '{"en": "B", "de": "C"}' \
--format_options '{"comment_column": "D", "tag_column": "E", "key_name_column": "A", "first_content_row": "2"}' \
--access_token
```