Import from Google Drive

Pull files from Google Drive — including private folders and shared drives — into a Playbook board without clicking through the web app. Useful when creators keep dropping content into Drive and an agent or script should bring it into Playbook on a schedule.

How it works

A person connects Google Drive once, in the Playbook web app. Google requires this consent step in a browser, so there is no API call or MCP tool for it.
Your script or agent lists that connection and gets its token.
It starts an import with one or more folder URLs. Each folder becomes a sub-board, named after the folder, inside the board you import into; its sub-folders are nested below.
It polls the import until it finishes.

After step 1, nothing else is manual. The connection keeps working until someone revokes Playbook's access in their Google account.

Connections belong to a Playbook user

Only the Playbook user who connected Google Drive can use that connection. The API token (or the account signed in to MCP) must belong to that same user, or the connection list comes back empty.

Prerequisites

Access token: an API token with the write scope, belonging to a workspace owner or admin.
Organization Slug: your workspace identifier.
Google Drive connected by the same Playbook user: in Playbook, open Apps in the sidebar, click Google Drive under Sync integrations, and sign in with a Google account that can see the folders. You can close the folder picker that opens afterwards — the connection is already saved.

The Google account needs access to the folders you import. If creators upload to their own Drive, have them share the folder with that account.

1. List connections

curl "https://api.playbook.com/v1/my-org/imports/sources" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "data": [
    {
      "token": "Hk3vT9pQ2mX8",
      "provider": "google_drive",
      "email": "[email protected]",
      "created_at": "2026-09-14T10:12:03Z"
    }
  ],
  "meta": {
    "connect_url": "https://www.playbook.com/my-org/new-app"
  }
}

email is filled in a few seconds after connecting, so it can briefly be null. If data is empty, send the user to meta.connect_url to connect Google Drive, then list again.

2. Start an import

curl -X POST "https://api.playbook.com/v1/my-org/imports" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "import": {
      "source_token": "Hk3vT9pQ2mX8",
      "folders": ["https://drive.google.com/drive/folders/1AbCdEfGhIjKlMnOp"],
      "board_token": "optional-board-token"
    }
  }'

Field	Required	Description
`source_token`	yes	Token from the connection list.
`folders`	yes	1–20 Google Drive folder URLs or folder IDs. Folders only — file URLs are refused.
`board_token`	no	Board to import into. Omit it to create a new top-level board named `Google Drive import (dd-mm-yyyy)`.

Files do not land in board_token itself: importing the Drive folder Creators into the board Content puts them in Content / Creators. List that sub-board with the board children endpoint.

Each folder is checked against the connected Google account before anything starts, so a folder the account cannot see fails right away with a 422 naming that account.

Response:

{
  "data": {
    "token": "q7Wm2LkP9sRt",
    "status": "pending",
    "cancel_reason": null,
    "scanning": true,
    "board_token": "b8Jd3KxQ1vNz",
    "pending_folders": 0,
    "files": { "total": 0, "pending": 0, "completed": 0, "skipped": 0, "failed": 0 },
    "created_at": "2026-09-14T10:15:00Z",
    "started_at": null,
    "completed_at": null,
    "canceled_at": null
  }
}

Keep board_token if you plan to re-sync the same folder later.

3. Poll the import

curl "https://api.playbook.com/v1/my-org/imports/q7Wm2LkP9sRt" \
  -H "Authorization: Bearer YOUR_TOKEN"

status moves from pending to active to one of two final states:

completed — every file was imported or skipped.
canceled — see cancel_reason:
- incomplete — some files or folders failed (files.failed).
- overlimit — the workspace ran out of storage or assets, or the next file would have crossed into storage overage the workspace has not agreed to. Nothing past that point was stored.
- failed_to_start — the import could not start after retrying, for example under sustained Google rate limiting.
- oauth_credential_deleted — the Google Drive connection was removed while importing.
- target_collection_deleted — the board was deleted while importing.
- blocked — the import was blocked by an admin.

scanning is true while folders are still being listed, so files.total keeps growing until it turns false. Poll every 15–30 seconds; large folders take a while.

Re-syncing a folder

Import the same folder into the same board_token again to pick up what creators added since the last run. Files already there and unchanged are counted as skipped and not downloaded again; new files are imported.

This is not a mirror of the folder. Things that produce duplicates:

Files changed in Drive. The new version is added as a second asset next to the old one; the old asset is not updated or removed.
Renamed folders. Sub-boards are matched by name, so renaming a Drive folder — or its sub-board in Playbook — imports that folder again in full into a new sub-board.
Files moved to another board. Skipping only applies to files still in the sub-board they were imported into. Moved files are imported again.
Google Docs, Sheets, and Slides have no checksum, so they are added again as links on every run.

Files deleted from Drive stay in Playbook.

Limits

One active import per workspace on plans without unrestricted imports. The refusal names the active import's token, so a client whose earlier start request timed out can poll that import instead of starting another.
An API import never bills storage overage the workspace has not agreed to. Overage cannot be confirmed through the API. A start request is refused when the workspace has no storage left before that level, and a running import is canceled with overlimit before storing the file that would cross it — files imported up to then are kept. To import more, agree to the overage in the web app first.
Plan limits on import size and asset counts apply exactly as they do in the web app.

Errors

Status	When
403	The token's user is not a workspace owner or admin, or the token lacks the `write` scope.
404	`source_token` is not one of this user's connections, or `board_token` is not a board in the workspace (deleted boards included).
406	The `import` object or `source_token` is missing.
422	Not a folder URL or ID; folder not visible to the connected Google account; a file instead of a folder; connection no longer authorized (reconnect at `connect_url`); another import active (the message names it); storage or asset limit reached; no storage left before unconsented overage.
429	Google is rate limiting the connection. Retry after the `Retry-After` header's seconds.
502	Google Drive returned another error, e.g. a Google Workspace policy blocking access; the message has Google's text.

Using it from an AI assistant

The MCP server exposes the same flow as list_import_sources, import_from_google_drive, and get_import. Ask your assistant something like "Import the Drive folder https://drive.google.com/drive/folders/… into the Creator Content board, then tag the new files" — it lists the connection, starts the import, polls until it finishes, and finds the files in the sub-board named after the folder.

How it works​

Prerequisites​

1. List connections​

2. Start an import​

3. Poll the import​

Re-syncing a folder​

Limits​

Errors​

Using it from an AI assistant​

Related API Endpoints​