> ## 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. # Convert an XLIFF file from the connector to a raw file used by Contentful asynchronously > Convert a translated XLIFF (referenced by `storageId`) back into Contentful's raw entry format without writing it to Contentful. The result is stored in Phrase file storage and returned as a `storageId` you can then push with `upload-raw-file`. Use this when the upload step is decoupled from the conversion step (e.g. for a preview/review gate). **Async variant.** Returns `{ requestId, webHookUrl }` immediately; the raw file (or its `storageId`) is POSTed to `X-Webhook`. ## OpenAPI ````yaml /openapi/phrase-connectors.json post /contentful2/v1/async/convert-to-raw openapi: 3.0.1 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, 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. externalDocs: description: Tutorial-style integration guides (Phrase Confluence, INT space) url: https://phrase.atlassian.net/wiki/spaces/INT paths: /contentful2/v1/async/convert-to-raw: post: tags: - Contentful summary: >- Convert an XLIFF file from the connector to a raw file used by Contentful asynchronously description: >- Convert a translated XLIFF (referenced by `storageId`) back into Contentful's raw entry format without writing it to Contentful. The result is stored in Phrase file storage and returned as a `storageId` you can then push with `upload-raw-file`. Use this when the upload step is decoupled from the conversion step (e.g. for a preview/review gate). **Async variant.** Returns `{ requestId, webHookUrl }` immediately; the raw file (or its `storageId`) is POSTed to `X-Webhook`. operationId: convertXliffToRawAsync_1 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 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 - name: X-Webhook in: header description: > Required on `/async/...` endpoints. Bifrost POSTs the operation result to this URL once the connector finishes processing. Omitting this header on an async endpoint returns 400. required: true schema: type: string example: https://webhook.site/1b1b1b1b-1b1b-1b1b-1b1b-1b1b1b1b1b1b requestBody: content: application/json: schema: $ref: '#/components/schemas/Contentful2ConvertXliffToRawApiBody' examples: Convert XLIFF back to raw: description: Convert XLIFF back to raw value: storageId: e48eda63928c4155bez9fdbsaadc15f3 sourceLocale: en-US targetLocale: de-DE required: true responses: '200': description: > Successful operation. If X-ResponseType is set to 'ID' or no value is sent in the header, the file is saved and can be retrieved by sending a GET request to this endpoint. If X-ResponseType is set to 'OBJECT', the file is returned as a stream. headers: 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: string content: application/json: schema: $ref: '#/components/schemas/AsyncResponse' examples: Response: description: Response value: requestId: e48eda63-928c-4155-bez9-fdbsaadc15f3 webHookUrl: https://example.tld/my-webhook 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' components: schemas: Contentful2ConvertXliffToRawApiBody: required: - sourceLocale - storageId - targetLocale type: object properties: storageId: type: string description: Storage ID of the translated XLIFF file to convert. example: e48eda63928c4155bez9fdbsaadc15f3 sourceLocale: type: string description: Source locale embedded in the XLIFF (Contentful locale code). example: en-US targetLocale: type: string description: Target locale the XLIFF was translated into. example: de-DE description: >- Request body for converting a stored XLIFF back into Contentful's raw entry format without writing it to Contentful. The result lands in Phrase file storage as a new `storageId` you can then push with `upload-raw-file`. AsyncResponse: type: object properties: webhookUrl: type: string description: Webhook URL you supplied in the request requestId: type: string description: Request ID you can use to retrieve the result ErrorResponse: type: object properties: problemDetail: $ref: '#/components/schemas/ProblemDetail' 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: type: object securitySchemes: bearerAuth: type: http description: >- IDM-issued JWT. Obtain via the IDM authentication flow and pass as: Bearer scheme: bearer bearerFormat: JWT ````