> ## 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. # Upload xliff content asynchronously > Upload translated XLIFF back to Contentful. The connector parses the XLIFF, maps target-language segments back onto the original entries, and writes them to the target locale in the configured space. **Async variant.** Returns immediately with `{ requestId, webHookUrl }`. The upload result is POSTed to the URL supplied in `X-Webhook`. `X-Webhook` is required. ## OpenAPI ````yaml /openapi/phrase-connectors.json post /contentful2/v1/async/upload-xliff-file 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/upload-xliff-file: post: tags: - Contentful summary: Upload xliff content asynchronously description: >- Upload translated XLIFF back to Contentful. The connector parses the XLIFF, maps target-language segments back onto the original entries, and writes them to the target locale in the configured space. **Async variant.** Returns immediately with `{ requestId, webHookUrl }`. The upload result is POSTed to the URL supplied in `X-Webhook`. `X-Webhook` is required. operationId: uploadXliffContentAsync_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-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/Contentful2UploadXliffFileApiBody' examples: Upload translated XLIFF: description: Upload translated XLIFF value: connectorUuid: 4282fec0-d2e9-4266-8733-3e634feb7b59 configuration: tags: - translate-me includeReferences: true path: pathType: ROOT targetLocale: de-DE storageId: e48eda63928c4155bez9fdbsaadc15f3 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: Contentful2UploadXliffFileApiBody: required: - configuration - connectorUuid - storageId type: object properties: connectorUuid: type: string description: UUID of a connector instance configured in TMS. example: 4282fec0-d2e9-4266-8733-3e634feb7b59 configuration: $ref: '#/components/schemas/Contentful2ConfigurationDto' path: $ref: '#/components/schemas/WebApiContentful2PathDto' targetLocale: type: string description: Target locale to write into (Contentful locale code). nullable: true example: de-DE storageId: type: string description: >- Storage ID of the translated XLIFF file (already uploaded to Phrase file storage). example: e48eda63928c4155bez9fdbsaadc15f3 description: >- Request body for uploading translated XLIFF back to Contentful. Reference the stored XLIFF by `storageId`; the connector parses it and writes the target-locale segments to Contentful. 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' Contentful2ConfigurationDto: type: object properties: tags: type: array items: type: string tagFilterListingStrategy: type: string enum: - WITH_ALL_TAGS - WITH_AT_LEAST_ONE_TAG fieldsToOmit: type: array items: type: string followAliases: type: boolean includeReferences: type: boolean includeReferencesInChangeDetection: type: boolean includeAssets: type: boolean useApp: type: boolean includeTaxonomy: type: boolean organizationId: type: string middlemanTargetLocales: type: array items: type: string filters: $ref: '#/components/schemas/Contentful2Filters' doNotResegmentWhenMaxLengthAvailable: type: boolean description: >- Contentful-specific behavior knobs (tag filter, reference inlining, asset handling, …). WebApiContentful2PathDto: required: - pathType type: object properties: pathType: type: string description: >- Selector inside the Contentful space — entry, folder, or ROOT for the entire selection driven by `configuration`. nullable: true discriminator: propertyName: 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: type: object Contentful2Filters: type: object properties: filterEntryByContentType: $ref: '#/components/schemas/FilterEntryByContentType' filterReferencesByFieldId: $ref: '#/components/schemas/FilterReferencesByFieldId' filterReferencesByEntryContentType: $ref: '#/components/schemas/FilterReferencesByEntryContentType' filterReferencesByEntryTag: $ref: '#/components/schemas/FilterReferencesByEntryTag' filterReferencesByDepth: $ref: '#/components/schemas/FilterReferencesByDepth' FilterEntryByContentType: type: object properties: strategy: type: string enum: - DISABLE - EXCLUDE - INCLUDE values: type: array items: type: string FilterReferencesByFieldId: type: object properties: strategy: type: string enum: - DISABLE - EXCLUDE - INCLUDE values: type: array items: type: string FilterReferencesByEntryContentType: type: object properties: strategy: type: string enum: - DISABLE - EXCLUDE values: type: array items: type: string FilterReferencesByEntryTag: type: object properties: strategy: type: string enum: - DISABLE - EXCLUDE - INCLUDE values: type: array items: type: string FilterReferencesByDepth: type: object properties: value: type: integer format: int32 securitySchemes: bearerAuth: type: http description: >- IDM-issued JWT. Obtain via the IDM authentication flow and pass as: Bearer scheme: bearer bearerFormat: JWT ````