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

Bearer [ACCESS_TOKEN]
application/json

Query Parameters

stringin queryoptional
file

Limits search results to items of this type.

Value is one of file,folder,web_link

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.

string arrayin 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.

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
10030200

The maximum number of items to return.

Metadata filter arrayin queryoptional
[{"scope":"enterprise","templateKey":"contract","filters":{"category":"online"}}]

A list of metadata templates to filter the search results by.

Required unless query parameter is defined.

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

Required unless mdfilters parameter is defined.

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
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/jsonSearch Results

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

application/jsonClient error

An unexpected client error.

get
Search for content
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -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 }
		*/
	});
iOS
client.search.query(query: "Quarterly Business Review") { results in
    switch results {
    case let .success(iterator):
        for i in 1 ... 10 {
            iterator.next { result in
                switch result {
                case let .success(item):
                    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)
                }
            }
        }
    case let .failure(error):
        print(error)
    }
}

Response Example

{
  "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/",
        "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
        },
        "download_count": 3,
        "preview_count": 3
      },
      "parent": {
        "id": 12345,
        "etag": 1,
        "type": "folder",
        "sequence_id": 3,
        "name": "Contracts"
      },
      "item_status": "active"
    }
  ],
  "limit": 1000,
  "offset": 2000,
  "total_count": 5000
}