> ## 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. # Move a file synchronously > Move one file to another folder in Google Drive. This is a strict relocation: the same file (same `fileId`, same name) ends up in the destination folder. It is never replaced by a copy or an upload, and no other file is overwritten, replaced or deleted. A file with the same name that is already in the destination does not block the move. **Source.** `source` is the file together with where you expect it to be: the last element of `source.parentChain` is its direct parent (with an `id`, as returned by `list-files`; an empty chain means the drive root). Only that parent is removed. **Destination.** `destination` is a folder. With `folderId` that folder is used. Without it, `name` is required and the folder is resolved like the target of `upload-raw-file`: parents with an `id` are used, named parents are looked up by name, and a missing named folder is created, but only when the file is actually going to be moved. With several folders of the same name, the oldest (creation time, then id) is used. **Scope.** Files only, within My Drive or within one shared drive. A folder as the source or a destination in another drive is rejected with `MOVE_UNSUPPORTED` before anything is changed. **Outcomes.** - The file is in the expected parent: it is moved. The response is its new `path`. - The file is already in the destination, or source and destination are the same folder: the request succeeds without any change and returns the current `path`. - The file is somewhere else: `MOVE_SOURCE_NOT_AT_EXPECTED_LOCATION`, nothing is changed and no folder is created. **Errors.** Failures use the common error model. These `errorCode` values are stable: - `MOVE_SOURCE_NOT_AT_EXPECTED_LOCATION` — the file is in neither the expected parent nor the destination - `MOVE_SOURCE_NOT_FOUND` — the file is missing, trashed, or not accessible to this connection - `MOVE_UNSUPPORTED` — a folder, or a move between different drives - `MOVE_DESTINATION_INVALID` — the destination is not an accessible folder - `MOVE_OUTCOME_UNCONFIRMED` — the write was sent to Google Drive but Drive did not answer, so it is unknown whether the file moved. This is an answer you do receive (HTTP 502); it is different from receiving no response or no webhook at all (see below) Google Drive failures are reported by cause (permissions, quota and rate limits, provider errors); they do not ask for re-authentication unless the token is really rejected. **Unknown outcome, and no automatic retry.** A move, or the creation of a destination folder, is never repeated automatically, neither by Bifrost nor by the connector. The outcome can be unknown in two different ways: - You receive `MOVE_OUTCOME_UNCONFIRMED`. The connector did send the write to Google Drive, but Drive did not answer it. The file may or may not have moved, and a folder may or may not have been created. - You receive no response (a timeout) or, for async, no webhook. You have learned nothing: the request may not have reached Google Drive, the move may be complete, or the result may have been lost on the way. In both cases check the file before you repeat the request. A repeated request confirms success only when the original file is found in the destination; if the file is still in the expected parent it is moved, otherwise you get `MOVE_SOURCE_NOT_AT_EXPECTED_LOCATION`. **Async.** Accepting an async request is not a completed move. The result is POSTed once to `X-Webhook`, the same success body or the same error as the sync variant. Bifrost does not retry the webhook and offers no status polling for this operation, so use your own deadline. ## OpenAPI ````yaml /openapi/phrase-connectors.json post /google-drive/v1/sync/move-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: /google-drive/v1/sync/move-file: post: tags: - Google Drive summary: Move a file synchronously description: > Move one file to another folder in Google Drive. This is a strict relocation: the same file (same `fileId`, same name) ends up in the destination folder. It is never replaced by a copy or an upload, and no other file is overwritten, replaced or deleted. A file with the same name that is already in the destination does not block the move. **Source.** `source` is the file together with where you expect it to be: the last element of `source.parentChain` is its direct parent (with an `id`, as returned by `list-files`; an empty chain means the drive root). Only that parent is removed. **Destination.** `destination` is a folder. With `folderId` that folder is used. Without it, `name` is required and the folder is resolved like the target of `upload-raw-file`: parents with an `id` are used, named parents are looked up by name, and a missing named folder is created, but only when the file is actually going to be moved. With several folders of the same name, the oldest (creation time, then id) is used. **Scope.** Files only, within My Drive or within one shared drive. A folder as the source or a destination in another drive is rejected with `MOVE_UNSUPPORTED` before anything is changed. **Outcomes.** - The file is in the expected parent: it is moved. The response is its new `path`. - The file is already in the destination, or source and destination are the same folder: the request succeeds without any change and returns the current `path`. - The file is somewhere else: `MOVE_SOURCE_NOT_AT_EXPECTED_LOCATION`, nothing is changed and no folder is created. **Errors.** Failures use the common error model. These `errorCode` values are stable: - `MOVE_SOURCE_NOT_AT_EXPECTED_LOCATION` — the file is in neither the expected parent nor the destination - `MOVE_SOURCE_NOT_FOUND` — the file is missing, trashed, or not accessible to this connection - `MOVE_UNSUPPORTED` — a folder, or a move between different drives - `MOVE_DESTINATION_INVALID` — the destination is not an accessible folder - `MOVE_OUTCOME_UNCONFIRMED` — the write was sent to Google Drive but Drive did not answer, so it is unknown whether the file moved. This is an answer you do receive (HTTP 502); it is different from receiving no response or no webhook at all (see below) Google Drive failures are reported by cause (permissions, quota and rate limits, provider errors); they do not ask for re-authentication unless the token is really rejected. **Unknown outcome, and no automatic retry.** A move, or the creation of a destination folder, is never repeated automatically, neither by Bifrost nor by the connector. The outcome can be unknown in two different ways: - You receive `MOVE_OUTCOME_UNCONFIRMED`. The connector did send the write to Google Drive, but Drive did not answer it. The file may or may not have moved, and a folder may or may not have been created. - You receive no response (a timeout) or, for async, no webhook. You have learned nothing: the request may not have reached Google Drive, the move may be complete, or the result may have been lost on the way. In both cases check the file before you repeat the request. A repeated request confirms success only when the original file is found in the destination; if the file is still in the expected parent it is moved, otherwise you get `MOVE_SOURCE_NOT_AT_EXPECTED_LOCATION`. **Async.** Accepting an async request is not a completed move. The result is POSTed once to `X-Webhook`, the same success body or the same error as the sync variant. Bifrost does not retry the webhook and offers no status polling for this operation, so use your own deadline. operationId: googleDriveMoveFileSync 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 requestBody: content: application/json: schema: $ref: '#/components/schemas/GoogleDrive2MoveFileApiBody' additionalProperties: default: '' default: '' examples: Move to a folder by name: description: Move to a folder by name value: connectorUuid: 4282fec0-d2e9-4266-8733-3e634feb7b59 configuration: {} source: pathType: FILE fileId: 1A2b3C4d5E6f7G8h9I0jK name: report.pdf drive: driveType: MY_DRIVE parentChain: - id: root name: My Drive - id: 0B7_inbox name: inbox destination: pathType: FOLDER name: processed drive: driveType: MY_DRIVE parentChain: - id: root name: My Drive - id: 0B7_inbox name: inbox 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: array contains: default: '' items: default: '' unevaluatedItems: default: '' content: application/json: schema: $ref: '#/components/schemas/FilePathDto' additionalProperties: default: '' default: '' examples: Moved file: description: Moved file value: pathType: FILE fileId: 1A2b3C4d5E6f7G8h9I0jK name: report.pdf drive: driveType: MY_DRIVE parentChain: - id: root name: My Drive - id: 0B7_inbox name: inbox - id: 0B7_processed name: processed default: description: > Bad request or upstream failure. Returns an `ErrorResponse` body. See the API overview's "Error model" section for the HTTP status to 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: GoogleDrive2MoveFileApiBody: type: object description: > Request payload for moving one Google Drive file to another folder. A move is a strict relocation: the same file (same `fileId`, same name) ends up in the destination folder. It is never replaced by a copy, and no other file is overwritten, replaced or deleted. A file with the same name already in the destination does not block the move. Authentication is provided via connectorUuid. properties: connectorUuid: type: string default: '' description: > UUID of a configured connector that holds stored Google Drive credentials. example: b9c06f76-4a44-4d2e-8a26-3d1e4b47e123 configuration: $ref: '#/components/schemas/GoogleDrive2ConfigurationDto' default: '' description: | Connector configuration for this request. Currently unused, but reserved for future configuration flags. source: $ref: '#/components/schemas/FilePathDto' default: '' description: > The file to move, together with where you expect it to be. `fileId` is required. The last element of `parentChain` must be the file's direct parent, with an `id`, exactly as returned by `list-files` (a file directly in My Drive has the parent `{ "id": "root", "name": "My Drive" }`). An empty `parentChain` means the drive root. `name` is informational: the file keeps its name. The move happens only if the file is in that expected parent. If it is already in the destination folder, the request succeeds without a change. Otherwise the request is rejected with `MOVE_SOURCE_NOT_AT_EXPECTED_LOCATION`. destination: $ref: '#/components/schemas/FolderPathDto' default: '' description: > The folder to move the file into. - With `folderId`, that folder is used directly. It must be an accessible folder. - Without `folderId`, `name` is required. `parentChain` and `name` are resolved like the target of `upload-raw-file`: parents with an `id` are used directly, named parents are looked up by name, and a missing named folder is created (only when the file is actually going to be moved). When several folders have the same name, the oldest one (by creation time, then by id) is used. The destination must be in the same drive as the file: My Drive, or the same shared drive. A destination in another drive is rejected with `MOVE_UNSUPPORTED`. required: - connectorUuid - destination - source FilePathDto: 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. properties: pathType: type: string default: '' description: | Shape discriminator for this path. Must be FILE for this DTO. enum: - FILE example: FILE fileId: type: - string - 'null' default: '' 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. example: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms name: type: - string - 'null' default: '' description: | Human-readable display name of the file. Optional and not guaranteed to be unique within a folder. example: welcome-email.docx drive: $ref: '#/components/schemas/DriveRefDto' default: '' description: | Drive scope for this path. - MY_DRIVE - the authenticated user's "My Drive" - SHARED_DRIVE - a specific shared drive identified by driveId parentChain: type: array default: '' 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' required: - drive - parentChain - pathType ErrorResponse: type: object properties: problemDetail: $ref: '#/components/schemas/ProblemDetail' GoogleDrive2ConfigurationDto: 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: {} FolderPathDto: 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. properties: pathType: type: string default: '' enum: - FOLDER example: FOLDER folderId: type: - string - 'null' default: '' 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. example: root name: type: - string - 'null' default: '' description: | Human-readable display name of the folder. Optional and not guaranteed to be unique under a given parent. example: Marketing drive: $ref: '#/components/schemas/DriveRefDto' default: '' description: | Drive scope for this folder. - MY_DRIVE - the authenticated user's "My Drive" - SHARED_DRIVE - a specific shared drive identified by driveId parentChain: type: array default: '' 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' owner: type: string repo: type: string branch: type: string location: type: string required: - drive - parentChain - pathType DriveRefDto: 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 mapping: MY_DRIVE: '#/components/schemas/MyDriveRefDto' SHARED_DRIVE: '#/components/schemas/SharedDriveRefDto' oneOf: - $ref: '#/components/schemas/MyDriveRefDto' - $ref: '#/components/schemas/SharedDriveRefDto' properties: driveType: type: string required: - driveType ParentRefDto: type: object 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. properties: id: type: - string - 'null' default: '' 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. example: 0AOpExampleParentIdUk9PVA name: type: string default: '' description: | Human-readable display name of the parent folder. Required and never blank. example: Projects required: - name 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 MyDriveRefDto: 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 properties: driveType: type: string required: - driveType SharedDriveRefDto: 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. properties: driveType: type: string driveId: type: string default: '' description: | Google Drive shared drive identifier. Non-empty, stable id returned by the Drive API. example: 0AOpExampleDriveIdUk9PVA required: - driveId - driveType 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.