Search for content

get
https://api.box.com/2.0
/search

Searches for items that are available to the user or an entire enterprise.

Request

application/json

Query Parameters

stringin queryoptional
4535234,234123235,2654345

Limits search results to items within the given list of folders.

Folders are defined as a comma separated lists of folder IDs.

Search results will also include items within subfolders.

stringin queryoptional
name,description

Limits search results to items with the given content types.

Content types are defined as a comma separated lists of Box recognized content types.

Value is one of "name", "description", "file_content", "comments", "tag"

stringin queryoptional
2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00

Limits search results to 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) the earliest known date will be used as the start date instead.

If the end date is omitted (2014-05-15T13:35:01-07:00,) the current date will be used as the end date instead.

stringin queryoptional
ASC"DESC"

Defines the direction in which search results are ordered. Default value is DESC.

When results are sorted by relevance the ordering is forced to DESC, ignoring the value of this parameter.

Value is one of "DESC", "ASC"

string arrayin queryoptional
id,type,name

A 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.

stringin queryoptional
pdf,png,gif

Limits search results to a comma-separated list of file extensions.

integer / int64in queryoptional
10001000-1000

The maximum number of items to return per page.

Metadata Filter arrayin queryoptional
[{"scope":"enterprise","templateKey":"marketingCollateral","filters":{"documentType":"datasheet"}}]

Limits search results to items that match the metadata template name and content.

integer / int64in queryoptional
10000

The offset of the item at which to begin the response.

stringin queryoptional
123422,23532,3241212

Limits search results to items owned by the given list of owners.

Owners are defined as a comma separated list of user IDs.

stringin queryrequired
sales

The 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.

stringin queryoptional
user_content

Limits search results to a user scope.

Defaults to user_content which limits the search to content available to the current user

Setting this to enterprise_content widens the search to content available to the entire enterprise. To enable this scope for an administrator, please reach out to support.

Value is one of "user_content", "enterprise_content"

stringin queryoptional
1000000,5000000

Limits search results to items within a given file size range.

File size ranges are defined as comma separated byte sizes.

The upper and lower bound can be omitted to create open ranges.

stringin queryoptional
modified_at"relevance"

Defines the order in which results are returned. Defaults to relevance.

  • relevance (default) returns the results sorted by relevance to the query search term.
  • modified_at returns the results ordered in descending order by date at which the item was last modified.

Value is one of "modified_at", "relevance"

stringin queryoptional
non_trashed_only

Controls if search results include the trash.

Defaults to non_trashed_only

Value is one of "non_trashed_only", "trashed_only"

stringin queryoptional
file

Limits search results to items of this type.

Value is one of "file", "folder", "web_link"

stringin queryoptional
2014-05-15T13:35:01-07:00,2014-05-17T13:35:01-07:00

Limits search results to 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) the earliest known date will be used as the start date instead.

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

application/jsonItems

Returns a collection of search results. If there are no matching search results, the entries array will be empty.

You can now try out some of our APIs live, right here in the documentation.
Log In

Request Example

cURL
curl -X GET https://api.box.com/2.0/search?query=sales \
     -H "Authorization: Bearer <ACCESS_TOKEN>"
.NET
// Search for PDF or Word documents matching "Meeting Notes"
BoxCollection<BoxItem> results = await client.SearchManager
    .QueryAsync("Meeting Notes", fileExtensions: new { "pdf", "docx" });
Java
// 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);
Python
items = client.search().query(query='TEST QUERY', limit=100, file_extensions=['pdf', 'doc'])
for item in items:
    print('The item ID is {0} and the item name is {1}'.format(item.id, item.name))
Node
// 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 }
		*/
	});

Response Example

{
  "total_count": 5000,
  "limit": 1000,
  "offset": 2000,
  "order": [
    {
      "by": "type",
      "direction": "ASC"
    }
  ],
  "entries": [
    {
      "id": 12345,
      "etag": 1,
      "type": "file",
      "sequence_id": 3,
      "name": "Contract.pdf"
    }
  ]
}