> ## 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. # Download multilingual content as XLIFF synchronously > Download Braze multilingual content as XLIFF 2.0, ready for translation. The connector applies its segmentation and serialization rules, including locale fallbacks across the source and target Braze locale codes. Pair with `upload-xliff-file` once translated. ## OpenAPI ````yaml /openapi/phrase-connectors.json post /braze_multilang/v1/sync/download-xliff-file openapi: 3.1.0 info: title: Connectors API description: > The Connectors API (Bifrost) is the public gateway between Phrase clients and the individual content connectors (Google Drive, Contentful, Tridion, Knak, Optimizely, ...). Every endpoint follows the same request/response contract — this page documents the shared pieces. Per-connector pages below show the connector-specific request bodies. --- ## Gateway prefix When calling Bifrost through the public Phrase gateway, **prefix every path with `/connectors`**: ``` https:///connectors//v1/ ``` Internal callers (service-to-service inside the Phrase cluster) call Bifrost directly and omit the `/connectors` prefix. The OpenAPI paths below show the *internal* form. --- ## Authentication All endpoints require an IDM-issued JWT in the `Authorization` header: ``` Authorization: Bearer ``` Bifrost decodes the token, resolves the caller's TMS account via IDM Discovery, and exchanges the JWT for a short-lived TMS access token transparently. Callers do not handle TMS tokens directly. --- ## Connector identity & credentials Every request body carries a **`connectorUuid`** that references a connector instance configured in TMS. Bifrost loads the connector's stored credentials and uses them to talk to the underlying system — callers never handle connector credentials directly. New connectors are created in TMS — e.g. for Google Drive: `https:///tms/connectors/create?connectorType=GOOGLE_DRIVE2`. --- ## Synchronous vs asynchronous variants Most operations expose two variants: | Path prefix | Behavior | |---|---| | `/sync/...` | Blocks until the operation completes. Best for small payloads / interactive flows. | | `/async/...` | Returns immediately with `{ requestId, webHookUrl }`. Bifrost POSTs the result to `X-Webhook` when ready, or you can poll. Use for large payloads and long-running work. | For async endpoints, the `X-Webhook` header is **required** — Bifrost will POST the result there once the connector finishes processing. --- ## Common headers | Header | Direction | Purpose | |---|---|---| | `Authorization` | request | `Bearer ` — required on every endpoint. | | `X-ActionId` | request + response | Correlation id propagated through Phrase logs. Generated by Bifrost when omitted; always returned on the response. | | `X-Webhook` | request | Required on `/async/...` endpoints. URL that receives the result. | | `X-ResponseType` | request | `ID` (default) — JSON with `storageId`. `OBJECT` — raw binary stream (`application/octet-stream`). Use `ID` for files > 1 MB. | | `X-Upload-Mode` | request | `STORAGE` (default) — upload bytes already in file storage. `STREAM` — initialize a streaming upload session; the response carries `uploadUrl` + `X-Stream-Token` for the phase-2 PUT. Currently supported by Google Drive only. | | `X-Stream-Token` | request | Required on phase-2 streaming upload PUTs. Value returned by phase-1. | --- ## Raw vs XLIFF operations Most connectors expose two content shapes: - **Raw** (`download-raw-file`, `upload-raw-file`) — the connector's native content, unmodified. Use when you want the original asset. - **XLIFF** (`download-xliff-file`, `upload-xliff-file`) — the same content converted to/from XLIFF 2.0 ready for translation. The connector applies its segmentation and serialization rules. `convert-to-xliff` / `convert-to-raw` are the standalone conversion variants that operate on already-stored files referenced by `storageId`. --- ## Error model Errors come back in two envelopes depending on the endpoint: - **Operations that report partial success** (upload, convert) return `200 OK` with: ```json { "success": false, "errors": [{ "code": "404", "message": "Content was not found." }] } ``` - **Hard failures** return a 4xx/5xx with an `ErrorResponse` body. HTTP status maps to the Bifrost error taxonomy: | Status | Error type | Typical cause | |---|---|---| | 401, 403 | `auth_error` | Missing/invalid JWT, IDM identity unresolved, connector credential rejected upstream. | | 429 | `rate_limited` | Caller or upstream rate limit hit. | | 400 | `processing_error` | Bad request body, validation failure, unsupported configuration. | | 4xx (other) | `processing_error` | Connector returned a client error. | | 5xx | `upstream_error` | Connector or downstream Phrase service failed. | | timeout | `timeout` | Upstream did not respond in time. | | deserialization | `deserialization` | Connector returned a malformed response. | | other | `unknown` | Unclassified. | `X-ActionId` is returned on every error response — quote it when reporting issues. --- ## Streaming uploads (two-phase) For connectors that support `X-Upload-Mode: STREAM` (currently Google Drive): 1. **Phase 1** — `POST //v1/sync/upload-raw-file` with `X-Upload-Mode: STREAM` and a body that includes `name`, `size`, and a `FOLDER` path. The response is: ```json { "uploadUrl": "//v1/sync/upload-raw-file/stream/", "streamToken": "", "expiresAt": "2026-01-29T13:48:01Z", "maxBytes": 240113628 } ``` `uploadUrl` is relative — prepend the gateway host (and `/connectors` prefix when calling through the public gateway). 2. **Phase 2** — `PUT ` with the raw bytes, `X-Stream-Token: `, and a `Content-Type` matching the file. `Content-Length` must equal the declared `size`. Streams expire at `expiresAt`. Large transfers may need increased client-side timeouts. version: '1.0' servers: - url: https://eu.phrase.com/connectors description: The API server for EU data center. - url: https://us.phrase.com/connectors description: The API server for US data center. security: - bearerAuth: [] tags: - name: Files description: Upload and download files via Phrase file storage. - name: GitHub description: GitHub connector. Supports raw download/upload and batch uploads. - name: Braze description: Braze multilingual content connector. - name: Contentful description: >- Contentful headless CMS connector. Supports raw and XLIFF download/upload, listing entries, and standalone XLIFF conversion. Requires a `connectorUuid` and a `configuration` block on every request. - name: Google Drive description: >- Google Drive connector. Supports raw download/upload (JSON `storageId` or streamed binary via `X-ResponseType: OBJECT`) plus the two-phase streaming upload (`X-Upload-Mode: STREAM` → `X-Stream-Token`). - name: Connectors description: >- Cross-connector discovery and metadata: list available connector types, retrieve schemas, and inspect supported operations. - name: Tridion Docs description: SDL Tridion CMS connector. - name: GitHub description: Perform operations using the GitHub connector. - name: Optimizely description: Optimizely CMS / experimentation connector. - name: Knak description: >- Knak connector. Supports listing translation requests plus raw download/upload. externalDocs: description: Tutorial-style integration guides (Phrase Confluence, INT space) url: https://phrase.atlassian.net/wiki/spaces/INT paths: /braze_multilang/v1/sync/download-xliff-file: post: tags: - Braze summary: Download multilingual content as XLIFF synchronously description: > Download Braze multilingual content as XLIFF 2.0, ready for translation. The connector applies its segmentation and serialization rules, including locale fallbacks across the source and target Braze locale codes. Pair with `upload-xliff-file` once translated. operationId: brazeMultilangDownloadXliffContentSync parameters: - name: X-ActionId in: header description: > A logging ID of the request. It is propagated through Phrase systems, making it easier to connect logs from various services. If no ActionId is sent with a request, one will be generated by Bifrost and returned with the response. required: false schema: type: string default: '' example: e48eda63928c4155bez9fdbsaadc15f3 - name: X-ResponseType in: header description: > Specify if the response should contain the processed object itself in an application/octet-stream body, or a application/json body with an ID that can be then used to retrieve the object using a /load-content endpoint. Note that for larger files (> 1 MB), it is advised to use the ID option which is also default. required: false schema: type: string default: ID enum: - ID - OBJECT requestBody: content: application/json: schema: $ref: '#/components/schemas/BrazeMultilangDownloadXliffFileApiBody' additionalProperties: default: '' default: '' examples: Download as XLIFF: description: Download as XLIFF value: connectorUuid: 4282fec0-d2e9-4266-8733-3e634feb7b59 configuration: {} path: pathType: ROOT sourceLocale: en-US targetLocale: de-DE required: true responses: '200': description: OK — XLIFF binary stream (returned when `X-ResponseType=OBJECT`). headers: Content-Disposition: description: '`attachment; filename="export.xliff"`.' style: simple schema: type: array contains: default: '' items: default: '' unevaluatedItems: default: '' X-ActionId: description: > A logging ID of the request. It is propagated through Phrase systems, making it easier to connect logs from various services. If no ActionId is sent with a request, one will be generated by Bifrost and returned with the response. style: simple schema: type: array contains: default: '' items: default: '' unevaluatedItems: default: '' Content-Type: description: '`application/xliff+xml`.' style: simple schema: type: array contains: default: '' items: default: '' unevaluatedItems: default: '' content: application/xliff+xml: schema: type: string format: binary additionalProperties: default: '' default: '' default: description: > Bad request or upstream failure. Returns an `ErrorResponse` body. See the API overview's "Error model" section for the HTTP status → error-type mapping. The `X-ActionId` header is set on every error response — quote it when reporting issues. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' additionalProperties: default: '' default: '' components: schemas: BrazeMultilangDownloadXliffFileApiBody: type: object description: >- Request body for downloading Braze multilingual content as XLIFF 2.0. The connector loads stored credentials from TMS based on `connectorUuid` and applies its segmentation and serialization rules to produce a translation-ready XLIFF. properties: connectorUuid: type: string default: '' description: UUID of a connector instance configured in TMS. example: 4282fec0-d2e9-4266-8733-3e634feb7b59 configuration: $ref: '#/components/schemas/BrazeMultilangConfigurationDto' default: '' description: Braze-specific behavior knobs. path: $ref: '#/components/schemas/WebApiBrazeMultilangPathDto' type: 'null' default: '' description: >- Selector inside the Braze workspace — content block / campaign ID, or ROOT. sourceLocale: type: - string - 'null' default: '' description: Source locale of the content (Phrase locale code). example: en-US targetLocale: type: - string - 'null' default: '' description: Target locale of the content (Phrase locale code). example: de-DE required: - connectorUuid ErrorResponse: type: object properties: problemDetail: $ref: '#/components/schemas/ProblemDetail' BrazeMultilangConfigurationDto: type: object description: > Connector configuration for the Braze Multilang connector. Every field is optional; omitted fields (or an omitted configuration object) fall back to their defaults. example: tags: - marketing - priority maxDaysFromLastUpdate: 30 includeHash: true properties: tags: type: array default: [] description: Optional list of tags to filter items during listing items: type: string maxDaysFromLastUpdate: type: integer format: int32 default: 0 description: >- Optional limit in days based on last update date; items older than this threshold are excluded from listing. 0 means no recency filter is applied. includeHash: type: boolean default: false description: >- Whether to compute and include a hash of the localized content during listing. When true, the localized content is downloaded for each item during listing in order to calculate the hash — typically required for change detection. Items without an existing translation are filtered out. When false or omitted, listing is faster but no hash is computed. WebApiBrazeMultilangPathDto: discriminator: propertyName: pathType mapping: ROOT: '#/components/schemas/RootPathDto' EMAIL_TEMPLATE_DIRECTORY: '#/components/schemas/EmailTemplateDirectoryPathDto' CAMPAIGN_DIRECTORY: '#/components/schemas/CampaignDirectoryPathDto' CANVAS_DIRECTORY: '#/components/schemas/CanvasDirectoryPathDto' CONTENT_BLOCK_DIRECTORY: '#/components/schemas/ContentBlockDirectoryPathDto' EMAIL_TEMPLATE: '#/components/schemas/EmailTemplatePathDto' CAMPAIGN: '#/components/schemas/CampaignPathDto' CANVAS: '#/components/schemas/CanvasPathDto' CONTENT_BLOCK: '#/components/schemas/ContentBlockPathDto' oneOf: - $ref: '#/components/schemas/RootPathDto' - $ref: '#/components/schemas/EmailTemplateDirectoryPathDto' - $ref: '#/components/schemas/CampaignDirectoryPathDto' - $ref: '#/components/schemas/CanvasDirectoryPathDto' - $ref: '#/components/schemas/ContentBlockDirectoryPathDto' - $ref: '#/components/schemas/EmailTemplatePathDto' - $ref: '#/components/schemas/CampaignPathDto' - $ref: '#/components/schemas/CanvasPathDto' - $ref: '#/components/schemas/ContentBlockPathDto' properties: pathType: type: string required: - pathType ProblemDetail: type: object properties: type: type: string format: uri title: type: string status: type: integer format: int32 detail: type: string instance: type: string format: uri properties: type: object additionalProperties: {} errorType: type: string description: Bifrost error taxonomy — see the "Error model" section above. enum: - auth_error - upstream_error - processing_error - deserialization - timeout - rate_limited - unknown RootPathDto: properties: pathType: type: string default: '' enum: - ROOT example: ROOT required: - pathType EmailTemplateDirectoryPathDto: properties: pathType: type: string default: '' enum: - EMAIL_TEMPLATE_DIRECTORY example: EMAIL_TEMPLATE_DIRECTORY required: - pathType CampaignDirectoryPathDto: properties: pathType: type: string default: '' enum: - CAMPAIGN_DIRECTORY example: CAMPAIGN_DIRECTORY required: - pathType CanvasDirectoryPathDto: properties: pathType: type: string default: '' enum: - CANVAS_DIRECTORY example: CANVAS_DIRECTORY required: - pathType ContentBlockDirectoryPathDto: properties: pathType: type: string default: '' enum: - CONTENT_BLOCK_DIRECTORY example: CONTENT_BLOCK_DIRECTORY required: - pathType EmailTemplatePathDto: properties: pathType: type: string default: '' enum: - EMAIL_TEMPLATE example: EMAIL_TEMPLATE id: type: string required: - pathType CampaignPathDto: properties: pathType: type: string default: '' enum: - CAMPAIGN example: CAMPAIGN id: type: string required: - pathType CanvasPathDto: properties: pathType: type: string default: '' enum: - CANVAS example: CANVAS id: type: string required: - pathType ContentBlockPathDto: properties: pathType: type: string default: '' enum: - CONTENT_BLOCK example: CONTENT_BLOCK id: type: string required: - pathType securitySchemes: bearerAuth: type: http description: >- IDM-issued JWT. Obtain via the IDM authentication flow and pass as: Bearer scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.