Maton

Dropbox

Access the Dropbox API with managed OAuth authentication. Manage files and folders, search content, retrieve metadata, and work with file revisions.

Reference

Get Current Account

POST /dropbox/2/users/get_current_account
Content-Type: application/json

null

Response:

{
  "account_id": "dbid:AAA-AdT84WzkyLw5s590DbYF1nGomiAoO8I",
  "name": {
    "given_name": "John",
    "surname": "Doe",
    "familiar_name": "John",
    "display_name": "John Doe",
    "abbreviated_name": "JD"
  },
  "email": "john@example.com",
  "email_verified": true,
  "disabled": false,
  "country": "US",
  "locale": "en",
  "account_type": {
    ".tag": "basic"
  },
  "root_info": {
    ".tag": "user",
    "root_namespace_id": "11989877987",
    "home_namespace_id": "11989877987"
  }
}

Get Space Usage

POST /dropbox/2/users/get_space_usage
Content-Type: application/json

null

Response:

{
  "used": 538371,
  "allocation": {
    ".tag": "individual",
    "allocated": 2147483648
  }
}

List Folder

POST /dropbox/2/files/list_folder
Content-Type: application/json

{
  "path": "",
  "recursive": false,
  "include_deleted": false,
  "include_has_explicit_shared_members": false
}

Use empty string "" for the root folder.

Optional Parameters:

  • recursive - Include contents of subdirectories (default: false)
  • include_deleted - Include deleted files (default: false)
  • include_media_info - Include media info for photos/videos
  • limit - Maximum entries per response (1-2000)

Response:

{
  "entries": [
    {
      ".tag": "file",
      "name": "document.pdf",
      "path_lower": "/document.pdf",
      "path_display": "/document.pdf",
      "id": "id:Awe3Av8A8YYAAAAAAAAABQ",
      "client_modified": "2026-02-09T19:58:12Z",
      "server_modified": "2026-02-09T19:58:13Z",
      "rev": "016311c063b4f8700000002caa704e3",
      "size": 538371,
      "is_downloadable": true,
      "content_hash": "6542845d7b65ffc5358ebaa6981d991bab9fda194afa48bd727fcbe9e4a3158b"
    },
    {
      ".tag": "folder",
      "name": "Documents",
      "path_lower": "/documents",
      "path_display": "/Documents",
      "id": "id:Awe3Av8A8YYAAAAAAAAABw"
    }
  ],
  "cursor": "AAVqv-MUYFlM98b1QpFK6YaYC8L1s39lWjqbeqgWu4un...",
  "has_more": false
}

Continue Listing Folder

POST /dropbox/2/files/list_folder/continue
Content-Type: application/json

{
  "cursor": "AAVqv-MUYFlM98b1QpFK6YaYC8L1s39lWjqbeqgWu4un..."
}

Use when has_more is true in the previous response.

Get Metadata

POST /dropbox/2/files/get_metadata
Content-Type: application/json

{
  "path": "/document.pdf",
  "include_media_info": false,
  "include_deleted": false,
  "include_has_explicit_shared_members": false
}

Response:

{
  ".tag": "file",
  "name": "document.pdf",
  "path_lower": "/document.pdf",
  "path_display": "/document.pdf",
  "id": "id:Awe3Av8A8YYAAAAAAAAABQ",
  "client_modified": "2026-02-09T19:58:12Z",
  "server_modified": "2026-02-09T19:58:13Z",
  "rev": "016311c063b4f8700000002caa704e3",
  "size": 538371,
  "is_downloadable": true,
  "content_hash": "6542845d7b65ffc5358ebaa6981d991bab9fda194afa48bd727fcbe9e4a3158b"
}

Create Folder

POST /dropbox/2/files/create_folder_v2
Content-Type: application/json

{
  "path": "/New Folder",
  "autorename": false
}

Response:

{
  "metadata": {
    "name": "New Folder",
    "path_lower": "/new folder",
    "path_display": "/New Folder",
    "id": "id:Awe3Av8A8YYAAAAAAAAABw"
  }
}

Copy File or Folder

POST /dropbox/2/files/copy_v2
Content-Type: application/json

{
  "from_path": "/source/file.pdf",
  "to_path": "/destination/file.pdf",
  "autorename": false
}

Response:

{
  "metadata": {
    ".tag": "file",
    "name": "file.pdf",
    "path_lower": "/destination/file.pdf",
    "path_display": "/destination/file.pdf",
    "id": "id:Awe3Av8A8YYAAAAAAAAACA"
  }
}

Move File or Folder

POST /dropbox/2/files/move_v2
Content-Type: application/json

{
  "from_path": "/old/location/file.pdf",
  "to_path": "/new/location/file.pdf",
  "autorename": false
}

Response:

{
  "metadata": {
    ".tag": "file",
    "name": "file.pdf",
    "path_lower": "/new/location/file.pdf",
    "path_display": "/new/location/file.pdf",
    "id": "id:Awe3Av8A8YYAAAAAAAAACA"
  }
}

Delete File or Folder

POST /dropbox/2/files/delete_v2
Content-Type: application/json

{
  "path": "/file-to-delete.pdf"
}

Response:

{
  "metadata": {
    ".tag": "file",
    "name": "file-to-delete.pdf",
    "path_lower": "/file-to-delete.pdf",
    "path_display": "/file-to-delete.pdf",
    "id": "id:Awe3Av8A8YYAAAAAAAAABQ"
  }
}
POST /dropbox/2/files/get_temporary_link
Content-Type: application/json

{
  "path": "/document.pdf"
}

Response:

{
  "metadata": {
    "name": "document.pdf",
    "path_lower": "/document.pdf",
    "path_display": "/document.pdf",
    "id": "id:Awe3Av8A8YYAAAAAAAAABQ",
    "size": 538371,
    "is_downloadable": true
  },
  "link": "https://uc785ee484c03b6556c091ea4491.dl.dropboxusercontent.com/cd/0/get/..."
}

The link is valid for 4 hours.

Note: Upload endpoints use a different request format. File content is sent as the raw request body, and parameters are passed in the Dropbox-API-Arg header as JSON. Maton automatically routes these to content.dropboxapi.com.

Upload File (up to 150 MB)

POST /dropbox/2/files/upload
Content-Type: application/octet-stream
Dropbox-API-Arg: {"path": "/test.txt", "mode": "add", "autorename": true, "mute": false}

<file contents>

Parameters (in Dropbox-API-Arg header):

  • path (required) - Path in Dropbox where the file will be saved
  • mode - Write mode: add (default), overwrite, or update with rev
  • autorename - If true, rename file if there's a conflict (default: false)
  • mute - If true, don't notify desktop app (default: false)
  • strict_conflict - If true, be more strict about conflicts (default: false)

Response:

{
  "name": "test.txt",
  "path_lower": "/test.txt",
  "path_display": "/test.txt",
  "id": "id:Awe3Av8A8YYAAAAAAAAABw",
  "client_modified": "2026-04-14T10:00:00Z",
  "server_modified": "2026-04-14T10:00:01Z",
  "rev": "016311c063b4f8700000002caa704e4",
  "size": 1024,
  "is_downloadable": true,
  "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Upload Large Files (Upload Session)

For files larger than 150 MB, use upload sessions. Files can be up to 350 GB.

Step 1: Start Session

POST /dropbox/2/files/upload_session/start
Content-Type: application/octet-stream
Dropbox-API-Arg: {"close": false}

<first chunk of file content>

Response:

{
  "session_id": "AAAAAAAAAAFxxxxxxxxxxxxxxx"
}

Step 2: Append Data (repeat as needed)

POST /dropbox/2/files/upload_session/append_v2
Content-Type: application/octet-stream
Dropbox-API-Arg: {"cursor": {"session_id": "AAAAAAAAAAFxxxxxxxxxxxxxxx", "offset": 10000000}, "close": false}

<next chunk of file content>

The offset must match the total bytes uploaded so far.

Step 3: Finish Session

POST /dropbox/2/files/upload_session/finish
Content-Type: application/octet-stream
Dropbox-API-Arg: {"cursor": {"session_id": "AAAAAAAAAAFxxxxxxxxxxxxxxx", "offset": 50000000}, "commit": {"path": "/large_file.zip", "mode": "add", "autorename": true}}

<final chunk of file content, can be empty>

Response: Same as regular upload endpoint.

Finish Multiple Upload Sessions (Batch)

Complete multiple upload sessions in one call:

POST /dropbox/2/files/upload_session/finish_batch
Content-Type: application/json

{
  "entries": [
    {
      "cursor": {
        "session_id": "AAAAAAAAAAFxxxxxxxxxxxxxxx",
        "offset": 50000000
      },
      "commit": {
        "path": "/file1.zip",
        "mode": "add",
        "autorename": true
      }
    },
    {
      "cursor": {
        "session_id": "AAAAAAAAAAFyyyyyyyyyyyyyyy",
        "offset": 30000000
      },
      "commit": {
        "path": "/file2.zip",
        "mode": "add",
        "autorename": true
      }
    }
  ]
}

Response (async job):

{
  ".tag": "async_job_id",
  "async_job_id": "dbjid:AAAAAAAAAA..."
}

Check status with /files/upload_session/finish_batch/check.

Check Batch Status

POST /dropbox/2/files/upload_session/finish_batch/check
Content-Type: application/json

{
  "async_job_id": "dbjid:AAAAAAAAAA..."
}

Response (in progress):

{
  ".tag": "in_progress"
}

Response (complete):

{
  ".tag": "complete",
  "entries": [
    {
      ".tag": "success",
      "name": "file1.zip",
      "path_lower": "/file1.zip",
      "path_display": "/file1.zip",
      "id": "id:Awe3Av8A8YYAAAAAAAAABw"
    },
    {
      ".tag": "success",
      "name": "file2.zip",
      "path_lower": "/file2.zip",
      "path_display": "/file2.zip",
      "id": "id:Awe3Av8A8YYAAAAAAAAABx"
    }
  ]
}

Download File

POST /dropbox/2/files/download
Dropbox-API-Arg: {"path": "/document.pdf"}

Response: Raw file contents with metadata in Dropbox-API-Result response header.

Download Folder as ZIP

POST /dropbox/2/files/download_zip
Dropbox-API-Arg: {"path": "/folder"}

Response: ZIP file contents. Note: folders larger than 20 GB or with more than 10,000 files cannot be downloaded as ZIP.

Export File

Export a file from Dropbox (e.g., Paper docs to markdown):

POST /dropbox/2/files/export
Dropbox-API-Arg: {"path": "/document.paper"}

Get Preview

POST /dropbox/2/files/get_preview
Dropbox-API-Arg: {"path": "/document.docx"}

Response: PDF preview of the file.

Get Thumbnail

POST /dropbox/2/files/get_thumbnail_v2
Dropbox-API-Arg: {"resource": {".tag": "path", "path": "/photo.jpg"}, "format": "jpeg", "size": "w128h128"}

Thumbnail Sizes:

  • w32h32, w64h64, w128h128, w256h256, w480h320, w640h480, w960h640, w1024h768, w2048h1536

Search Files

POST /dropbox/2/files/search_v2
Content-Type: application/json

{
  "query": "document",
  "options": {
    "path": "",
    "max_results": 100,
    "file_status": "active",
    "filename_only": false
  }
}

Response:

{
  "has_more": false,
  "matches": [
    {
      "highlight_spans": [],
      "match_type": {
        ".tag": "filename"
      },
      "metadata": {
        ".tag": "metadata",
        "metadata": {
          ".tag": "file",
          "name": "document.pdf",
          "path_display": "/document.pdf",
          "path_lower": "/document.pdf",
          "id": "id:Awe3Av8A8YYAAAAAAAAABw"
        }
      }
    }
  ]
}
POST /dropbox/2/files/search/continue_v2
Content-Type: application/json

{
  "cursor": "..."
}

List Revisions

POST /dropbox/2/files/list_revisions
Content-Type: application/json

{
  "path": "/document.pdf",
  "mode": "path",
  "limit": 10
}

Response:

{
  "is_deleted": false,
  "entries": [
    {
      "name": "document.pdf",
      "path_lower": "/document.pdf",
      "path_display": "/document.pdf",
      "id": "id:Awe3Av8A8YYAAAAAAAAABQ",
      "client_modified": "2026-02-09T19:58:12Z",
      "server_modified": "2026-02-09T19:58:13Z",
      "rev": "016311c063b4f8700000002caa704e3",
      "size": 538371,
      "is_downloadable": true
    }
  ],
  "has_more": false
}

Restore File

POST /dropbox/2/files/restore
Content-Type: application/json

{
  "path": "/document.pdf",
  "rev": "016311c063b4f8700000002caa704e3"
}

Get Tags

POST /dropbox/2/files/tags/get
Content-Type: application/json

{
  "paths": ["/document.pdf", "/folder"]
}

Response:

{
  "paths_to_tags": [
    {
      "path": "/document.pdf",
      "tags": [
        {
          ".tag": "user_generated_tag",
          "tag_text": "important"
        }
      ]
    },
    {
      "path": "/folder",
      "tags": []
    }
  ]
}

Add Tag

POST /dropbox/2/files/tags/add
Content-Type: application/json

{
  "path": "/document.pdf",
  "tag_text": "important"
}

Returns null on success.

Note: Tag text must match pattern [\w]+ (alphanumeric and underscores only, no hyphens or spaces).

Remove Tag

POST /dropbox/2/files/tags/remove
Content-Type: application/json

{
  "path": "/document.pdf",
  "tag_text": "important"
}

Returns null on success.

Delete Batch

POST /dropbox/2/files/delete_batch
Content-Type: application/json

{
  "entries": [
    {"path": "/file1.pdf"},
    {"path": "/file2.pdf"}
  ]
}

Returns async job ID. Check status with /files/delete_batch/check.

Copy Batch

POST /dropbox/2/files/copy_batch_v2
Content-Type: application/json

{
  "entries": [
    {"from_path": "/source/file1.pdf", "to_path": "/dest/file1.pdf"},
    {"from_path": "/source/file2.pdf", "to_path": "/dest/file2.pdf"}
  ],
  "autorename": false
}

Move Batch

POST /dropbox/2/files/move_batch_v2
Content-Type: application/json

{
  "entries": [
    {"from_path": "/old/file1.pdf", "to_path": "/new/file1.pdf"},
    {"from_path": "/old/file2.pdf", "to_path": "/new/file2.pdf"}
  ],
  "autorename": false
}

Resources

PreviousConstant ContactNextDropbox Business

On this page

Reference
Get Current Account
Get Space Usage
List Folder
Continue Listing Folder
Get Metadata
Create Folder
Copy File or Folder
Move File or Folder
Delete File or Folder
Get Temporary Download Link
Upload File (up to 150 MB)
Upload Large Files (Upload Session)
Finish Multiple Upload Sessions (Batch)
Check Batch Status
Download File
Download Folder as ZIP
Export File
Get Preview
Get Thumbnail
Search Files
Continue Search
List Revisions
Restore File
Get Tags
Add Tag
Remove Tag
Delete Batch
Copy Batch
Move Batch
Resources