openapi: 3.1.0
info:
version: "1.0"
title: Box Authorize Authorization Search API
description: Needs a description.
tags:
- name: Search
description: 'The Box API provides a way to find content in Box
using full-text search queries.'
x-box-tag: search
paths:
/metadata_queries/execute_read:
post:
operationId: post_metadata_queries_execute_read
summary: Box Query files/folders by metadata
tags:
- Search
x-box-tag: search
x-box-sanitized: true
x-box-enable-explorer: true
description: 'Create a search using SQL-like syntax to return items that match specific
metadata.
By default, this endpoint returns only the most basic info about the items for
which the query matches. To get additional fields for each item, including any
of the metadata, use the `fields` attribute in the query.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataQuery'
responses:
'200':
description: Returns a list of files and folders that match this metadata query.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataQueryResults'
'400':
description: 'Returns an error when the request body is not valid.
* `invalid_query` - Any of the provided body parameters might be
incorrect. This can mean the `query` is incorrect, as well as some cases
where the `from` value does not represent a valid template.
* `unexpected_json_type` - An argument from the `query` string is not
present in `query_param`. For example, `query` of `name = :name` requires
the `query_param` to include a value for the `name` argument, for example
`{ "name": "Box, Inc" }`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: 'Returns an error when a metadata template with the given `scope` and
`templateKey` can not be found. The error response will include extra
details.
* `instance_not_found` - The template was not found. Please make sure
to use the full template scope including the enterprise ID, like
`enterprise_12345`.'
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/search:
get:
operationId: get_search
summary: Box Search for content
tags:
- Search
x-box-tag: search
x-box-enable-explorer: true
description: 'Searches for files, folders, web links, and shared files across the
users content or across the entire enterprise.'
parameters:
- name: query
description: "The string to search for. This query is matched against item names,\ndescriptions, text content of files, and various other fields of\nthe different item types.\n\nThis parameter supports a variety of operators to further refine\nthe results returns.\n\n* `\"\"` - by wrapping a query in double quotes only exact matches are\n returned by the API. Exact searches do not return search matches\n based on specific character sequences. Instead, they return\n matches based on phrases, that is, word sequences. For example:\n A search for `\"Blue-Box\"` may return search results including\n the sequence `\"blue.box\"`, `\"Blue Box\"`, and `\"Blue-Box\"`;\n any item containing the words `Blue` and `Box` consecutively, in\n the order specified.\n* `AND` - returns items that contain both the search terms. For\n example, a search for `marketing AND BoxWorks` returns items\n that have both `marketing` and `BoxWorks` within its text in any order.\n It does not return a result that only has `BoxWorks` in its text.\n* `OR` - returns items that contain either of the search terms. For\n example, a search for `marketing OR BoxWorks` returns a result that\n has either `marketing` or `BoxWorks` within its text. Using this\n operator is not necessary as we implicitly interpret multi-word\n queries as `OR` unless another supported boolean term is used.\n* `NOT` - returns items that do not contain the search term provided.\n For example, a search for `marketing AND NOT BoxWorks` returns a result\n that has only `marketing` within its text. Results containing\n `BoxWorks` are omitted.\n\nWe do not support lower case (that is,\n`and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`)\noperators.\n\nThis field is required unless the `mdfilters` parameter is defined."
in: query
required: false
example: sales
schema:
type: string
- name: scope
description: '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.'
in: query
required: false
schema:
type: string
enum:
- user_content
- enterprise_content
default: user_content
example: user_content
- name: file_extensions
description: 'Limits 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.'
example:
- pdf
- png
- gif
in: query
required: false
explode: false
schema:
type: array
items:
type: string
- name: created_at_range
description: 'Limits 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.'
example:
- '2014-05-15T13:35:01-07:00'
- '2014-05-17T13:35:01-07:00'
in: query
required: false
explode: false
schema:
type: array
items:
type: string
- name: updated_at_range
description: 'Limits 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.'
example:
- '2014-05-15T13:35:01-07:00'
- '2014-05-17T13:35:01-07:00'
in: query
required: false
explode: false
schema:
type: array
items:
type: string
- name: size_range
description: 'Limits 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.'
example:
- 1000000
- 5000000
in: query
required: false
explode: false
schema:
type: array
items:
type: integer
- name: owner_user_ids
description: 'Limits 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.'
example:
- '123422'
- '23532'
- '3241212'
in: query
required: false
explode: false
schema:
type: array
items:
type: string
- name: recent_updater_user_ids
description: 'Limits 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.'
example:
- '123422'
- '23532'
- '3241212'
in: query
required: false
explode: false
schema:
type: array
items:
type: string
- name: ancestor_folder_ids
description: 'Limits 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.'
explode: false
example:
- '4535234'
- '234123235'
- '2654345'
in: query
required: false
schema:
type: array
items:
type: string
- name: content_types
description: "Limits the search results to any items that match the search query\nfor a specific part of the file, for example the file description.\n\nContent types are defined as a comma separated lists\nof Box recognized content types. The allowed content types are as follows.\n\n* `name` - The name of the item, as defined by its `name` field.\n* `description` - The description of the item, as defined by its\n `description` field.\n* `file_content` - The actual content of the file.\n* `comments` - The content of any of the comments on a file or\n folder.\n* `tags` - Any tags that are applied to an item, as defined by its\n `tags` field."
in: query
example:
- name
- description
explode: false
required: false
schema:
type: array
items:
type: string
enum:
- name
- description
- file_content
- comments
- tag
- name: type
description: "Limits the search results to any items of this type. This\nparameter only takes one value. By default the API returns\nitems that match any of these types.\n\n* `file` - Limits the search results to files\n* `folder` - Limits the search results to folders\n* `web_link` - Limits the search results to web links, also known\n as bookmarks"
example: file
in: query
required: false
schema:
type: string
enum:
- file
- folder
- web_link
- name: trash_content
description: "Determines if the search should look in the trash for items.\n\nBy default, this API only returns search results for items\nnot currently in the trash (`non_trashed_only`).\n\n* `trashed_only` - Only searches for items currently in the trash\n* `non_trashed_only` - Only searches for items currently not in\n the trash\n* `all_items` - Searches for both trashed and non-trashed items."
in: query
required: false
example: non_trashed_only
schema:
type: string
default: non_trashed_only
enum:
- non_trashed_only
- trashed_only
- all_items
- name: mdfilters
description: 'Limits the search results to any items for which the metadata matches
the provided filter.
This parameter contains a list of 1 metadata template to filter
the search results by. This list can currently only
contain one entry, though this might be expanded in the future.
This parameter is required unless the `query` parameter is provided.'
in: query
example:
- scope: enterprise
templateKey: contract
filters:
category: online
x-example:
- scope: enterprise
templateKey: contract
filters:
category: online
contractValue: 1000000
required: false
schema:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/MetadataFilter'
description: 'A list of metadata templates to filter the search results by.
Required unless `query` parameter is defined.'
- name: sort
description: '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_at` returns the results ordered in descending order by date
at which the item was last modified.'
in: query
required: false
schema:
type: string
default: relevance
enum:
- modified_at
- relevance
example: modified_at
- name: direction
description: '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.'
in: query
required: false
schema:
type: string
default: DESC
enum:
- DESC
- ASC
example: ASC
- name: limit
description: 'Defines the maximum number of items to return as part of a page of
results.'
in: query
required: false
example: 100
schema:
type: integer
format: int64
default: 30
maximum: 200
- name: include_recent_shared_links
description: 'Defines whether the search results should include any items
that the user recently accessed through a shared link.
When this parameter has been set to true,
the format of the response of this API changes to return
a list of [Search Results with
Shared Links](r://search_results_with_shared_links)'
in: query
required: false
example: true
schema:
type: boolean
default: false
- name: fields
description: '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.'
in: query
example:
- id
- type
- name
required: false
explode: false
schema:
type: array
items:
type: string
- name: offset
description: 'The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.'
in: query
required: false
example: 1000
schema:
type: integer
format: int64
default: 0
- name: deleted_user_ids
description: '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.'
example:
- '123422'
- '23532'
- '3241212'
in: query
required: false
schema:
type: array
items:
type: string
- name: deleted_at_range
description: '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.'
example:
- '2014-05-15T13:35:01-07:00'
- '2014-05-17T13:35:01-07:00'
in: query
required: false
schema:
type: array
items:
type: string
responses:
'200':
description: 'Returns a collection of search results. If there are no matching
search results, the `entries` array will be empty.'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SearchResults'
- $ref: '#/components/schemas/SearchResultsWithSharedLinks'
'400':
description: "Returns an error when the request was not valid. This can have multiple\nreasons and the `context_info` object will provide you with more details.\n\n* `missing_parameter` - Please provide at least the `query` or `mdfilters`\n query parameter in a search.\n* `invalid_parameter` - Any of the fields might not be in the right\n format. This could for example mean that one of the RFC3339 dates is\n incorrect, or a string is provided where an integer is expected."
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: "Returns an error when the user does not have the permission to make\nthis API call.\n\n* The developer provided a `scope` of `enterprise_content` but did\n not request this scope to be enabled for the user through our\n support channels."
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: "Returns an error when the user does not have access to an item\nmentioned in the request.\n\n* The developer provided a folder ID in `ancestor_folder_ids`\n that either does not exist or the user does not have access to."
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
Folder:
title: Folder
type: object
x-box-resource-id: folder
x-box-variant: standard
description: 'A standard representation of a folder, as returned from any
folder API endpoints by default'
allOf:
- $ref: '#/components/schemas/Folder--Mini'
- properties:
created_at:
type: string
format: date-time
nullable: true
description: 'The date and time when the folder was created. This value may
be `null` for some folders such as the root folder or the trash
folder.'
example: '2012-12-12T10:53:43-08:00'
modified_at:
type: string
format: date-time
description: 'The date and time when the folder was last updated. This value may
be `null` for some folders such as the root folder or the trash
folder.'
example: '2012-12-12T10:53:43-08:00'
nullable: true
description:
allOf:
- type: string
description: The optional description of this folder
maxLength: 256
example: Legal contracts for the new ACME deal
nullable: false
- nullable: false
size:
type: integer
format: int64
description: 'The folder size in bytes.
Be careful parsing this integer as its
value can get very large.'
example: 629644
nullable: false
path_collection:
allOf:
- title: Path collection
description: A list of parent folders for an item.
type: object
required:
- total_count
- entries
properties:
total_count:
description: The number of folders in this list.
example: 1
type: integer
format: int64
nullable: false
entries:
type: array
description: The parent folders for this item
nullable: false
items:
$ref: '#/components/schemas/Folder--Mini'
- description: 'The tree of folders that this folder is contained in,
starting at the root.'
- nullable: false
created_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who created this folder
- nullable: false
modified_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who last modified this folder.
- nullable: false
trashed_at:
type: string
format: date-time
description: The time at which this folder was put in the trash.
example: '2012-12-12T10:53:43-08:00'
nullable: true
purged_at:
type: string
format: date-time
description: 'The time at which this folder is expected to be purged
from the trash.'
example: '2012-12-12T10:53:43-08:00'
nullable: true
content_created_at:
type: string
format: date-time
nullable: true
description: 'The date and time at which this folder was originally
created.'
example: '2012-12-12T10:53:43-08:00'
content_modified_at:
type: string
format: date-time
nullable: true
description: The date and time at which this folder was last updated.
example: '2012-12-12T10:53:43-08:00'
owned_by:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user who owns this folder.
- nullable: false
shared_link:
allOf:
- title: Shared link
description: 'Shared links provide direct, read-only access to files or folder on Box.
Shared links with open access level allow anyone with the URL
to access the item, while shared links with company or collaborators access
levels can only be accessed by appropriately authenticated Box users.'
type: object
required:
- url
- accessed
- effective_access
- effective_permission
- is_password_enabled
- download_count
- preview_count
properties:
url:
type: string
format: url
description: 'The URL that can be used to access the item on Box.
This URL will display the item in Box''s preview UI where the file
can be downloaded if allowed.
This URL will continue to work even when a custom `vanity_url`
has been set for this shared link.'
example: https://www.box.com/s/vspke7y05sb214wjokpk
nullable: false
download_url:
type: string
format: url
x-box-premium-feature: true
description: 'A URL that can be used to download the file. This URL can be used in
a browser to download the file. This URL includes the file
extension so that the file will be saved with the right file type.
This property will be `null` for folders.'
example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
nullable: true
vanity_url:
type: string
format: url
description: 'The "Custom URL" that can also be used to preview the item on Box. Custom
URLs can only be created or modified in the Box Web application.'
example: https://acme.app.box.com/v/my_url/
nullable: true
vanity_name:
type: string
description: The custom name of a shared link, as used in the `vanity_url` field.
example: my_url
nullable: true
access:
type: string
description: "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin."
enum:
- open
- company
- collaborators
example: open
nullable: false
effective_access:
type: string
description: 'The effective access level for the shared link. This can be a more
restrictive access level than the value in the `access` field when the
enterprise settings restrict the allowed access levels.'
enum:
- open
- company
- collaborators
example: company
nullable: false
effective_permission:
type: string
description: 'The effective permissions for this shared link.
These result in the more restrictive combination of
the share link permissions and the item permissions set
by the administrator, the owner, and any ancestor item
such as a folder.'
enum:
- can_edit
- can_download
- can_preview
- no_access
example: can_download
nullable: false
unshared_at:
type: string
format: date-time
description: 'The date and time when this link will be unshared. This field can only be
set by users with paid accounts.'
example: '2018-04-13T13:53:23-07:00'
nullable: true
is_password_enabled:
type: boolean
description: Defines if the shared link requires a password to access the item.
example: true
nullable: false
permissions:
type: object
description: 'Defines if this link allows a user to preview, edit, and download an item.
These permissions refer to the shared link only and
do not supersede permissions applied to the item itself.'
required:
- can_download
- can_preview
- can_edit
properties:
can_download:
type: boolean
example: true
nullable: false
description: 'Defines if the shared link allows for the item to be downloaded. For
shared links on folders, this also applies to any items in the folder.
This value can be set to `true` when the effective access level is
set to `open` or `company`, not `collaborators`.'
can_preview:
type: boolean
example: true
nullable: false
description: 'Defines if the shared link allows for the item to be previewed.
This value is always `true`. For shared links on folders this also
applies to any items in the folder.'
can_edit:
type: boolean
example: false
nullable: false
description: 'Defines if the shared link allows for the item to be edited.
This value can only be `true` if `can_download` is also `true` and if
the item has a type of `file`.'
download_count:
type: integer
example: 3
description: The number of times this item has been downloaded.
nullable: false
preview_count:
type: integer
example: 3
description: The number of times this item has been previewed.
nullable: false
- description: 'The sha
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-search-api-openapi.yml