Manage Applications

    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.

    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
    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"
        }
      ]
    }