Why v2 Replaces v1

Dropbox's earlier search endpoint is being retired, and the replacement /files/search_v2 carries both performance and reliability gains. Search v2 delivers over 20% performance improvement relative to v1, and it is also consumed internally by Dropbox's own surfaces, which brings additional reliability. Applications that depend on search functionality should migrate rather than stay on the v1 endpoint.

What the Endpoint Returns

Result coverage is broader under v2. It can return more of the file types supported by Dropbox, including Paper files, "online-only" files such as G Suite or O365 documents, and unmounted files. An unmounted file is one that has been shared with the API caller but is not mounted to their Dropbox; the mechanics of mounting and unmounting shared folders are described in Dropbox's Sharing Guide.

  • File extensions — Passing the file_extensions parameter with a list such as ["pdf", "xlsx", "mp3"] restricts matches to those extensions only.
  • File categories — A file_categories list such as ["spreadsheet", "presentation"] limits results to the file types belonging to the given categories.
  • Sort order — Relevance is the default ordering, but setting order_by to last_modified_time in the search options sorts by when each file was last changed.
  • Highlighting — The include_highlights Boolean optionally returns highlighted spans alongside results, the same exact-match highlighting the Dropbox UI shows for a search string.

Pagination

Paging through results moves to /files/search/continue_v2, which takes the cursor produced by /files/search_v2. Limiting max_results is a practical way to exercise the behavior: issue the search with a small limit, then hand the returned cursor to the continue endpoint to retrieve the next page.

Worked Examples

Suppose the goal is finding next year's financial projections without knowing the exact filename or location. Searching within a file category keeps the match set under control; one option is to search all spreadsheets for a name containing the word "forecast."

Extension-filtered search with recency ordering

Whiteboarding session photos are a common case where no formal process governs who captures the image or where it is stored. Because the team holds a session each month, limiting the search to specific file extensions and ordering by last modification time surfaces the relevant photos.

Migration

Compared with v1, v2 offers better performance, a wider set of supported file types in results, filtering by extension or category, and features such as pagination and highlighting. Search v1 is scheduled for retirement, so apps relying on search should move to /files/search_v2. Dropbox directs migration questions to its developer forum, with tickets available for more direct support.