> ## 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 raw content from Google Drive synchronously > Download a raw binary file from Google Drive without any connector-side conversion. The returned payload is the original file bytes as stored in Drive (Docs/Sheets/Slides are exported as their native binary equivalents when applicable). Use this when you need the source artefact intact (e.g. PDF, DOCX, image, video). Google Drive is a binary-file connector — there is no XLIFF or raw-to-XLIFF conversion endpoint. **Choosing sync vs async** - `/sync/download-raw-file` blocks until the connector finishes. Use for small files and interactive callers. Subject to gateway timeouts (~60 s). - `/async/download-raw-file` returns immediately with a `requestId` and posts the result to the URL in `X-Webhook` when ready. Required for large files. **Response shape (sync only)** is controlled by `X-ResponseType`: - `ID` (default) — JSON `{ "storageId": "..." }`. The caller fetches the content from Phrase file storage later. Recommended for any non-trivial payload. - `OBJECT` — raw `application/octet-stream`. Faster for small payloads; the stream may be proxied directly from Drive with upstream `Content-Type`, `Content-Disposition`, and `Content-Length` headers preserved when available. **Response shape (this endpoint)** is controlled by the `X-ResponseType` request header: - `ID`: returns JSON with a `storageId` referencing file storage (`application/json`) - `OBJECT`: returns a binary stream (`application/octet-stream`). Two variants: - Streaming: proxied stream from the connector; status and headers (`Content-Type`, `Content-Disposition`, `Content-Length`) may come from upstream when present. - File storage: Bifrost downloads from storage (single file or zip of multiple files) and returns `application/octet-stream` with `Content-Disposition: attachment; filename=""`. ## OpenAPI ````yaml /openapi/phrase-connectors.json post /google-drive/v1/sync/download-raw-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: /google-drive/v1/sync/download-raw-file: post: tags: - Google Drive summary: Download raw content from Google Drive synchronously description: >- Download a raw binary file from Google Drive without any connector-side conversion. The returned payload is the original file bytes as stored in Drive (Docs/Sheets/Slides are exported as their native binary equivalents when applicable). Use this when you need the source artefact intact (e.g. PDF, DOCX, image, video). Google Drive is a binary-file connector — there is no XLIFF or raw-to-XLIFF conversion endpoint. **Choosing sync vs async** - `/sync/download-raw-file` blocks until the connector finishes. Use for small files and interactive callers. Subject to gateway timeouts (~60 s). - `/async/download-raw-file` returns immediately with a `requestId` and posts the result to the URL in `X-Webhook` when ready. Required for large files. **Response shape (sync only)** is controlled by `X-ResponseType`: - `ID` (default) — JSON `{ "storageId": "..." }`. The caller fetches the content from Phrase file storage later. Recommended for any non-trivial payload. - `OBJECT` — raw `application/octet-stream`. Faster for small payloads; the stream may be proxied directly from Drive with upstream `Content-Type`, `Content-Disposition`, and `Content-Length` headers preserved when available. **Response shape (this endpoint)** is controlled by the `X-ResponseType` request header: - `ID`: returns JSON with a `storageId` referencing file storage (`application/json`) - `OBJECT`: returns a binary stream (`application/octet-stream`). Two variants: - Streaming: proxied stream from the connector; status and headers (`Content-Type`, `Content-Disposition`, `Content-Length`) may come from upstream when present. - File storage: Bifrost downloads from storage (single file or zip of multiple files) and returns `application/octet-stream` with `Content-Disposition: attachment; filename=""`. operationId: downloadRawContentSync_2 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. (ID => JSON with storageId, OBJECT => binary stream). required: false schema: type: string enum: - ID - OBJECT requestBody: content: application/json: schema: $ref: '#/components/schemas/GoogleDrive2DownloadRawFileApiBody' examples: Stored credentials: description: Stored credentials value: connectorUuid: 4282fec0-d2e9-4266-8733-3e634feb7b59 configuration: {} path: pathType: FILE fileId: 1A2b3C4d5E6f7G8h9I0jK name: report.pdf drive: driveType: MY_DRIVE parentChain: - id: root name: My Drive required: true responses: '200': description: >- OK (binary stream when X-ResponseType=OBJECT). Streaming may proxy upstream status/headers. headers: Content-Disposition: description: >- Streaming: may be provided by upstream RemoteStream. File storage: attachment; filename="". style: simple schema: type: string Content-Length: description: File size in bytes when known (streaming only). style: simple schema: type: integer format: int64 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-Type: description: >- Streaming: proxied from upstream; file storage: application/octet-stream. style: simple schema: type: string content: application/octet-stream: schema: type: string description: Binary file stream. format: binary '400': description: Bad Request (workflow returned ErrorResponse) 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/ErrorResponse' components: schemas: GoogleDrive2DownloadRawFileApiBody: required: - configuration - connectorUuid type: object properties: connectorUuid: type: string description: > UUID of a configured connector that holds stored Google Drive credentials. example: b9c06f76-4a44-4d2e-8a26-3d1e4b47e123 configuration: $ref: '#/components/schemas/GoogleDrive2ConfigurationDto' path: $ref: '#/components/schemas/WebApiGoogleDrive2PathDto' locale: type: string description: > Locale code associated with the file content, if applicable. Optional. Use a BCP 47 or Phrase locale code (for example, "en", "de", "cs"). example: en description: > Request payload for downloading a raw file from Google Drive through the connector. Clients authenticate by referencing a stored connector via connectorUuid. The path describes which file or location to download from. ErrorResponse: type: object properties: problemDetail: $ref: '#/components/schemas/ProblemDetail' GoogleDrive2ConfigurationDto: type: object description: > Connector configuration for the Google Drive connector. Currently no configuration options are exposed. The object is reserved for future configuration flags while keeping the API contract stable. example: {} WebApiGoogleDrive2PathDto: required: - pathType type: object properties: pathType: type: string description: > Polymorphic description of a Google Drive location used by connector operations. The pathType discriminator selects the concrete shape: - ROOT - connector entry listing available spaces - SHARED_DRIVES_ROOT - virtual root listing shared drives - FOLDER - real folder or drive root - FILE - real file under a folder nullable: true discriminator: propertyName: pathType oneOf: - $ref: '#/components/schemas/RootPathDto' - $ref: '#/components/schemas/SharedDrivesRootPathDto' - $ref: '#/components/schemas/FolderPathDto' - $ref: '#/components/schemas/FilePathDto' 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 RootPathDto: type: object allOf: - $ref: '#/components/schemas/WebApiBrazeMultilangPathDto' - type: object properties: pathType: type: string enum: - ROOT - EMAIL_TEMPLATE_DIRECTORY - CAMPAIGN_DIRECTORY - CANVAS_DIRECTORY - CONTENT_BLOCK_DIRECTORY - EMAIL_TEMPLATE - CAMPAIGN - CANVAS - CONTENT_BLOCK SharedDrivesRootPathDto: required: - pathType type: object description: > Virtual root representing the "Shared drives" collection. Listing this path enumerates shared drives accessible to the authenticated user. Each shared drive is then exposed as a FolderPath scoped by a SharedDriveRef. This is a connector-level abstraction, not a native Google Drive resource. allOf: - $ref: '#/components/schemas/WebApiGoogleDrive2PathDto' - type: object properties: pathType: type: string description: > Concrete shape of a Google Drive path DTO. The value is serialized as "pathType" and used to choose the correct path representation during deserialization. example: SHARED_DRIVES_ROOT enum: - ROOT - FOLDER - FILE - SHARED_DRIVES_ROOT FolderPathDto: required: - drive - parentChain - pathType type: object description: > Resolved folder location within a Google Drive space. Represents both "My Drive" folders and shared drive folders. The folderId identifies the folder in its drive. The parentChain lists real ancestors from the drive root to the folder's direct parent. allOf: - $ref: '#/components/schemas/WebApiGoogleDrive2PathDto' - type: object properties: folderId: type: string description: > Google Drive folder identifier. For "My Drive", the root folder uses id "root". For shared drives, the root folder typically uses the shared drive id. Required for listing or downloading existing folders. May be null when the connector is expected to create the folder during an export workflow. nullable: true example: root name: type: string description: | Human-readable display name of the folder. Optional and not guaranteed to be unique under a given parent. nullable: true example: Marketing drive: $ref: '#/components/schemas/DriveRefDto' parentChain: type: array description: > Ordered chain of parent folders from the drive root down to the direct parent of this folder. The folder itself is not included. For read-only workflows, each parent should have a non-empty id so that the connector can reconstruct the full location without additional discovery. items: $ref: '#/components/schemas/ParentRefDto' pathType: type: string description: > Concrete shape of a Google Drive path DTO. The value is serialized as "pathType" and used to choose the correct path representation during deserialization. example: FOLDER enum: - ROOT - FOLDER - FILE - SHARED_DRIVES_ROOT FilePathDto: required: - drive - parentChain - pathType type: object description: > Resolved file location inside a specific Google Drive space. Captures drive scope, the ordered chain of parent folders, and the file identifier. For read-only workflows, fileId and all parent ids should be resolved. For export workflows, fileId may be null when creating a new file. allOf: - $ref: '#/components/schemas/WebApiGoogleDrive2PathDto' - type: object properties: fileId: type: string description: > Google Drive file identifier, when known. Required for listing or downloading existing files. May be null when the connector is expected to create a new file in the target folder. nullable: true example: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms name: type: string description: | Human-readable display name of the file. Optional and not guaranteed to be unique within a folder. nullable: true example: welcome-email.docx drive: $ref: '#/components/schemas/DriveRefDto' parentChain: type: array description: > Ordered chain of parent folders from the drive root down to the direct parent of the file. The file itself is not included. For read-only workflows, each parent should have a non-empty id so that the connector can reconstruct the full location without additional discovery. items: $ref: '#/components/schemas/ParentRefDto' pathType: type: string description: > Concrete shape of a Google Drive path DTO. The value is serialized as "pathType" and used to choose the correct path representation during deserialization. example: FILE enum: - ROOT - FOLDER - FILE - SHARED_DRIVES_ROOT WebApiBrazeMultilangPathDto: required: - pathType type: object properties: pathType: type: string description: >- Selector inside the Braze workspace — content block / campaign ID, or ROOT for the entire selection driven by `configuration`. discriminator: propertyName: pathType DriveRefDto: required: - driveType type: object properties: driveType: type: string description: > Drive scope that Google Drive operations should target. The driveType discriminator determines whether the path refers to the authenticated user's "My Drive" space or to a specific shared drive. discriminator: propertyName: driveType oneOf: - $ref: '#/components/schemas/MyDriveRefDto' - $ref: '#/components/schemas/SharedDriveRefDto' ParentRefDto: required: - name type: object properties: id: type: string description: > Google Drive identifier of the parent folder, when known. Required for read-only workflows that must address existing folders without additional discovery. May be null when folders are created or resolved by name. nullable: true example: 0AOpExampleParentIdUk9PVA name: type: string description: | Human-readable display name of the parent folder. Required and never blank. example: Projects description: > Descriptor for a parent folder in a Google Drive location hierarchy. Entries are ordered from the drive root to the direct parent of the leaf resource. This allows clients to reconstruct human-readable paths and understand where a file or folder lives. MyDriveRefDto: type: object description: > Drive reference that scopes operations to the authenticated user's "My Drive". The actual Google account is derived from the OAuth credentials; no additional identifiers are required. example: driveType: MY_DRIVE allOf: - $ref: '#/components/schemas/DriveRefDto' SharedDriveRefDto: required: - driveId type: object description: > Drive reference that scopes operations to a specific shared drive. The driveId is the immutable identifier returned by the Google Drive API and remains stable even if the shared drive is renamed. allOf: - $ref: '#/components/schemas/DriveRefDto' - type: object properties: driveId: type: string description: | Google Drive shared drive identifier. Non-empty, stable id returned by the Drive API. example: 0AOpExampleDriveIdUk9PVA securitySchemes: bearerAuth: type: http description: >- IDM-issued JWT. Obtain via the IDM authentication flow and pass as: Bearer scheme: bearer bearerFormat: JWT ````