Import from Dropbox

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

How it works

A person connects Dropbox once, in the Playbook web app. Dropbox 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 folders. 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 disconnects Playbook in their Dropbox settings.

Connections belong to a Playbook user

Only the Playbook user who connected Dropbox can use that connection. The API token (or the account signed in to MCP) must belong to that same user, or the connection is missing from the list.

Prerequisites

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

For a Dropbox team account, the connection sees the team folders that account can open.

1. List connections

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

Response:

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

The list also contains Google Drive connections (provider: "google_drive"); use a dropbox one. email is filled in a few seconds after connecting, so it can briefly be null. If there is no dropbox connection, send the user to meta.connect_url to connect Dropbox, 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": "Rq8nW2vK5tLp",
      "folders": ["https://www.dropbox.com/home/Clients/Acme"],
      "board_token": "optional-board-token"
    }
  }'

Field	Required	Description
`source_token`	yes	Token of a `dropbox` connection from the connection list.
`folders`	yes	1–20 Dropbox folders, in any of the formats below. Folders only — files are refused.
`board_token`	no	Board to import into. Omit it to create a new top-level board named `Dropbox import (dd-mm-yyyy)`.

A folder can be given as:

The URL from the Dropbox address bar while the folder is open. A personal account shows https://www.dropbox.com/home/Clients/Acme; a member of a Dropbox team sees https://www.dropbox.com/work/Team%20Folder/Clients instead. Both work.
Its path, e.g. /Clients/Acme.
Its Dropbox ID, e.g. id:a4ayc_80_OEAAAAAAAAAXw.

Shared links (https://www.dropbox.com/scl/fo/…) are not supported and are refused with a 422: open the folder in Dropbox and use the address-bar URL or path instead. The Dropbox root cannot be imported as a whole; pass its folders.

Paths are read in the account's own root: for a team member that is the team space, so /Team Folder/Clients and the member's own folder (/Jane Doe/Drafts) both resolve, exactly as the address-bar URL spells them.

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

Each folder is checked against the connected Dropbox account before anything starts, so a folder the account cannot find 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-22T10: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 Dropbox rate limiting.
- oauth_credential_deleted — the Dropbox 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 — compared by Dropbox's content hash — are counted as skipped and not downloaded again; new files are imported. files.completed is therefore what the run added.

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

Files changed in Dropbox. 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 Dropbox folder — or its sub-board in Playbook — imports that folder again in full into a new sub-board.
Files moved to another board, or given a new version in Playbook. Skipping only applies to files still in the sub-board they were imported into, unchanged. Such files are imported again.
Files first imported before this skipping shipped are downloaded again on every re-sync. The copies are usually merged away by duplicate detection, but a workspace that turned duplicate merging off, or an asset kept inside a group, ends up with real duplicates. Import into a new board once to get skipping for them.

Files deleted from Dropbox 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 Dropbox folder URL, path or ID; a shared link; the Dropbox root; folder not found in the connected Dropbox 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	Dropbox is rate limiting the connection. Retry after the `Retry-After` header's seconds.
502	Dropbox returned another error; the message has Dropbox's text.

Using it from an AI assistant

The MCP server exposes the same flow as list_import_sources, import_from_dropbox, and get_import. Ask your assistant something like "Import the Dropbox folder /Clients/Acme 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​