Dropbox ExecModule

Overview

DropboxModule connects ValkyrAI workflows to Dropbox API v2 for account identity, file and folder metadata, search, bounded upload/download, organization, deletion, and shared-link creation. It uses the native map I/O ExecModule ABI, is annotation-discoverable as DropboxModule, and resolves its OAuth access token only from a READY IntegrationAccount.

The operation set follows the most useful file, folder, and search behavior in n8n's Dropbox node while adding ValkyrAI's trusted-host boundary, explicit destructive acknowledgements, bounded payloads, safe-read retries, stable errors, and credential redaction:

• get_current_account
• list_folder
• get_metadata
• search
• download_file
• upload_file
• create_folder
• copy_path
• move_path
• delete_path
• create_shared_link

Workflow input cannot override the Dropbox API origins or authentication headers.

Usage

1. Create a Dropbox scoped app with App folder or Full Dropbox access according to the workflow boundary.
2. Enable only the OAuth scopes required by the selected operations.
3. Complete OAuth authorization and store the current access token in the encrypted apiKey field of a ValkyrAI IntegrationAccount.
4. Set the account status to READY and bind it through ExecModuleConfig.authConfig.integrationAccount.
5. Add DropboxModule, select one operation, and map the operation-specific fields from configuration or upstream state.
6. For destructive or externally visible actions, provide the documented acknowledgement immediately before execution.

Mapped inputs can override non-secret operation parameters. Credentials, API hosts, timeout policy, and retry policy remain trusted application configuration.

Inputs

Name	Type	Requirement	Default	Description and constraints
operation	string	Required	None	One of the eleven operations above.
path	string	Required except get_current_account; optional root for list/search	Empty root for list/search	Absolute Dropbox path without a trailing slash. Read/delete/copy/move/share operations also accept provider id: references. Maximum 4,096 characters; control characters are rejected.
destinationPath	string	Required for copy/move	None	Absolute Dropbox destination path, different from path.
query	string	Required for search	None	1–1,000 safe characters.
cursor	string	Optional for list/search	None	Opaque continuation cursor from a previous response. Maximum 8,192 characters; never inspect or alter it.
recursive	boolean	Optional for list	false	Include all descendants. Large trees remain capped by limit.
includeDeleted	boolean	Optional for list/search	false	Include deleted list entries or search only deleted items.
includeMountedFolders	boolean	Optional for list	true	Include mounted app, shared, and team folders.
includeNonDownloadableFiles	boolean	Optional for list	true	Include provider-native entries that cannot be downloaded through the content endpoint.
limit	integer	Optional for list/search	100	Total returned items, 1–10,000. Provider requests are capped at 2,000 list entries or 1,000 search matches per page.
maxDownloadBytes	integer	Optional for download	10485760	Maximum response bytes, 1–52,428,800. Oversized content is rejected rather than partially emitted.
contentText	string	Conditional for upload	None	UTF-8 content. Exactly one of contentText or contentBase64; empty text is valid.
contentBase64	string	Conditional for upload	None	Base64 content. Maximum 5 MiB after decoding.
mode	string	Optional for upload	add	add, overwrite, or update.
revision	string	Required when mode=update	None	Dropbox revision token, 1–256 safe token characters.
autorename	boolean	Optional for upload/create/copy/move	false	Ask Dropbox to choose a non-conflicting destination name.
mute	boolean	Optional for upload	false	Suppress provider notifications for the write where supported.
strictConflict	boolean	Optional for upload	false	Enable strict Dropbox write-conflict behavior.
confirmOverwrite	boolean	Required for overwrite upload	false	Must be true because the operation can replace existing content.
confirmDelete	boolean	Required for delete	false	Must be true immediately before delete_path.
confirmSharedLink	boolean	Required for shared link creation	false	Must be true because the operation creates an externally usable access path.
requestedVisibility	string	Optional for shared link	public	public or team_only; the provider and team policy may narrow the result.
allowDownload	boolean	Optional for shared link	true	Request whether link recipients can download.

Outputs

Every execution returns status, operation, and attempts.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
attempts	integer	Always	Provider HTTP attempts, including followed list/search pages.
httpStatus	integer	Provider response received	Last Dropbox HTTP status.
data	object	Single-resource and download success	Provider metadata, account, write, or shared-link result normalized to JSON-compatible values.
id	string	Provider result contains one	Convenience Dropbox resource ID.
name	string	Provider result contains one	Convenience file/folder name.
path_display	string	Provider result contains one	Provider-cased display path.
url	string	Shared-link success	Created Dropbox shared-link URL.
items	array	List/search success	Bounded provider entries or search matches.
count	integer	List/search success	Number of returned items.
hasMore	boolean	List/search success	Whether Dropbox reports another page.
cursor	string	Provider supplies one	Opaque cursor for later continuation or reconciliation.
contentBytes	integer	Download success	Downloaded byte count.
contentBase64	string	Download success	Bounded content for binary-aware downstream steps.
mimeType	string	Download success	Provider content type or application/octet-stream.
requestId	string	Dropbox supplies one	x-dropbox-request-id for provider support and diagnostics.
error	object	Failure	Redacted {code, message, httpStatus?, retryable} details.

OAuth tokens never appear in outputs or logs. Provider error text is bounded and passed through the shared workflow sensitive-data policy.

IntegrationAccount Requirements

Setting	Requirement
Provider	Dropbox API v2
Authentication	OAuth 2.0 bearer access token
status	Exactly READY
accountName	Human-readable Dropbox account or team label
apiKey	Preferred encrypted SecureField containing the current access token
password	Legacy access-token fallback only; prefer apiKey
Relationship	ExecModuleConfig.authConfig.integrationAccount

Recommended least-privilege scopes:

• Account identity: account_info.read
• Metadata, list, and search: files.metadata.read
• Download: files.content.read
• Upload, create, copy, move, and delete: files.content.write
• Shared-link creation: sharing.write

Choose App folder access when the workflow needs only its managed subtree. Use Full Dropbox only when business requirements require broader paths. Refresh-token exchange and token rotation belong to the platform authorization lifecycle; never place app secrets, refresh tokens, or access tokens in workflow parameters, input maps, examples, or logs.

Configuration

Illustrative persisted configuration:

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:dropbox-release-artifacts"
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffStrategy": "EXPONENTIAL",
    "initialDelayMs": 1000,
    "maxDelayMs": 60000,
    "jitter": false
  },
  "executionConfig": {
    "timeoutMs": 30000
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_folder\",\"path\":\"/Launch\",\"limit\":250}"
  }
}

The relationship value is symbolic. Persisted workflows use the generated relationship to the encrypted account record.

Operations

Operation	Dropbox API route	Side effect and retry contract
get_current_account	users/get_current_account	Read-only; transient retries allowed.
list_folder	files/list_folder and /continue	Read-only; follows opaque cursors up to limit.
get_metadata	files/get_metadata	Read-only; transient retries allowed.
search	files/search_v2 and /continue_v2	Read-only; follows opaque cursors up to limit.
download_file	content.dropboxapi.com/2/files/download	Read-only bounded binary response; transient retries allowed.
upload_file	content.dropboxapi.com/2/files/upload	Single attempt; overwrite requires acknowledgement.
create_folder	files/create_folder_v2	Single attempt; may create a duplicate after an ambiguous timeout.
copy_path	files/copy_v2	Single attempt; preserves source.
move_path	files/move_v2	Single attempt; changes the source path.
delete_path	files/delete_v2	Single attempt; explicit acknowledgement required.
create_shared_link	sharing/create_shared_link_with_settings	Single attempt; explicit acknowledgement required.

Errors and Failure Modes

Code	Typical cause	Retry guidance
VALIDATION_ERROR	Missing/unsafe path or query, invalid cursor/revision/base64/mode, incompatible content fields, oversized upload, or missing acknowledgement.	Correct inputs; no provider request is sent.
UNSUPPORTED_OPERATION	Unknown operation.	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No secure account relationship is bound.	Bind the intended Dropbox account.
INTEGRATION_ACCOUNT_NOT_READY	Account status is not READY.	Repair or reauthorize the account.
CREDENTIAL_MISSING	No access token is present.	Refresh authorization and store the token in the encrypted field.
DROPBOX_INVALID_ACCESS_TOKEN / HTTP 401	Token is expired, revoked, or invalid.	Refresh the OAuth session.
HTTP 403	App access type, team policy, or scope forbids the action.	Correct app/scopes/team policy; do not broaden access unnecessarily.
DROPBOX_PATH / HTTP 409	Missing path, conflict, revision mismatch, or unsupported path state.	Inspect the bounded provider summary and reconcile current metadata.
HTTP 429	Dropbox rate limit.	Safe reads honor Retry-After and bounded backoff. Writes remain single-attempt.
DOWNLOAD_TOO_LARGE	Content exceeded maxDownloadBytes.	Raise the bounded limit or use an external streaming workflow.
RESPONSE_TOO_LARGE	JSON response exceeded 5 MiB.	Narrow the query/page and retry.
NETWORK_ERROR	Timeout, DNS, TLS, or connectivity failure.	Reads may retry. Reconcile write state before any manual retry.
INVALID_PROVIDER_RESPONSE	List/search response lacks the expected array.	Use requestId and inspect API compatibility.

Dropbox path errors use tagged error_summary values. The module converts the leading tag to a stable error code, redacts credentials, and limits human-readable text to 500 characters.

Example

Upload a Markdown release brief without overwriting an existing file:

{
  "operation": "upload_file",
  "path": "/Launch/release-brief.md",
  "mode": "add",
  "autorename": true,
  "contentText": "# Release brief\n\n- Verify rollout\n- Notify the team"
}

Expected normalized result shape:

{
  "status": "success",
  "operation": "upload_file",
  "attempts": 1,
  "httpStatus": 200,
  "id": "id:example",
  "name": "release-brief.md",
  "path_display": "/Launch/release-brief.md",
  "data": {
    ".tag": "file",
    "id": "id:example",
    "name": "release-brief.md",
    "path_display": "/Launch/release-brief.md",
    "rev": "example-revision"
  }
}

Notes

• Pagination: list_folder and search follow provider cursors until exhaustion or limit. A supplied cursor starts from that continuation endpoint. Cursors are opaque and can expire when provider state changes.
• Rate limits: HTTP 408, 429, 500, 502, 503, and 504 are transient. Only account, metadata, list, search, and download operations retry automatically. Numeric and RFC 1123 Retry-After values are honored within the configured 60-second cap.
• API limits: ValkyrAI caps results at 10,000, uploads at 5 MiB, JSON responses at 5 MiB, downloads at 50 MiB, and request cursors/paths at bounded lengths. Dropbox may enforce stricter plan, namespace, team, or endpoint limits.
• Idempotency: all writes are single-attempt because a timed-out provider call may have committed. mode=add plus autorename=false, update-mode revisions, deterministic destinations, metadata lookup, and cursor/request-ID reconciliation help prevent duplicates.
• Uploads: this release uses the simple /files/upload route. Upload sessions, chunked transfer, and large-file commit are intentionally deferred.
• Downloads: content is base64-encoded for the map ABI. Dropbox Paper or other non-downloadable provider-native entries require an export-capable workflow that is outside this version.
• Destructive behavior: delete_path can remove a file or an entire folder tree and requires confirmDelete=true. Dropbox may retain deleted content for a plan-defined recovery period, but recovery is not guaranteed by this module. move_path and overwrite uploads can also disrupt downstream links or revisions.
• Sharing: create_shared_link requires confirmSharedLink=true. Dropbox team policy can narrow requested visibility or forbid public links. Link revocation, password/expiry management, membership, and shared-folder administration are deferred.
• External behavior: deterministic local tests cover validation, authentication headers, binary transfer, pagination, retries, single-attempt writes, acknowledgements, redaction, response mapping, and metadata discovery. Live Dropbox execution remains deferred until an explicitly authorized account is supplied.
• Functional reference: the official n8n Dropbox node and current n8n source informed the file/folder/search operation set. Dropbox's HTTP API reference and OAuth guide define provider behavior and scopes.