Search
GET P/search searches the files of one application. It combines words with filters, applies the caller’s permissions inside the query, and pages like every other list. This page explains what it matches and how to use it well; every parameter is on Search query.
What q matches
Section titled “What q matches”q holds words and “quoted phrases”. in says where they match:
in |
Matches |
|---|---|
name |
Names that start with q, ignoring case: img finds IMG_5913.jpg and Img-cover.png, 5913 finds neither. It is a prefix, not a substring, and it does not look at the title |
keywords |
Whole words in the name, the title, the description, the tags, the category, the department and the values of custom |
content |
Whole words in the text inside documents: PDF, Word, PowerPoint, Excel, OpenDocument, text, HTML and JSON. See Searching inside documents |
The default is in=name,keywords: whole words anywhere, ranked by relevance (a match in the name counts most, then the title, then the tags). When no whole word matches, the same search returns the names that start with q instead, so typing the first letters of a file name still finds it. A word inside a longer token is not a whole word: 5913 does not match IMG_5913.jpg. There is no fuzzy matching and no match in the middle of a word.
With q, results are sorted by relevance; a name-only search (in=name, or the name fallback) sorts by name. Each hit carries highlights: up to three short snippets with the field they came from (name, title, description, tags, …, and content for a match in a document’s text). Without q, search is a filtered listing, newest change first.
Filters
Section titled “Filters”Every filter combines with every other: type (kind, mime_type, extension), place (folder_id, with recursive=true for its subfolders), dates (created_from, created_to, updated_from, updated_to), people (owner_id, created_by_user_id, created_by_client_id), your metadata (category, department, tags with tags_match=any|all, external_ref, up to five custom.<key>=<value>), size (min_size, max_size), and lifecycle (status, visibility, state). Trashed files appear only with state=trashed, and only those the caller may delete.
Permissions inside the query
Section titled “Permissions inside the query”A user sees only files they may view, and paging and total stay exact because the filter is part of the query, not applied afterwards. A user with files.view searches everything. A user without it searches the folders they may view and the files they own, up to 5,000 separate permission scopes; beyond that the answer is too_many_scopes, and a folder_id filter solves it. A machine client searches its whole context.
Paging and totals
Section titled “Paging and totals”limit defaults to 50 and is capped at 200. Pass next_cursor as after for the next page: paging is by cursor, so a page is as fast as the first one however deep you go, and files added meanwhile do not shift the pages. Search is rate limited to 120 per minute per caller.
total counts the matches the caller may see, exactly, up to 10,000. Above that it is null: show “more than 10,000” and keep paging with the cursor, never by counting. A broad search of a large application (no q, or a very common word) is where you meet it; a filter or a folder brings total back. Sorted by relevance, a search inside documents (in=content) pages through its best 1,000 matches; sort by name or date to page through all of them.
Tags and managed lists
Section titled “Tags and managed lists”| Route | Answers |
|---|---|
GET P/tags |
The application’s tags with their counts, optionally by prefix: for an autocomplete |
GET P/taxonomies/:name |
The managed list of categories or departments: values with value, label, active, and enforced |
PUT P/taxonomies/:name |
Replace a list (files.settings.manage, or a machine client with files:config.manage) |
When a list is enforced, uploads and updates must use one of its active values (taxonomy_value_invalid). See Search from your backend for a worked example.