openapi: 3.1.0 info: 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 shared link for this folder. This will be `null` if no shared link has been created for this folder.' nullable: true folder_upload_email: type: object nullable: true properties: access: type: string example: open nullable: false enum: - open - collaborators description: 'When this parameter has been set, users can email files to the email address that has been automatically created for this folder. To create an email address, set this property either when creating or updating the folder. When set to `collaborators`, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered. When set to `open` it will accept emails from any email address.' email: description: The optional upload email address for this folder. type: string format: email example: upload.Contracts.asd7asd@u.box.com nullable: false parent: allOf: - $ref: '#/components/schemas/Folder--Mini' - description: 'The optional folder that this folder is located within. This value may be `null` for some folders such as the root folder or the trash folder.' nullable: true item_status: type: string description: 'Defines if this item has been deleted or not. * `active` when the item has is not in the trash * `trashed` when the item has been moved to the trash but not deleted * `deleted` when the item has been permanently deleted.' enum: - active - trashed - deleted nullable: false example: active item_collection: allOf: - $ref: '#/components/schemas/Items' - description: 'A page of the items that are in the folder. This field can only be requested when querying a folder''s information, not when querying a folder''s items.' - nullable: false File: title: File type: object x-box-resource-id: file x-box-variant: standard description: 'A standard representation of a file, as returned from any file API endpoints by default' allOf: - $ref: '#/components/schemas/File--Mini' - properties: description: type: string nullable: false description: The optional description of this file maxLength: 256 example: Contract for Q1 renewal size: type: integer nullable: false description: 'The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.' example: 629644 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 file is contained in, starting at the root.' - nullable: false created_at: type: string format: date-time nullable: false description: The date and time when the file was created on Box. example: '2012-12-12T10:53:43-08:00' modified_at: type: string format: date-time nullable: false description: The date and time when the file was last updated on Box. example: '2012-12-12T10:53:43-08:00' trashed_at: type: string format: date-time description: The time at which this file 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 file 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 file was originally created, which might be before it was uploaded to Box.' 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 file was last updated, which might be before it was uploaded to Box.' example: '2012-12-12T10:53:43-08:00' created_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who created this file modified_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who last modified this file - nullable: false owned_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who owns this file - 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 shared link for this file. This will be `null` if no shared link has been created for this file.' - nullable: true parent: allOf: - $ref: '#/components/schemas/Folder--Mini' - description: The folder that this file is located within. nullable: true item_status: type: string description: 'Defines if this item has been deleted or not. * `active` when the item has is not in the trash * `trashed` when the item has been moved to the trash but not deleted * `deleted` when the item has been permanently deleted.' enum: - active - trashed - deleted nullable: false example: active User--Base: title: User (Base) type: object x-box-resource-id: user--base x-box-tag: users x-box-variants: - base - mini - standard - full x-box-variant: base description: 'A mini representation of a user, used when nested within another resource.' required: - type - id properties: id: type: string description: The unique identifier for this user example: '11446498' type: type: string description: '`user`' example: user nullable: false enum: - user WebLink: title: Web link type: object x-box-resource-id: web_link x-box-variant: standard description: 'Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.' allOf: - $ref: '#/components/schemas/WebLink--Mini' - properties: parent: allOf: - $ref: '#/components/schemas/Folder--Mini' - description: The parent object the web link belongs to description: type: string example: Example page description: 'The description accompanying the web link. This is visible within the Box web application.' 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 web link is contained in, starting at the root.' - nullable: false created_at: type: string format: date-time description: When this file was created on Box’s servers. example: '2012-12-12T10:53:43-08:00' modified_at: type: string format: date-time description: 'When this file was last updated on the Box servers.' example: '2012-12-12T10:53:43-08:00' trashed_at: type: string format: date-time nullable: true description: When this file was moved to the trash. example: '2012-12-12T10:53:43-08:00' purged_at: type: string format: date-time nullable: true description: When this file will be permanently deleted. example: '2012-12-12T10:53:43-08:00' created_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who created this web link modified_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who last modified this web link owned_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who owns this web link 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 shared link object for this item. Will be `null` if no shared link has been created.' - nullable: true item_status: type: string example: active enum: - active - trashed - deleted description: 'Whether this item is deleted or not. Values include `active`, `trashed` if the file has been moved to the trash, and `deleted` if the file has been permanently deleted' MetadataQuery: title: Metadata query search request type: object description: 'Create a search using SQL-like syntax to return items that match specific metadata.' required: - from - ancestor_folder_id properties: from: type: string description: 'Specifies the template used in the query. Must be in the form `scope.templateKey`. Not all templates can be used in this field, most notably the built-in, Box-provided classification templates can not be used in a query.' example: enterprise_123456.someTemplate query: type: string description: 'The query to perform. A query is a logical expression that is very similar to a SQL `SELECT` statement. Values in the search query can be turned into parameters specified in the `query_param` arguments list to prevent having to manually insert search values into the query string. For example, a value of `:amount` would represent the `amount` value in `query_params` object.' example: value >= :amount query_params: type: object description: 'Set of arguments corresponding to the parameters specified in the `query`. The type of each parameter used in the `query_params` must match the type of the corresponding metadata template field.' example: amount: '100' additionalProperties: type: string description: 'The value for the argument being used in the metadata search. The type of this parameter must match the type of the corresponding metadata template field.' example: '100' x-box-example-key: amount ancestor_folder_id: type: string description: 'The ID of the folder that you are restricting the query to. A value of zero will return results from all folders you have access to. A non-zero value will only return results found in the folder corresponding to the ID or in any of its subfolders.' example: '0' order_by: type: array description: 'A list of template fields and directions to sort the metadata query results by. The ordering `direction` must be the same for each item in the array.' items: type: object description: 'An object representing one of the metadata template fields to sort the metadata query results by.' properties: field_key: type: string description: 'The metadata template field to order by. The `field_key` represents the `key` value of a field from the metadata template being searched for.' example: amount direction: type: string description: 'The direction to order by, either ascending or descending. The `ordering` direction must be the same for each item in the array.' example: asc enum: - ASC - DESC - asc - desc limit: type: integer description: 'A value between 0 and 100 that indicates the maximum number of results to return for a single request. This only specifies a maximum boundary and will not guarantee the minimum number of results returned.' default: 100 minimum: 0 maximum: 100 example: 50 marker: type: string description: Marker to use for requesting the next page. example: AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff fields: type: array items: type: string description: 'By default, this endpoint returns only the most basic info about the items for which the query matches. This attribute can be used to specify a list of additional attributes to return for any item, including its metadata. This attribute takes a list of item fields, metadata template identifiers, or metadata template field identifiers. For example: * `created_by` will add the details of the user who created the item to the response. * `metadata..` will return the mini-representation of the metadata instance identified by the `scope` and `templateKey`. * `metadata...` will return all the mini-representation of the metadata instance identified by the `scope` and `templateKey` plus the field specified by the `field` name. Multiple fields for the same `scope` and `templateKey` can be defined.' example: - extension - created_at - item_status - metadata.enterprise_1234.contracts - metadata.enterprise_1234.regions.location MetadataFieldFilterDateRange: title: Metadata field filter (date range) type: object x-box-resource-id: metadata_field_filter_date_range description: 'Specifies which `date` field on the template to filter the search results by, specifying a range of dates that can match.' example: expirationDate: lt: '2017-08-01T00:00:00Z' gt: '2016-08-01T00:00:00Z' additionalProperties: type: object description: Match a `date` metadata field to a range of values. example: lt: '2017-08-01T00:00:00Z' gt: '2016-08-01T00:00:00Z' x-box-example-key: expirationDate properties: lt: description: 'Specifies the (inclusive) upper bound for the metadata field value. The value of a field must be lower than (`lt`) or equal to this value for the search query to match this template.' type: string format: date-time example: '2017-08-01T00:00:00Z' gt: description: 'Specifies the (inclusive) lower bound for the metadata field value. The value of a field must be greater than (`gt`) or equal to this value for the search query to match this template.' type: string format: date-time example: '2016-08-01T00:00:00Z' FileOrFolderScope: title: File or folder scope type: object description: A relation between a resource (file or folder) and the scopes for which the resource can be accessed properties: scope: type: string description: The scopes for the resource access example: item_download enum: - annotation_edit - annotation_view_all - annotation_view_self - base_explorer - base_picker - base_preview - base_upload - item_delete - item_download - item_preview - item_rename - item_share object: allOf: - oneOf: - $ref: '#/components/schemas/Folder--Mini' - $ref: '#/components/schemas/File--Mini' - description: The file or folder resource MetadataFieldFilterMultiSelect: title: Metadata field filter (multi-select) type: object x-box-resource-id: metadata_field_filter_multi_select description: 'Specifies the values to match for a `multiSelect` metadata field. When performing a search, the query will essentially perform an `OR` operation to match any template where any of the provided values match this field.' example: category: - online - enterprise additionalProperties: type: array description: 'A mapping between a metadata `multiSelect` field key and the one or more values to match search results on. When performing a search, the query will essentially perform an `OR` operation to match any template where any of the provided values match this field.' example: - online - enterprise items: type: string x-box-example-key: category Metadata--Base: title: Metadata instance (Base) type: object x-box-resource-id: metadata--base x-box-sanitized: true x-box-tag: file_metadata x-box-variants: - base - standard - full x-box-variant: base description: The base representation of a metadata instance. properties: $parent: type: string example: folder_59449484661, description: 'The identifier of the item that this metadata instance has been attached to. This combines the `type` and the `id` of the parent in the form `{type}_{id}`.' $template: type: string example: marketingCollateral description: The name of the template $scope: type: string example: enterprise_27335 description: 'An ID for the scope in which this template has been applied. This will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box.' $version: type: integer example: 1 description: 'The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.' WebLink--Mini: title: Web link (Mini) type: object x-box-resource-id: web_link--mini x-box-variant: mini description: 'Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.' allOf: - $ref: '#/components/schemas/WebLink--Base' - properties: url: type: string example: https://www.example.com/example/1234 description: The URL this web link points to sequence_id: allOf: - type: string example: '3' nullable: true description: 'A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.' - nullable: false name: type: string description: The name of the web link example: My Bookmark SearchResultsWithSharedLinks: title: Search Results (including Shared Links) type: object x-box-resource-id: search_results_with_shared_links x-box-tag: search description: 'A list of files, folders and web links that matched the search query, including the additional information about any shared links through which the item has been shared with the user. This response format is only returned when the `include_recent_shared_links` query parameter has been set to `true`.' required: - type allOf: - type: object properties: total_count: description: 'One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than `total_count`.' example: 5000 type: integer format: int64 limit: description: 'The limit that was used for this search. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed.' example: 1000 type: integer format: int64 offset: description: 'The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter used.' example: 2000 type: integer format: int64 - properties: type: description: Specifies the response as search result items with shared links type: string example: search_results_with_shared_links enum: - search_results_with_shared_links nullable: false entries: description: 'The search results for the query provided, including the additional information about any shared links through which the item has been shared with the user.' type: array items: $ref: '#/components/schemas/SearchResultWithSharedLink' Metadata: title: Metadata instance type: object x-box-resource-id: metadata x-box-tag: file_metadata x-box-variant: standard description: 'An instance of a metadata template, which has been applied to a file or folder.' allOf: - $ref: '#/components/schemas/Metadata--Base' MetadataFieldFilterFloatRange: title: Metadata field filter (float range) type: object x-box-resource-id: metadata_field_filter_float_range description: 'Specifies which `float` field on the template to filter the search results by, specifying a range of values that can match.' example: contractValue: gt: 100000 lt: 200000 additionalProperties: type: object description: 'Specifies which `float` field on the template to filter the search results by, specifying a range of values that can match.' example: gt: 100000 lt: 200000 x-box-example-key: value properties: lt: description: 'Specifies the (inclusive) upper bound for the metadata field value. The value of a field must be lower than (`lt`) or equal to this value for the search query to match this template.' type: number example: 200000 gt: description: 'Specifies the (inclusive) lower bound for the metadata field value. The value of a field must be greater than (`gt`) or equal to this value for the search query to match this template.' type: number example: 100000 SearchResults: title: Search Results type: object x-box-resource-id: search_results x-box-tag: search description: A list of files, folders and web links that matched the search query. required: - type allOf: - type: object properties: total_count: description: 'One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than `total_count`.' example: 5000 type: integer format: int64 limit: description: 'The limit that was used for this search. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed.' example: 1000 type: integer format: int64 offset: description: 'The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter used.' example: 2000 type: integer format: int64 - properties: type: description: Specifies the response as search result items without shared links type: string example: search_results_items enum: - search_results_items nullable: false entries: description: The search results for the query provided. type: array items: oneOf: - $ref: '#/components/schemas/File--Full' - $ref: '#/components/schemas/Folder--Full' - $ref: '#/components/schemas/WebLink' MetadataFieldFilterFloat: title: Metadata field filter (float) type: object x-box-resource-id: metadata_field_filter_float description: 'Specifies which `float` field on the template to filter the search results by.' example: contractValue: 10000 additionalProperties: type: number description: 'A mapping between a metadata `float` field key and the value to match search results on.' example: 10000 x-box-example-key: contractValue Folder--Full: title: Folder (Full) type: object x-box-resource-id: folder--full x-box-variant: full description: 'A full representation of a folder, as can be returned from any folder API endpoints by default' allOf: - $ref: '#/components/schemas/Folder' - properties: sync_state: allOf: - type: string example: synced nullable: false description: 'Specifies whether a folder should be synced to a user''s device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.' enum: - synced - not_synced - partially_synced has_collaborations: type: boolean example: true nullable: false description: Specifies if this folder has any other collaborators. permissions: allOf: - type: object description: The permissions that the authenticated user has for a folder. required: - can_upload allOf: - type: object description: The permissions that the authenticated user has for an item. required: - can_delete - can_download - can_invite_collaborator - can_rename - can_set_share_access - can_share properties: can_delete: type: boolean description: Specifies if the current user can delete this item. example: true nullable: false can_download: type: boolean description: Specifies if the current user can download this item. example: true nullable: false can_invite_collaborator: type: boolean description: 'Specifies if the current user can invite new users to collaborate on this item, and if the user can update the role of a user already collaborated on this item.' example: true nullable: false can_rename: type: boolean description: Specifies if the user can rename this item. example: true nullable: false can_set_share_access: type: boolean description: 'Specifies if the user can change the access level of an existing shared link on this item.' example: true nullable: false can_share: type: boolean description: Specifies if the user can create a shared link for this item. example: true nullable: false - properties: can_upload: type: boolean description: Specifies if the user can upload into this folder. example: true nullable: false - description: 'Describes the permissions that the current user has for this folder' - nullable: false tags: allOf: - type: array example: - approved items: type: string minItems: 1 maxItems: 100 description: 'The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item''s current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.' - nullable: false can_non_owners_invite: allOf: - type: boolean example: true description: 'Specifies if users who are not the owner of the folder can invite new collaborators to the folder.' - nullable: false is_externally_owned: type: boolean example: true nullable: false description: 'Specifies if this folder is owned by a user outside of the authenticated enterprise.' metadata: allOf: - title: Item metadata instances type: object description: 'A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`. To access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise. Then use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID. To request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata..` For example, `?fields=metadata.enterprise_27335.marketingCollateral`.' example: 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 additionalProperties: type: object description: 'A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`.' example: 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 additionalProperties: $ref: '#/components/schemas/Metadata' - description: 'An object containing the metadata instances that have been attached to this folder. Each metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each folder. Each metadata instance is nested within an object with the `templateKey` as the key, which again itself is nested in an object with the `scope` as the key.' is_collaboration_restricted_to_enterprise: allOf: - type: boolean example: true description: 'Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.' - nullable: false allowed_shared_link_access_levels: type: array example: - open items: type: string enum: - open - company - collaborators nullable: false description: 'A list of access levels that are available for this folder. For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level.' allowed_invitee_roles: type: array example: - editor nullable: false description: 'A list of the types of roles that user can be invited at when sharing this folder.' items: type: string enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner watermark_info: allOf: - type: object description: Details about the watermark applied to this item properties: is_watermarked: type: boolean description: Specifies if this item has a watermark applied. example: true nullable: false - description: Details about the watermark applied to this folder - nullable: false is_accessible_via_shared_link: type: boolean description: 'Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.' example: true enum: - true - false can_non_owners_view_collaborators: type: boolean example: true description: 'Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators.' classification: allOf: - type: object description: The classification applied to an item properties: name: type: string example: Top Secret description: The name of the classification definition: type: string example: Content that should not be shared outside the company. description: An explanation of the meaning of this classification. color: type: string example: '#FF0000' description: 'The color that is used to display the classification label in a user-interface. Colors are defined by the admin or co-admin who created the classification in the Box web app.' - description: Details about the classification applied to this folder. - nullable: true Folder--Mini: title: Folder (Mini) type: object x-box-resource-id: folder--mini x-box-variant: mini description: 'A mini representation of a file version, used when nested under another resource.' allOf: - $ref: '#/components/schemas/Folder--Base' - properties: sequence_id: allOf: - type: string example: '3' nullable: true description: 'A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.' - nullable: false name: type: string description: The name of the folder. example: Contracts nullable: false File--Base: title: File (Base) type: object x-box-resource-id: file--base x-box-sanitized: true x-box-tag: files x-box-variants: - base - mini - standard - full x-box-variant: base nullable: true description: 'The bare basic representation of a file, the minimal amount of fields returned when using the `fields` query parameter.' required: - id - type properties: id: type: string nullable: false description: 'The unique identifier that represent a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`.' example: '12345' etag: type: string example: '1' nullable: true description: 'The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened.' type: type: string description: '`file`' example: file enum: - file nullable: false FileVersion--Mini: title: File version (Mini) type: object x-box-resource-id: file_version--mini x-box-variant: mini description: 'A mini representation of a file version, used when nested within another resource.' allOf: - $ref: '#/components/schemas/FileVersion--Base' - properties: sha1: type: string description: The SHA1 hash of this version of the file. example: 134b65991ed521fcfe4724b7d814ab8ded5185dc File--Mini: title: File (Mini) type: object x-box-resource-id: file--mini x-box-variant: mini description: 'A mini representation of a file, used when nested under another resource.' nullable: true allOf: - $ref: '#/components/schemas/File--Base' - properties: sequence_id: allOf: - type: string example: '3' nullable: true description: 'A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.' - nullable: false name: type: string description: The name of the file example: Contract.pdf sha1: type: string format: digest nullable: false example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37 description: 'The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file.' file_version: allOf: - $ref: '#/components/schemas/FileVersion--Mini' - description: The information about the current version of the file. File--Full: title: File (Full) type: object x-box-resource-id: file--full x-box-variant: full description: 'A full representation of a file, as can be returned from any file API endpoints by default' allOf: - $ref: '#/components/schemas/File' - properties: version_number: type: string example: '1' description: The version number of this file comment_count: type: integer example: 10 description: The number of comments on this file permissions: allOf: - type: object description: The permissions that the authenticated user has for a file. required: - can_annotate - can_comment - can_preview - can_upload - can_view_annotations_all - can_view_annotations_self allOf: - type: object description: The permissions that the authenticated user has for an item. required: - can_delete - can_download - can_invite_collaborator - can_rename - can_set_share_access - can_share properties: can_delete: type: boolean description: Specifies if the current user can delete this item. example: true nullable: false can_download: type: boolean description: Specifies if the current user can download this item. example: true nullable: false can_invite_collaborator: type: boolean description: 'Specifies if the current user can invite new users to collaborate on this item, and if the user can update the role of a user already collaborated on this item.' example: true nullable: false can_rename: type: boolean description: Specifies if the user can rename this item. example: true nullable: false can_set_share_access: type: boolean description: 'Specifies if the user can change the access level of an existing shared link on this item.' example: true nullable: false can_share: type: boolean description: Specifies if the user can create a shared link for this item. example: true nullable: false - properties: can_annotate: type: boolean description: Specifies if the user can place annotations on this file. example: true nullable: false can_comment: type: boolean description: Specifies if the user can place comments on this file. example: true nullable: false can_preview: type: boolean description: Specifies if the user can preview this file. example: true nullable: false can_upload: type: boolean description: Specifies if the user can upload a new version of this file. example: true nullable: false can_view_annotations_all: type: boolean description: Specifies if the user view all annotations placed on this file example: true nullable: false can_view_annotations_self: type: boolean description: 'Specifies if the user view annotations placed by themselves on this file' example: true nullable: false - description: 'Describes the permissions that the current user has for this file.' - nullable: false tags: allOf: - type: array example: - approved items: type: string minItems: 1 maxItems: 100 description: 'The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item''s current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.' - nullable: false lock: allOf: - title: Lock type: object description: 'The lock held on a file. A lock prevents a file from being moved, renamed, or otherwise changed by anyone else than the user who created the lock.' properties: id: type: string description: The unique identifier for this lock example: '11446498' type: type: string description: '`lock`' example: lock enum: - lock created_by: allOf: - $ref: '#/components/schemas/User--Mini' - description: The user who created the lock. created_at: type: string format: date-time example: '2012-12-12T10:53:43-08:00' description: The time this lock was created at. expired_at: type: string format: date-time example: '2012-12-12T10:53:43-08:00' description: The time this lock is to expire at, which might be in the past. is_download_prevented: type: boolean example: true description: Whether or not the file can be downloaded while locked. app_type: type: string description: 'If the lock is managed by an application rather than a user, this field identifies the type of the application that holds the lock. This is an open enum and may be extended with additional values in the future.' enum: - gsuite - office_wopi - office_wopiplus - other example: office_wopiplus nullable: true - description: 'The lock held on this file. If there is no lock, this can either be `null` or have a timestamp in the past.' nullable: true extension: type: string example: pdf description: 'Indicates the (optional) file extension for this file. By default, this is set to an empty string.' is_package: type: boolean example: true description: 'Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.' expiring_embed_link: allOf: - title: Expiring embed link type: object description: An expiring Box Embed Link. allOf: - type: object description: The basics of an access token properties: access_token: type: string format: token example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ description: The requested access token. expires_in: type: integer format: int64 example: 3600 description: The time in seconds by which this token will expire. token_type: type: string enum: - bearer example: bearer description: The type of access token returned. restricted_to: type: array description: 'The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources.' items: $ref: '#/components/schemas/FileOrFolderScope' - properties: url: type: string format: url example: https://cloud.app.box.com/preview/expiring_embed/... description: 'The actual expiring embed URL for this file, constructed from the file ID and access tokens specified in this object.' - description: 'Requesting this field creates an expiring Box Embed URL for an embedded preview session in an `iframe`. This URL will expire after 60 seconds and the session will expire after 60 minutes. Not all file types are supported for these embed URLs. Box Embed is not optimized for mobile browsers and should not be used in web experiences designed for mobile devices. Many UI elements, like the **download** and **print** options might not show in mobile browsers.' watermark_info: allOf: - type: object description: Details about the watermark applied to this item properties: is_watermarked: type: boolean description: Specifies if this item has a watermark applied. example: true nullable: false - description: Details about the watermark applied to this file is_accessible_via_shared_link: type: boolean description: 'Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder.' example: true enum: - true - false allowed_invitee_roles: type: array example: - editor nullable: false description: 'A list of the types of roles that user can be invited at when sharing this file.' items: type: string enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner is_externally_owned: type: boolean example: true nullable: false description: 'Specifies if this file is owned by a user outside of the authenticated enterprise.' has_collaborations: type: boolean example: true nullable: false description: Specifies if this file has any other collaborators. metadata: allOf: - title: Item metadata instances type: object description: 'A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`. To access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise. Then use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID. To request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata..` For example, `?fields=metadata.enterprise_27335.marketingCollateral`.' example: 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 additionalProperties: type: object description: 'A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`.' example: 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 additionalProperties: $ref: '#/components/schemas/Metadata' - description: 'An object containing the metadata instances that have been attached to this file. Each metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each file. Each metadata instance is nested within an object with the `templateKey` as the key, which again itself is nested in an object with the `scope` as the key.' expires_at: type: string format: date-time nullable: true description: When the file will automatically be deleted example: '2012-12-12T10:53:43-08:00' representations: allOf: - title: Representations description: A list of file representations type: object properties: entries: type: array description: A list of files items: type: object description: A file representation properties: content: type: object description: 'An object containing the URL that can be used to actually fetch the representation.' properties: url_template: type: string example: https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567 description: "The download URL that can be used to fetch the representation.\nMake sure to make an authenticated API call to this endpoint.\n\nThis URL is a template and will require the `{+asset_path}` to\nbe replaced by a path. In general, for unpaged representations\nit can be replaced by an empty string.\n\nFor paged representations, replace the `{+asset_path}` with the\npage to request plus the extension for the file, for example\n`1.pdf`.\n\nWhen requesting the download URL the following additional\nquery params can be passed along.\n\n* `set_content_disposition_type` - Sets the\n`Content-Disposition` header in the API response with the\nspecified disposition type of either `inline` or `attachment`.\nIf not supplied, the `Content-Disposition` header is not\nincluded in the response.\n\n* `set_content_disposition_filename` - Allows the application to\n define the representation's file name used in the\n `Content-Disposition` header. If not defined, the filename\n is derived from the source file name in Box combined with the\n extension of the representation." info: type: object description: 'An object containing the URL that can be used to fetch more info on this representation.' properties: url: type: string example: https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048 description: 'The API URL that can be used to get more info on this file representation. Make sure to make an authenticated API call to this endpoint.' properties: type: object description: An object containing the size and type of this presentation. properties: dimensions: type: string format: x example: 2048x2048 description: The width by height size of this representation in pixels. paged: type: boolean example: true description: 'Indicates if the representation is build up out of multiple pages.' thumb: type: boolean example: true description: 'Indicates if the representation can be used as a thumbnail of the file.' representation: type: string example: png description: Indicates the file type of the returned representation. status: type: object description: An object containing the status of this representation. properties: state: type: string example: success enum: - success - viewable - pending - none description: "The status of the representation.\n\n* `success` defines the representation as ready to be viewed.\n* `viewable` defines a video to be ready for viewing.\n* `pending` defines the representation as to be generated. Retry\n this endpoint to re-check the status.\n* `none` defines that the representation will be created when\n requested. Request the URL defined in the `info` object to\n trigger this generation." - description: 'A list of representations for a file that can be used to display a placeholder of the file in your application. By default this returns all representations and we recommend using the `x-rep-hints` header to further customize the desired representations.' classification: allOf: - type: object description: The classification applied to an item properties: name: type: string example: Top Secret description: The name of the classification definition: type: string example: Content that should not be shared outside the company. description: An explanation of the meaning of this classification. color: type: string example: '#FF0000' description: 'The color that is used to display the classification label in a user-interface. Colors are defined by the admin or co-admin who created the classification in the Box web app.' - description: Details about the classification applied to this file. - nullable: true uploader_display_name: allOf: - title: Uploader display name type: string example: Ellis Wiggins nullable: false description: 'The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload. If the file was uploaded using a File Request form that requires the user to provide an email address, this field is populated with that email address. If an email address was not required in the File Request form, this field is set to return a value of `File Request`. In all other anonymous cases where no email was provided this field will default to a value of `Someone`.' disposition_at: type: string format: date-time nullable: true description: The retention expiration timestamp for the given file example: '2012-12-12T10:53:43-08:00' shared_link_permission_options: type: array example: - can_preview nullable: true description: 'A list of the types of roles that user can be invited at when sharing this file.' items: type: string enum: - can_preview - can_download - can_edit WebLink--Base: title: Web link (Base) type: object x-box-resource-id: web_link--base x-box-tag: web_links x-box-variants: - base - mini - standard x-box-variant: base description: 'Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.' required: - id - type properties: id: type: string description: The unique identifier for this web link example: '11446498' type: type: string description: '`web_link`' example: web_link enum: - web_link etag: type: string example: '1' description: 'The entity tag of this web link. Used with `If-Match` headers.' FileVersion--Base: title: File version (Base) type: object x-box-resource-id: file_version--base x-box-sanitized: true x-box-variants: - base - mini - standard - full x-box-variant: base description: 'The bare basic representation of a file version, the minimal amount of fields returned when using the `fields` query parameter.' required: - id - type properties: id: type: string nullable: false description: The unique identifier that represent a file version. example: '12345' type: type: string description: '`file_version`' example: file_version enum: - file_version nullable: false ClientError: title: Client error type: object x-box-resource-id: client_error description: A generic error properties: type: description: error example: error type: string enum: - error nullable: false status: description: The HTTP status of the response. example: 400 type: integer format: int32 nullable: false code: description: A Box-specific error code example: item_name_invalid type: string enum: - created - accepted - no_content - redirect - not_modified - bad_request - unauthorized - forbidden - not_found - method_not_allowed - conflict - precondition_failed - too_many_requests - internal_server_error - unavailable - item_name_invalid - insufficient_scope message: description: A short message describing the error. example: Method Not Allowed type: string nullable: false context_info: description: 'A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.' type: object nullable: true properties: message: type: string description: More details on the error. example: Something went wrong. help_url: description: A URL that links to more information about why this error occurred. example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ type: string nullable: false request_id: description: 'A unique identifier for this response, which can be used when contacting Box support.' type: string example: abcdef123456 nullable: false MetadataFieldFilterString: title: Metadata field filter (string) type: object x-box-resource-id: metadata_field_filter_string description: 'Specifies which text field on the template to filter the search results by.' example: category: online additionalProperties: type: string description: 'A mapping between a metadata `string` field key and the value to match search results on.' example: online x-box-example-key: category Items: title: Items type: object x-box-resource-id: items x-box-tag: folders description: 'A list of files, folders, and web links in their mini representation.' allOf: - type: object description: The part of an API response that describes pagination properties: total_count: description: 'One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.' example: 5000 type: integer format: int64 limit: description: 'The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.' example: 1000 type: integer format: int64 offset: description: 'The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.' example: 2000 type: integer format: int64 order: description: 'The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.' type: array items: type: object description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: type: string description: The direction to order by, either ascending or descending example: ASC enum: - ASC - DESC - properties: entries: description: The items in this collection. type: array items: oneOf: - $ref: '#/components/schemas/File--Full' - $ref: '#/components/schemas/Folder--Mini' - $ref: '#/components/schemas/WebLink' Folder--Base: title: Folder (Base) type: object x-box-resource-id: folder--base x-box-sanitized: true x-box-tag: folders x-box-variants: - base - mini - standard - full x-box-variant: base description: 'The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter.' required: - id - type properties: id: type: string nullable: false description: 'The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.' example: '12345' etag: type: string nullable: true example: '1' description: 'The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.' type: type: string description: '`folder`' example: folder enum: - folder nullable: false MetadataQueryResults: title: Metadata query search results type: object x-box-tag: search x-box-resource-id: metadata_query_results description: A page of files and folders that matched the metadata query. properties: entries: description: 'The mini representation of the files and folders that match the search terms. By default, this endpoint returns only the most basic info about the items. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query.' type: array x-box-resource-variant: 1 items: oneOf: - $ref: '#/components/schemas/File' - $ref: '#/components/schemas/Folder' limit: description: 'The limit that was used for this search. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed.' default: 100 example: 100 type: integer format: int64 next_marker: description: The marker for the start of the next page of results. example: 0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ.. type: string MetadataFilter: title: Metadata filter type: object x-box-resource-id: metadata_filter x-box-tag: search description: A metadata template to filter the search results by. properties: scope: description: 'Specifies the scope of the template to filter search results by. This will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box.' type: string example: enterprise enum: - global - enterprise - enterprise_{enterprise_id} templateKey: description: 'The key of the template to filter search results by. In many cases the template key is automatically derived of its display name, for example `Contract Template` would become `contractTemplate`. In some cases the creator of the template will have provided its own template key. Please [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template''s key. [list]: e://get-metadata-templates-enterprise [file]: e://get-files-id-metadata [folder]: e://get-folders-id-metadata' type: string example: contract filters: allOf: - anyOf: - $ref: '#/components/schemas/MetadataFieldFilterString' - $ref: '#/components/schemas/MetadataFieldFilterFloat' - $ref: '#/components/schemas/MetadataFieldFilterMultiSelect' - $ref: '#/components/schemas/MetadataFieldFilterFloatRange' - $ref: '#/components/schemas/MetadataFieldFilterDateRange' - description: 'Specifies which fields on the template to filter the search results by. When more than one field is specified, the query performs a logical `AND` to ensure that the instance of the template matches each of the fields specified.' - example: category: online contractValue: 1000000 User--Mini: title: User (Mini) type: object x-box-resource-id: user--mini x-box-variant: mini description: 'A mini representation of a user, as can be returned when nested within other resources.' allOf: - $ref: '#/components/schemas/User--Base' - properties: name: type: string description: The display name of this user example: Aaron Levie maxLength: 50 nullable: false login: type: string format: email description: The primary email address of this user example: ceo@example.com nullable: false SearchResultWithSharedLink: title: Search Result (including Shared Link) type: object x-box-resource-id: search_result_with_shared_link x-box-tag: search description: 'A single of files, folder or web link that matched the search query, including the additional information about the shared link through which the item has been shared with the user. This response format is only returned when the `include_recent_shared_links` query parameter has been set to `true`.' properties: accessible_via_shared_link: description: 'The optional shared link through which the user has access to this item. This value is only returned for items for which the user has recently accessed the file through a shared link. For all other items this value will return `null`.' example: https://www.box.com/s/vspke7y05sb214wjokpk type: string format: url item: allOf: - oneOf: - $ref: '#/components/schemas/File--Full' - $ref: '#/components/schemas/Folder--Full' - $ref: '#/components/schemas/WebLink' - description: 'The file, folder or web link that matched the search query.' type: description: The result type. The value is always `search_result`. example: search_result type: string