Install & Compatibility
Where this runs
tested against v3.24.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.551s · 27.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.2s · import 0.485s · 28MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Configuration
✓ import phrase_api; config = phrase_api.Configuration()
Used to set API keys and other client-wide settings.
ApiClient
✓ import phrase_api; client = phrase_api.ApiClient(config)
The core HTTP client that handles requests and responses.
LocalesApi
✓ import phrase_api; locales_api = phrase_api.LocalesApi(client)
One of many API modules (e.g., ProjectsApi, KeysApi, etc.) available directly under the `phrase_api` package.
ApiException
✓ from phrase_api.rest import ApiException
Specific exception type raised for API errors (e.g., 4xx, 5xx responses).
This quickstart demonstrates how to configure the client with an API token, create an API instance, and fetch a list of locales for a given project. It uses environment variables for sensitive data like API tokens and project IDs.
import os
import phrase_api
from phrase_api.rest import ApiException
from pprint import pprint
# Configure API key authorization
configuration = phrase_api.Configuration()
configuration.api_key['api_token'] = os.environ.get('PHRASE_API_TOKEN', 'YOUR_PHRASE_API_TOKEN')
# Optionally, uncomment for bearer token prefix:
# configuration.api_key_prefix['api_token'] = 'Bearer'
# Create an instance of the API client
api_client = phrase_api.ApiClient(configuration)
# Create an instance of a specific API (e.g., LocalesApi)
locales_api = phrase_api.LocalesApi(api_client)
try:
# List locales for a project
project_id = os.environ.get('PHRASE_PROJECT_ID', 'YOUR_PHRASE_PROJECT_ID') # Replace with your project ID
# Optional: Two-Factor-Authentication token, if required for your account/action
x_phrase_app_otp = os.environ.get('PHRASE_OTP_TOKEN')
# Fetching the first page of locales, 25 per page
api_response = locales_api.locales_list(
project_id,
page=1,
per_page=25,
x_phrase_app_otp=x_phrase_app_otp
)
print("Successfully listed locales:")
pprint(api_response)
except ApiException as e:
print(f"Exception when calling LocalesApi->locales_list: {e}")
if e.status == 401:
print("Hint: Check your PHRASE_API_TOKEN and ensure it has necessary permissions.")
elif e.status == 404:
print("Hint: Check your PHRASE_PROJECT_ID and ensure it exists and is accessible.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingAs a generated client, new versions of `phrase-api` may introduce breaking changes to reflect updates in the underlying Phrase Strings API. Method signatures, object structures, or enum values can change without backward compatibility.fixRefer to the Phrase API changelog and the specific client version's release notes for migration guides. Always test new versions in a non-production environment before deployment.
affects: All major versions (e.g., v3.x.x to v4.x.x, or even minor versions reflecting significant API changes).
gotchaList operations (e.g., `locales_list`, `keys_list`) often implement server-side pagination. The client does not automatically fetch all pages.fixAlways check for `page` and `per_page` parameters in list methods. To retrieve all items, you must manually loop through pages until an empty list is returned or the number of items is less than `per_page`.
affects: All versions
gotchaSome API operations or accounts might require a Two-Factor-Authentication (2FA) token, passed via the `X-PhraseApp-OTP` header.fixIf you encounter 403 errors or specific messages about 2FA, ensure you are passing the `x_phrase_app_otp` parameter to the API method if your Phrase account requires it. The value is typically a temporary code generated by your 2FA app.
affects: All versions
Errors
Common errors & fixes
phrase_api.rest.ApiException: (401) Reason: Unauthorized
The provided API token is either missing, incorrect, or lacks the necessary permissions for the requested action.
fixVerify that `PHRASE_API_TOKEN` (or `configuration.api_key['api_token']`) is set correctly with a valid API token from your Phrase Strings account. Ensure the token has the scopes required for the specific API calls you are making.
phrase_api.rest.ApiException: (404) Reason: Not Found
The resource you are trying to access (e.g., project ID, locale ID, key ID) does not exist or your token does not have access to it.
fixDouble-check the IDs you are passing to API methods (e.g., `project_id`, `locale_id`). Confirm that the resource actually exists and that your API token has read/write access to it within the Phrase Strings platform.
AttributeError: module 'phrase_api' has no attribute 'SomeApiClass'
You are trying to import or access an API class that does not exist or has a different name in the current `phrase-api` version.
fixConsult the official Phrase Strings API documentation or the library's GitHub repository to find the correct class name and its placement within the `phrase_api` package. It's usually `phrase_api.<ApiClassName>Api` (e.g., `phrase_api.ProjectsApi`).
Upgrade
Version history
3.24.0latest on PyPI · released Jun 16, 2026
Audit
Dependencies
No dependency data recorded yet.