Join BoxWorks 2024 to discover what's possible with content and AI!
Register now!Search for content
Searches for files, folders, web links, and shared files across the users content or across the entire enterprise.
Request
Query Parameters
fileLimits the search results to any items of this type. This parameter only takes one value. By default the API returns items that match any of these types.
file- Limits the search results to filesfolder- Limits the search results to foldersweb_link- Limits the search results to web links, also known as bookmarks
Value is one of file,folder,web_link
4535234,234123235,2654345Limits the search results to items within the given list of folders, defined as a comma separated lists of folder IDs.
Search results will also include items within any subfolders of those ancestor folders.
The folders still need to be owned or shared with
the currently authenticated user. If the folder is not accessible by this
user, or it does not exist, a HTTP 404 error code will be returned
instead.
To search across an entire enterprise, we recommend using the
enterprise_content scope parameter which can be requested with our
support team.
name,descriptionLimits the search results to any items that match the search query for a specific part of the file, for example the file description.
Content types are defined as a comma separated lists of Box recognized content types. The allowed content types are as follows.
name- The name of the item, as defined by itsnamefield.description- The description of the item, as defined by itsdescriptionfield.file_content- The actual content of the file.comments- The content of any of the comments on a file or folder.tags- Any tags that are applied to an item, as defined by itstagsfield.
2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00Limits the search results to any items created within a given date range.
Date ranges are defined as comma separated RFC3339 timestamps.
If the the start date is omitted (,2014-05-17T13:35:01-07:00)
anything created before the end date will be returned.
If the end date is omitted (2014-05-15T13:35:01-07:00,) the
current date will be used as the end date instead.
["2014-05-15T13:35:01-07:00","2014-05-17T13:35:01-07:00"]Limits the search results to any items deleted within a given date range.
Date ranges are defined as comma separated RFC3339 timestamps.
If the the start date is omitted (2014-05-17T13:35:01-07:00),
anything deleted before the end date will be returned.
If the end date is omitted (2014-05-15T13:35:01-07:00),
the current date will be used as the end date instead.
The trash_content parameter needs to be set to trashed_only.
If searching in trash is not performed, then an empty result is returned.
Data available from 2023-02-01 onwards.
["123422","23532","3241212"]Limits the search results to items that were deleted by the given list of users, defined as a list of comma separated user IDs.
The trash_content parameter needs to be set to trashed_only.
If searching in trash is not performed, an empty result set is returned. The items need to be owned or shared with the currently authenticated user for them to show up in the search results.
If the user does not have access to any files owned by any of the users, an empty result set is returned.
Data available from 2023-02-01 onwards.
ASC"DESC"Defines the direction in which search results are ordered. This API
defaults to returning items in descending (DESC) order unless this
parameter is explicitly specified.
When results are sorted by relevance the ordering is locked to returning
items in descending order of relevance, and this parameter is ignored.
Value is one of DESC,ASC
id,type,nameA comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.
Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.
pdf,png,gifLimits the search results to any files that match any of the provided file extensions. This list is a comma-separated list of file extensions without the dots.
10030200Defines the maximum number of items to return as part of a page of results.
[{"scope":"enterprise","templateKey":"contract","filters":[{"category":"online"},{"contractValue":100000}]}]Limits the search results to any items for which the metadata matches the provided filter.
This parameter is a list that specifies exactly one metadata template used to filter the search results.
The parameter is required unless the query parameter is provided.
10000The offset of the item at which to begin the response.
Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.
123422,23532,3241212Limits the search results to any items that are owned by the given list of owners, defined as a list of comma separated user IDs.
The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned.
To search across an entire enterprise, we recommend using the
enterprise_content scope parameter which can be requested with our
support team.
salesThe string to search for. This query is matched against item names, descriptions, text content of files, and various other fields of the different item types.
This parameter supports a variety of operators to further refine the results returns.
""- by wrapping a query in double quotes only exact matches are returned by the API. Exact searches do not return search matches based on specific character sequences. Instead, they return matches based on phrases, that is, word sequences. For example: A search for"Blue-Box"may return search results including the sequence"blue.box","Blue Box", and"Blue-Box"; any item containing the wordsBlueandBoxconsecutively, in the order specified.AND- returns items that contain both the search terms. For example, a search formarketing AND BoxWorksreturns items that have bothmarketingandBoxWorkswithin its text in any order. It does not return a result that only hasBoxWorksin its text.OR- returns items that contain either of the search terms. For example, a search formarketing OR BoxWorksreturns a result that has eithermarketingorBoxWorkswithin its text. Using this operator is not necessary as we implicitly interpret multi-word queries asORunless another supported boolean term is used.NOT- returns items that do not contain the search term provided. For example, a search formarketing AND NOT BoxWorksreturns a result that has onlymarketingwithin its text. Results containingBoxWorksare omitted.
We do not support lower case (that is,
and, or, and not) or mixed case (that is, And, Or, and Not)
operators.
This field is required unless the mdfilters parameter is defined.
123422,23532,3241212Limits the search results to any items that have been updated by the given list of users, defined as a list of comma separated user IDs.
The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned.
This feature only searches back to the last 10 versions of an item.
user_content"user_content"Limits the search results to either the files that the user has access to, or to files available to the entire enterprise.
The scope defaults to user_content, which limits the search
results to content that is available to the currently authenticated
user.
The enterprise_content can be requested by an admin through our
support channels. Once this scope has been enabled for a user, it
will allow that use to query for content across the entire
enterprise and not only the content that they have access to.
Value is one of user_content,enterprise_content
1000000,5000000Limits the search results to any items with a size within a given file size range. This applied to files and folders.
Size ranges are defined as comma separated list of a lower and upper byte size limit (inclusive).
The upper and lower bound can be omitted to create open ranges.
modified_at"relevance"Defines the order in which search results are returned. This API defaults to returning items by relevance unless this parameter is explicitly specified.
relevance(default) returns the results sorted by relevance to the query search term. The relevance is based on the occurrence of the search term in the items name, description, content, and additional properties.modified_atreturns the results ordered in descending order by date at which the item was last modified.
Value is one of modified_at,relevance
non_trashed_only"non_trashed_only"Determines if the search should look in the trash for items.
By default, this API only returns search results for items
not currently in the trash (non_trashed_only).
trashed_only- Only searches for items currently in the trashnon_trashed_only- Only searches for items currently not in the trashall_items- Searches for both trashed and non-trashed items.
Value is one of non_trashed_only,trashed_only,all_items
2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00Limits the search results to any items updated within a given date range.
Date ranges are defined as comma separated RFC3339 timestamps.
If the start date is omitted (,2014-05-17T13:35:01-07:00)
anything updated before the end date will be returned.
If the end date is omitted (2014-05-15T13:35:01-07:00,) the
current date will be used as the end date instead.
Response
Returns a collection of search results. If there are no matching
search results, the entries array will be empty.
Returns an error when the request was not valid. This can have multiple
reasons and the context_info object will provide you with more details.
missing_parameter- Please provide at least thequeryormdfiltersquery parameter in a search.invalid_parameter- Any of the fields might not be in the right format. This could for example mean that one of the RFC3339 dates is incorrect, or a string is provided where an integer is expected.
Returns an error when the user does not have the permission to make this API call.
- The developer provided a
scopeofenterprise_contentbut did not request this scope to be enabled for the user through our support channels.
Returns an error when the user does not have access to an item mentioned in the request.
- The developer provided a folder ID in
ancestor_folder_idsthat either does not exist or the user does not have access to.
An unexpected client error.
Request Example
curl -i -X GET "https://api.box.com/2.0/search?query=sales" \
-H "authorization: Bearer <ACCESS_TOKEN>"await client.search.searchForContent({
ancestorFolderIds: ['0' as string],
mdfilters: [
{
filters: {
['stringField']: 'stringValue',
['dateField']: {
lt: dateTimeFromString('2035-01-01T00:00:00Z'),
gt: dateTimeFromString('2035-01-03T00:00:00Z'),
} satisfies MetadataFieldFilterDateRange,
['floatField']: {
lt: 9.5,
gt: 10.5,
} satisfies MetadataFieldFilterFloatRange,
['enumField']: 'enumValue2',
['multiSelectField']: ['multiSelectValue1', 'multiSelectValue2'],
},
scope: 'enterprise' as MetadataFilterScopeField,
templateKey: templateKey,
} satisfies MetadataFilter,
],
} satisfies SearchForContentQueryParams);client.search.search_for_content(
ancestor_folder_ids=["0"],
mdfilters=[
MetadataFilter(
filters={
"stringField": "stringValue",
"dateField": MetadataFieldFilterDateRange(
lt=date_time_from_string("2035-01-01T00:00:00Z"),
gt=date_time_from_string("2035-01-03T00:00:00Z"),
),
"floatField": MetadataFieldFilterFloatRange(lt=9.5, gt=10.5),
"enumField": "enumValue2",
"multiSelectField": ["multiSelectValue1", "multiSelectValue2"],
},
scope=MetadataFilterScopeField.ENTERPRISE.value,
template_key=template_key,
)
],
)// Find the first 10 files matching "taxes"
long offsetValue = 0;
long limitValue = 10;
BoxSearch boxSearch = new BoxSearch(api);
BoxSearchParameters searchParams = new BoxSearchParameters();
searchParams.setQuery("taxes");
searchParams.setType("file");
PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);items = client.search().query(query='TEST QUERY', limit=100, file_extensions=['pdf', 'doc'])
for item in items:
print(f'The item ID is {item.id} and the item name is {item.name}')// Search for PDF or Word documents matching "Meeting Notes"
BoxCollection<BoxItem> results = await client.SearchManager
.QueryAsync("Meeting Notes", fileExtensions: new { "pdf", "docx" });// Search for PDF or Word documents matching "Mobile"
client.search.query(
'Mobile',
{
fields: 'name,modified_at,size,extension,permissions,sync_state',
file_extensions: 'pdf,doc',
limit: 200,
offset: 0
})
.then(results => {
/* results -> {
total_count: 1,
entries:
[ { type: 'file',
id: '11111',
sequence_id: '1',
etag: '1',
sha1: 'f89d97c5eea0a68e2cec911s932eca34a52355d2',
name: 'Box for Sales - Empowering Your Mobile Worker White paper 2pg (External).pdf',
description: '',
size: 408979,
path_collection:
{ total_count: 2,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
{ type: 'folder',
id: '22222',
sequence_id: '1',
etag: '1',
name: 'Marketing Active Work' } ] },
created_at: '2014-05-17T12:59:45-07:00',
modified_at: '2014-05-17T13:00:20-07:00',
trashed_at: null,
purged_at: null,
content_created_at: '2014-05-17T12:58:58-07:00',
content_modified_at: '2014-05-17T12:58:58-07:00',
created_by:
{ type: 'user',
id: '33333',
name: 'Example User',
login: 'user@example.com' },
modified_by:
{ type: 'user',
id: '33333',
name: 'Example User',
login: 'user@example.com' },
owned_by:
{ type: 'user',
id: '33333',
name: 'Example User',
login: 'user@example.com' },
shared_link: null,
parent:
{ type: 'folder',
id: '22222',
sequence_id: '1',
etag: '1',
name: 'Marketing Active Work' },
item_status: 'active' } ],
limit: 200,
offset: 0 }
*/
});let iterator = client.search.query(query: "Quarterly Business Review")
iterator.next { results in
switch results {
case let .success(page):
for item in page.entries {
switch item {
case let .file(file):
print("- File \(file.name) (ID: \(file.id))")
case let .folder(folder):
print("- Folder \(file.name) (ID: \(file.id))")
case let .webLink(webLink):
print("- Web Link \(file.name) (ID: \(file.id))")
}
}
case let .failure(error):
print(error)
}
}Response Example
{
"type": "search_results_items",
"entries": [
{
"id": "12345",
"etag": "1",
"type": "file",
"sequence_id": "3",
"name": "Contract.pdf",
"sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
"file_version": {
"id": "12345",
"type": "file_version",
"sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
},
"description": "Contract for Q1 renewal",
"size": 629644,
"path_collection": {
"total_count": 1,
"entries": [
{
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
}
]
},
"created_at": "2012-12-12T10:53:43-08:00",
"modified_at": "2012-12-12T10:53:43-08:00",
"trashed_at": "2012-12-12T10:53:43-08:00",
"purged_at": "2012-12-12T10:53:43-08:00",
"content_created_at": "2012-12-12T10:53:43-08:00",
"content_modified_at": "2012-12-12T10:53:43-08:00",
"created_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"modified_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"owned_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"shared_link": {
"url": "https://www.box.com/s/vspke7y05sb214wjokpk",
"download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
"vanity_url": "https://acme.app.box.com/v/my_url/",
"vanity_name": "my_url",
"access": "open",
"effective_access": "company",
"effective_permission": "can_download",
"unshared_at": "2018-04-13T13:53:23-07:00",
"is_password_enabled": true,
"permissions": {
"can_download": true,
"can_preview": true,
"can_edit": false
},
"download_count": 3,
"preview_count": 3
},
"parent": {
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
},
"item_status": "active",
"version_number": "1",
"comment_count": 10,
"permissions": {
"can_delete": true,
"can_download": true,
"can_invite_collaborator": true,
"can_rename": true,
"can_set_share_access": true,
"can_share": true,
"can_annotate": true,
"can_comment": true,
"can_preview": true,
"can_upload": true,
"can_view_annotations_all": true,
"can_view_annotations_self": true
},
"tags": [
"approved"
],
"lock": {
"id": "11446498",
"type": "lock",
"created_by": {
"id": "11446498",
"type": "user",
"name": "Aaron Levie",
"login": "ceo@example.com"
},
"created_at": "2012-12-12T10:53:43-08:00",
"expired_at": "2012-12-12T10:53:43-08:00",
"is_download_prevented": true,
"app_type": "office_wopiplus"
},
"extension": "pdf",
"is_package": true,
"expiring_embed_link": {
"access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
"expires_in": 3600,
"token_type": "bearer",
"restricted_to": [
{
"scope": "item_download",
"object": {
"id": "12345",
"etag": "1",
"type": "folder",
"sequence_id": "3",
"name": "Contracts"
}
}
],
"url": "https://cloud.app.box.com/preview/expiring_embed/..."
},
"watermark_info": {
"is_watermarked": true
},
"is_accessible_via_shared_link": true,
"allowed_invitee_roles": [
"editor"
],
"is_externally_owned": true,
"has_collaborations": true,
"metadata": {
"enterprise_27335": {
"marketingCollateral": {
"$canEdit": true,
"$id": "01234500-12f1-1234-aa12-b1d234cb567e",
"$parent": "folder_59449484661",
"$scope": "enterprise_27335",
"$template": "marketingCollateral",
"$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
"$typeVersion": 2,
"$version": 1
}
}
},
"expires_at": "2012-12-12T10:53:43-08:00",
"representations": {
"entries": [
{
"content": {
"url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
},
"info": {
"url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
},
"properties": {
"dimensions": "2048x2048",
"paged": true,
"thumb": true
},
"representation": "png",
"status": {
"state": "success"
}
}
]
},
"classification": {
"name": "Top Secret",
"definition": "Content that should not be shared outside the company.",
"color": "#FF0000"
},
"uploader_display_name": "Ellis Wiggins",
"disposition_at": "2012-12-12T10:53:43-08:00",
"shared_link_permission_options": [
"can_preview"
],
"is_associated_with_app_item": true
}
],
"limit": 1000,
"offset": 2000,
"total_count": 5000
}