Phrase Repo Syncs API
The Repo Syncs API allows you to synchronize your Phrase projects with your code repositories. You can import translations from your repository to Phrase and export translations from Phrase to your repository.
OpenAPI Specification
openapi: 3.0.3
info:
title: Phrase Strings API Reference Accounts Repo Syncs API
version: 2.0.0
description: Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase Strings for your account.
contact:
name: Phrase Support
url: https://developers.phrase.com/api/
email: support@phrase.com
x-logo:
url: https://developers.phrase.com/images/phrase-logo.svg
backgroundColor: '#03eab3'
altText: Phrase Strings
termsOfService: https://phrase.com/terms/
license:
name: MIT
url: https://choosealicense.com/licenses/mit/
servers:
- url: https://api.phrase.com/v2
description: EU production server
- url: https://api.us.app.phrase.com/v2
description: US production server
security:
- Token: []
- Basic: []
tags:
- name: Repo Syncs
description: 'The Repo Syncs API allows you to synchronize your Phrase projects with your code repositories.
You can import translations from your repository to Phrase and export translations from Phrase to your repository.
'
paths:
/accounts/{account_id}/repo_syncs:
get:
summary: Get Repo Syncs
description: Lists all Repo Syncs from an account
operationId: repo_sync/list
tags:
- Repo Syncs
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/account_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/repo_sync'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
Link:
$ref: '#/components/headers/Link'
Pagination:
$ref: '#/components/headers/Pagination'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/accounts/ab12cd34/repo_syncs\"\\\n -u USERNAME_OR_ACCESS_TOKEN"
- lang: CLI v2
source: 'phrase repo_syncs list \
--account_id abcd1234 \
--access_token <token>'
x-cli-version: '2.24'
post:
summary: Create a Repo Sync
description: Create a new Repo Sync.
operationId: repo_sync/create
tags:
- Repo Syncs
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/account_id'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/repo_sync'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/accounts/ab12cd34/repo_syncs\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"project_id\": \"abcd1234abcd1234abcd1234abcd1234\",\n \"git_provider\": \"github\",\n \"connection_type\": \"github_app\",\n \"repo_name\": \"my-org/my-repo\",\n \"base_branch\": \"main\"\n }'"
- lang: CLI v2
source: 'phrase repo_syncs create \
--account_id abcd1234 \
--data ''{"project_id":"abcd1234abcd1234abcd1234abcd1234","git_provider":"github","connection_type":"github_app","repo_name":"my-org/my-repo","base_branch":"main"}'' \
--access_token <token>'
requestBody:
required: true
content:
application/json:
schema:
type: object
title: repo_sync/create/parameters
required:
- project_id
- repo_name
- connection_type
properties:
project_id:
description: ID of the project to connect the Repo Sync to.
type: string
example: abcd1234abcd1234abcd1234abcd1234
git_provider:
description: The Git provider to use.
default: github
type: string
enum:
- github
- gitlab
- bitbucket
example: github
connection_type:
description: 'The authentication method used to connect to the Git provider.
Defaults to `token` if not specified.
Valid values:
- `token` — Personal access token stored on the Repo Sync. Supported by all providers.
- `github_app` — Authenticate via the Phrase GitHub App installation on your account. GitHub only. The account must already have the GitHub App installed; if not, the response will include a `github_app_installation_url`.
- `self_hosted` — Token-based auth for self-hosted Git instances. Requires `custom_api_endpoint`.'
type: string
enum:
- token
- github_app
- self_hosted
example: github_app
repo_name:
description: Full repository name including the owner, e.g. `my-org/my-repo`.
type: string
example: my-org/my-repo
base_branch:
description: The default branch to use for imports and exports.
type: string
example: main
pr_branch:
description: Branch that translations are exported to before opening a pull request. If omitted, exports go directly to `base_branch`.
type: string
example: phrase-translations
auto_import:
description: Enable automatic import of translations triggered by pushes to the repository.
type: boolean
example: false
access_token:
description: Personal access token for the Git provider. Required when `connection_type` is `token` or `self_hosted`. Not used for `github_app`.
type: string
example: ghp_xxxxxxxxxxxxxxxxxxxx
custom_api_endpoint:
description: Custom API endpoint URL for self-hosted Git instances. Required when `connection_type` is `self_hosted`.
type: string
example: https://git.example.com/api/v4
x-cli-version: '2.60'
/accounts/{account_id}/repo_syncs/{id}:
get:
summary: Get a single Repo Sync
description: Shows a single Repo Sync setting.
operationId: repo_sync/show
tags:
- Repo Syncs
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/repo_sync'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/accounts/ab12cd34/repo_syncs/56ef78\"\\\n -u USERNAME_OR_ACCESS_TOKEN"
- lang: CLI v2
source: 'phrase repo_syncs show \
--id <id> \
--account_id abcd1234 \
--access_token <token>'
x-cli-version: '2.24'
/accounts/{account_id}/repo_syncs/{id}/export:
post:
summary: Export to code repository
description: 'Export translations from Phrase Strings to repository provider according to the
.phrase.yml file within the code repository.
*Export is done asynchronously and may take several seconds depending on the project size.*'
operationId: repo_sync/export
tags:
- Repo Syncs
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/id'
requestBody:
required: false
content:
application/json:
schema:
type: object
title: repo_sync/export/parameters
properties:
pr_branch:
description: Source branch to open a pull request from
type: string
example: my-feature-branch
branch:
description: Strings branch to export from
type: string
example: my-strings-branch
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/repo_sync_event'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/accounts/ab12cd34/repo_syncs/45ef6789/export\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -H 'Content-Type: application/json' \\\n -d '{\"pr_branch\":\"my-feature-branch\", \"branch\":\"my-strings-branch\"}'"
- lang: CLI v2
source: 'phrase repo_syncs export \
--id <repo_sync_id> \
--data ''{"pr_branch":"my-feature-branch", "branch":"my-strings-branch"}'' \
--access_token <token>'
/accounts/{account_id}/repo_syncs/{id}/import:
post:
summary: Import from code repository
description: 'Import translations from repository provider to Phrase Strings according to the .phrase.yml file
within the code repository.
_Import is done asynchronously and may take several seconds depending on the project size._'
operationId: repo_sync/import
tags:
- Repo Syncs
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/id'
requestBody:
required: false
content:
application/json:
schema:
type: object
title: repo_sync/import/parameters
properties:
repository_branch:
description: Branch to import from
type: string
example: my-feature-branch
branch:
description: Strings branch to import to
type: string
example: my-strings-branch
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/repo_sync_event'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/accounts/ab12cd34/repo_syncs/45ef6789/import\"\\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -d '{\"repository_branch\":\"my-feature-branch\", \"branch\":\"my-strings-branch\"}' \\\n -H 'Content-Type: application/json'"
- lang: CLI v2
source: 'phrase repo_syncs import \
--id <repo_sync_id> \
--data ''{"repository_branch":"my-feature-branch", "branch":"my-strings-branch"}'' \
--access_token <token>'
/accounts/{account_id}/repo_syncs/{id}/deactivate:
post:
summary: Deactivate a Repo Sync
description: 'Deactivate an active Repo Sync. Import and export can''t be performed on deactivated syncs
and the pushes to the repository won''t trigger the import to Phrase.'
operationId: repo_sync/deactivate
tags:
- Repo Syncs
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/repo_sync'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/accounts/ab12cd34/repo_syncs/45ef6789/deactivate\"\\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -H 'Content-Type: application/json'"
- lang: CLI v2
source: 'phrase repo_syncs deactivate \
--id <repo_sync_id> \
--access_token <token>'
x-cli-version: '2.24'
/accounts/{account_id}/repo_syncs/{id}/activate:
post:
summary: Activate a Repo Sync
description: 'Activate a deactivated Repo Sync. Active syncs can be used to import and export translations,
and imports to Phrase are automatically triggered by pushes to the repository, if configured.'
operationId: repo_sync/activate
tags:
- Repo Syncs
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/id'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/repo_sync'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/accounts/ab12cd34/repo_syncs/45ef6789/activate\"\\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -H 'Content-Type: application/json'"
- lang: CLI v2
source: 'phrase repo_syncs activate \
--id <repo_sync_id> \
--access_token <token>'
x-cli-version: '2.24'
components:
schemas:
repo_sync_event:
type: object
title: repo_sync_event
properties:
id:
type: string
type:
type: string
enum:
- import
- export
created_at:
type: string
format: date-time
status:
type: string
enum:
- running
- success
- failure
pull_request_url:
type: string
description: URL of the pull request created on export
auto_import:
type: boolean
description: Whether the import was triggered by the repo push event
errors:
description: List of error messages, in case of failure
type: array
items:
type: string
example:
type: import
created_at: '2015-01-28T09:52:53Z'
status: failure
auto_import: true
errors:
- Error message 1
- Error message 2
project_short:
type: object
title: project_short
properties:
id:
type: string
name:
type: string
main_format:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
example:
id: abcd1234cdef1234abcd1234cdef1234
name: My Android Project
main_format: xml
created_at: '2015-01-28T09:52:53Z'
updated_at: '2015-01-28T09:52:53Z'
repo_sync:
type: object
title: repo_sync
properties:
id:
type: string
project:
$ref: '#/components/schemas/project_short'
provider:
type: string
enabled:
type: boolean
auto_import:
type: boolean
repo_name:
type: string
created_at:
type: string
format: date-time
last_import_at:
type: string
format: date-time
last_export_at:
type: string
format: date-time
example:
id: abcd1234cdef1234abcd1234cdef1234
project:
id: abcd1234cdef1234abcd1234cdef1234
name: My Android Project
main_format: xml
created_at: '2015-01-28T09:52:53Z'
updated_at: '2015-01-28T09:52:53Z'
provider: github
enabled: true
auto_import: true
repo_name: organization/repo
created_at: '2015-01-28T09:52:53Z'
last_import_at: '2015-01-28T09:52:53Z'
last_export_at: '2015-01-28T09:52:53Z'
errors:
type: object
properties:
message:
type: string
errors:
type: array
items:
type: object
properties:
resource:
type: string
field:
type: string
message:
type: string
example:
message: Validation Failed
errors:
- resource: Resource
field: name
message: can't be blank
headers:
X-Rate-Limit-Reset:
description: Timestamp of end of current time period as UNIX timestamp, see [Rate Limiting](/en/api/strings/pagination#rate-limiting)
schema:
type: integer
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
schema:
type: integer
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
schema:
type: integer
Link:
description: 'Links to related resources, in the format defined by
[RFC 5988](https://tools.ietf.org/html/rfc5988#section-5).
This will include a link with relation type `next` to the
next page, if there is a next page.'
schema:
type: string
Pagination:
description: Pagination details for navigating through a collection of resources, provided in JSON format.
schema:
type: object
properties:
total_count:
description: Total count of items in the collection.
type: integer
example: 10
total_pages_count:
description: Total number of pages available for the collection.
type: integer
example: 2
current_page:
description: The current page number.
type: integer
example: 1
current_per_page:
description: Number of items currently displayed per page.
type: integer
example: 5
previous_page:
description: Page number of the previous page, if available.
type: integer
next_page:
description: Page number of the next page, if available.
type: integer
example: 2
parameters:
id:
in: path
name: id
description: ID
required: true
schema:
type: string
X-PhraseApp-OTP:
in: header
name: X-PhraseApp-OTP
description: Two-Factor-Authentication token (optional)
required: false
allowEmptyValue: false
schema:
type: string
account_id:
in: path
name: account_id
description: Account ID
required: true
schema:
type: string
responses:
'429':
description: Rate Limiting
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'404':
description: Not Found
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
description: Bad request
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
securitySchemes:
Token:
type: apiKey
in: header
name: Authorization
description: Enter your token in the format `token TOKEN`
Basic:
type: http
scheme: basic
x-tagGroups:
- name: Core Resources
tags:
- Projects
- Locales
- Keys
- Translations
- Uploads
- Tags
- Custom Metadata Properties
- Blacklisted Keys
- Versions / History
- name: Workflows
tags:
- Spaces
- Jobs
- Job Comments
- Job Locales
- Job Templates
- Job Template Locales
- Organization Job Templates
- Organization Job Template Locales
- Comments
- Comment Reactions
- Comment Replies
- Branches
- name: Quality
tags:
- Glossaries
- Glossary Terms
- Glossary Term Translations
- name: Integrations
tags:
- Webhooks
- Distributions
- Releases
- Release Triggers
- name: Ordering
tags:
- Orders
- Style guides
- name: User management
tags:
- Authorizations
- Users
- Accounts
- Members
- Invitations
- name: Screenshots
tags:
- Screenshots
- Screenshot Markers
- name: Misc
tags:
- Formats
- name: Figma Attachments
tags:
- Figma attachments
- Key's Figma attachments