openapi: 3.0.2 servers: - description: Box Platform API server url: https://api.box.com/2.0 info: contact: email: devrel@box.com name: Box, Inc url: https://box.dev x-twitter: BoxHQ description: "[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies." license: name: Apache-2.0 url: http://www.apache.org/licenses/LICENSE-2.0 termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9 title: Box Platform API version: 2.0.0 x-apisguru-categories: - cloud x-logo: url: https://twitter.com/BoxHQ/profile_image?size=original x-origin: - converter: url: https://github.com/mermade/oas-kit version: 7.0.4 format: openapi url: https://opensource.box.com/box-openapi/openapi.json version: "3.0" x-providerName: box.com externalDocs: description: Box Developer Documentation url: https://developer.box.com security: - OAuth2Security: [] tags: - name: Authorization x-box-priority: true x-box-tag: authorization - name: Box Sign x-box-tag: sign_requests - name: Classifications x-box-tag: classifications - name: Classifications on files x-box-tag: file_classifications - name: Classifications on folders x-box-tag: folder_classifications - name: Collaborations x-box-tag: user_collaborations - name: Collaborations (List) x-box-tag: list_collaborations - name: Collections x-box-tag: collections - name: Comments x-box-tag: comments - name: Device pinners x-box-tag: device_pinners - name: Domain restrictions (User exemptions) x-box-tag: collaboration_allowlist_exempt_targets - name: Domain restrictions for collaborations x-box-tag: collaboration_allowlist_entries - name: Downloads x-box-tag: downloads - name: Email aliases x-box-tag: email_aliases - name: Events x-box-tag: events - name: File requests x-box-tag: file_requests - name: File version legal holds x-box-tag: file_version_legal_holds - name: File version retentions x-box-tag: file_version_retentions - name: File versions x-box-tag: file_versions - name: Files x-box-tag: files - name: Folder Locks x-box-tag: folder_locks - name: Folders x-box-tag: folders - name: Group memberships x-box-tag: memberships - name: Groups x-box-tag: groups - name: Invites x-box-tag: invites - name: Legal hold policies x-box-tag: legal_hold_policies - name: Legal hold policy assignments x-box-tag: legal_hold_policy_assignments - name: Metadata cascade policies x-box-tag: metadata_cascade_policies - name: Metadata instances (Files) x-box-tag: file_metadata - name: Metadata instances (Folders) x-box-tag: folder_metadata - name: Metadata templates x-box-tag: metadata_templates - name: Recent items x-box-tag: recent_items - name: Retention policies x-box-tag: retention_policies - name: Retention policy assignments x-box-tag: retention_policy_assignments - name: Search x-box-tag: search - name: Session termination x-box-tag: session_termination - name: Shared links (Files) x-box-tag: shared_links_files - name: Shared links (Folders) x-box-tag: shared_links_folders - name: Shared links (Web Links) x-box-tag: shared_links_web_links - name: Shield information barriers x-box-tag: shield_information_barriers - name: Shield information barrier segments x-box-tag: shield_information_barrier_segments - name: Shield information barrier segment members x-box-tag: shield_information_barrier_segment_members - name: Shield information barrier reports x-box-tag: shield_information_barrier_reports - name: Shield information barrier segment restrictions x-box-tag: shield_information_barrier_segment_restrictions - name: Skills x-box-tag: skills - name: Standard and Zones Storage Policies x-box-tag: storage_policies - name: Standard and Zones Storage Policy Assignments x-box-tag: storage_policy_assignments - name: Task assignments x-box-tag: task_assignments - name: Tasks x-box-tag: tasks - name: Terms of service x-box-tag: terms_of_services - name: Terms of service user statuses x-box-tag: terms_of_service_user_statuses - name: Termination message x-box-tag: termination_message - name: Transfer folders x-box-tag: transfer - name: Trashed files x-box-tag: trashed_files - name: Trashed folders x-box-tag: trashed_folders - name: Trashed items x-box-tag: trashed_items - name: Trashed web links x-box-tag: trashed_web_links - name: Uploads x-box-tag: uploads - name: Uploads (Chunked) x-box-tag: chunked_uploads - name: User avatars x-box-tag: avatars - name: Users x-box-tag: users - name: Watermarks (Files) x-box-tag: file_watermarks - name: Watermarks (Folders) x-box-tag: folder_watermarks - name: Web links x-box-tag: web_links - name: Webhooks x-box-tag: webhooks - name: Workflows x-box-tag: workflows - name: Zip Downloads x-box-tag: zip_downloads paths: /authorize: get: description: |- Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf. This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format. operationId: get_authorize parameters: - description: The type of response we'd like to receive. example: code in: query name: response_type required: true schema: enum: - code format: token type: string - description: |- The Client ID of the application that is requesting to authenticate the user. To get the Client ID for your application, log in to your Box developer console and click the **Edit Application** link for the application you're working with. In the OAuth 2.0 Parameters section of the configuration page, find the item labelled `client_id`. The text of that item is your application's Client ID. example: ly1nj6n11vionaie65emwzk575hnnmrk in: query name: client_id required: true schema: type: string - description: |- The URI to which Box redirects the browser after the user has granted or denied the application permission. This URI match one of the redirect URIs in the configuration of your application. It must be a valid HTTPS URI and it needs to be able to handle the redirection to complete the next step in the OAuth 2.0 flow. Although this parameter is optional, it must be a part of the authorization URL if you configured multiple redirect URIs for the application in the developer console. A missing parameter causes a `redirect_uri_missing` error after the user grants application access. example: http://example.com/auth/callback in: query name: redirect_uri required: false schema: format: url type: string - description: |- A custom string of your choice. Box will pass the same string to the redirect URL when authentication is complete. This parameter can be used to identify a user on redirect, as well as protect against hijacked sessions and other exploits. example: my_state in: query name: state required: false schema: type: string - description: |- A comma-separated list of application scopes you'd like to authenticate the user for. This defaults to all the scopes configured for the application in its configuration page. example: admin_readwrite in: query name: scope required: false schema: type: string responses: "200": content: text/html: schema: format: html type: string description: Does not return any data, but rather should be used in the browser. default: content: text/html: schema: format: html type: string description: Does not return any data, but rather should be used in the browser. security: [] servers: - description: Server for client-side authentication url: https://account.box.com/api/oauth2 summary: Authorize user tags: - Authorization x-box-tag: authorization /collaboration_whitelist_entries: get: description: |- Returns the list domains that have been deemed safe to create collaborations for within the current enterprise. operationId: get_collaboration_whitelist_entries parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/CollaborationAllowlistEntries" description: Returns a collection of domains that are allowed for collaboration. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List allowed collaboration domains tags: - Domain restrictions for collaborations x-box-tag: collaboration_allowlist_entries post: description: |- Creates a new entry in the list of allowed domains to allow collaboration for. operationId: post_collaboration_whitelist_entries requestBody: content: application/json: schema: properties: direction: description: The direction in which to allow collaborations. enum: - inbound - outbound - both example: inbound type: string domain: description: The domain to add to the list of allowed domains. example: example.com type: string required: - domain - direction type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/CollaborationAllowlistEntry" description: Returns a new entry on the list of allowed domains. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add domain to list of allowed collaboration domains tags: - Domain restrictions for collaborations x-box-tag: collaboration_allowlist_entries "/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}": delete: description: |- Removes a domain from the list of domains that have been deemed safe to create collaborations for within the current enterprise. operationId: delete_collaboration_whitelist_entries_id parameters: - description: The ID of the entry in the list. example: "213123" in: path name: collaboration_whitelist_entry_id required: true schema: type: string responses: "204": description: |- A blank response is returned if the entry was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove domain from list of allowed collaboration domains tags: - Domain restrictions for collaborations x-box-tag: collaboration_allowlist_entries get: description: |- Returns a domain that has been deemed safe to create collaborations for within the current enterprise. operationId: get_collaboration_whitelist_entries_id parameters: - description: The ID of the entry in the list. example: "213123" in: path name: collaboration_whitelist_entry_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CollaborationAllowlistEntry" description: Returns an entry on the list of allowed domains. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get allowed collaboration domain tags: - Domain restrictions for collaborations x-box-tag: collaboration_allowlist_entries /collaboration_whitelist_exempt_targets: get: description: |- Returns a list of users who have been exempt from the collaboration domain restrictions. operationId: get_collaboration_whitelist_exempt_targets parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/CollaborationAllowlistExemptTargets" description: Returns a collection of user exemptions. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List users exempt from collaboration domain restrictions tags: - Domain restrictions (User exemptions) x-box-tag: collaboration_allowlist_exempt_targets post: description: |- Exempts a user from the restrictions set out by the allowed list of domains for collaborations. operationId: post_collaboration_whitelist_exempt_targets requestBody: content: application/json: schema: properties: user: description: The user to exempt. properties: id: description: The ID of the user to exempt. example: "23522323" type: string required: - id type: object required: - user type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/CollaborationAllowlistExemptTarget" description: Returns a new exemption entry. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create user exemption from collaboration domain restrictions tags: - Domain restrictions (User exemptions) x-box-tag: collaboration_allowlist_exempt_targets "/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}": delete: description: |- Removes a user's exemption from the restrictions set out by the allowed list of domains for collaborations. operationId: delete_collaboration_whitelist_exempt_targets_id parameters: - description: The ID of the exemption to the list. example: "984923" in: path name: collaboration_whitelist_exempt_target_id required: true schema: type: string responses: "204": description: |- A blank response is returned if the exemption was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove user from list of users exempt from domain restrictions tags: - Domain restrictions (User exemptions) x-box-tag: collaboration_allowlist_exempt_targets get: description: |- Returns a users who has been exempt from the collaboration domain restrictions. operationId: get_collaboration_whitelist_exempt_targets_id parameters: - description: The ID of the exemption to the list. example: "984923" in: path name: collaboration_whitelist_exempt_target_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CollaborationAllowlistExemptTarget" description: Returns the user's exempted from the list of collaboration domains. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get user exempt from collaboration domain restrictions tags: - Domain restrictions (User exemptions) x-box-tag: collaboration_allowlist_exempt_targets /collaborations: get: description: Retrieves all pending collaboration invites for this user. operationId: get_collaborations parameters: - description: The status of the collaborations to retrieve example: pending in: query name: status required: true schema: enum: - pending type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/Collaborations" description: |- Returns a collection of pending collaboration objects. If the user has no pending collaborations, the collection will be empty. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List pending collaborations tags: - Collaborations (List) x-box-tag: list_collaborations post: description: |- Adds a collaboration for a single user or a single group to a file or folder. Collaborations can be created using email address, user IDs, or a group IDs. If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited. If collaboration is in `pending` status, the following fields are redacted: - `login` and `name` are hidden if a collaboration was created using `user_id`, - `name` is hidden if a collaboration was created using `login`. operationId: post_collaborations parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Determines if users should receive email notification for the action performed. example: true in: query name: notify required: false schema: type: boolean requestBody: content: application/json: schema: properties: accessible_by: description: The user or group to give access to the item. properties: id: description: |- The ID of the user or group. Alternatively, use `login` to specify a user by email address. example: "23522323" type: string login: description: |- The email address of the user to grant access to the item. Alternatively, use `id` to specify a user by user ID. example: john@example.com type: string type: description: The type of collaborator to invite. enum: - user - group example: user type: string required: - type type: object can_view_path: description: |- Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's **All Files** page. We recommend you limit the number of collaborations with `can_view_path` enabled to 1,000 per user. Only owner or co-owners can invite collaborators with a `can_view_path` of `true`. `can_view_path` can only be used for folder collaborations. example: true type: boolean expires_at: description: |- Set the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting has been enabled in the **Enterprise Settings** of the **Admin Console**. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error. example: 2019-08-29T23:59:00-07:00 format: date-time type: string item: description: The item to attach the comment to. properties: id: description: The ID of the item that will be granted access to example: "11446498" type: string type: description: |- The type of the item that this collaboration will be granted access to enum: - file - folder example: file type: string required: - id - type type: object role: description: The level of access granted. enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner example: editor type: string required: - item - accessible_by - role type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Collaboration" description: Returns a new collaboration object. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user does not have the right permissions to create the collaboration. * `forbidden_by_policy`: Creating a collaboration is forbidden due to information barrier restrictions. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create collaboration tags: - Collaborations x-box-tag: user_collaborations "/collaborations/{collaboration_id}": delete: description: Deletes a single collaboration. operationId: delete_collaborations_id parameters: - description: The ID of the collaboration example: "1234" in: path name: collaboration_id required: true schema: type: string responses: "204": description: |- A blank response is returned if the collaboration was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove collaboration tags: - Collaborations x-box-tag: user_collaborations get: description: Retrieves a single collaboration. operationId: get_collaborations_id parameters: - description: The ID of the collaboration example: "1234" in: path name: collaboration_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Collaboration" description: Returns a collaboration object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get collaboration tags: - Collaborations x-box-tag: user_collaborations put: description: |- Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. operationId: put_collaborations_id parameters: - description: The ID of the collaboration example: "1234" in: path name: collaboration_id required: true schema: type: string requestBody: content: application/json: schema: properties: can_view_path: description: |- Determines if the invited users can see the entire parent path to the associated folder. The user will not gain privileges in any parent folder and therefore can not see content the user is not collaborated on. Be aware that this meaningfully increases the time required to load the invitee's **All Files** page. We recommend you limit the number of collaborations with `can_view_path` enabled to 1,000 per user. Only owner or co-owners can invite collaborators with a `can_view_path` of `true`. `can_view_path` can only be used for folder collaborations. example: true type: boolean expires_at: description: |- Update the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item. This feature will only work if the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting has been enabled in the **Enterprise Settings** of the **Admin Console**. When the setting is not enabled, collaborations can not have an expiry date and a value for this field will be result in an error. Additionally, a collaboration can only be given an expiration if it was created after the **Automatically remove invited collaborator** setting was enabled. example: 2019-08-29T23:59:00-07:00 format: date-time type: string role: description: The level of access granted. enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner - owner example: editor type: string status: description: |- Set the status of a `pending` collaboration invitation, effectively accepting, or rejecting the invite. enum: - pending - accepted - rejected example: accepted type: string required: - role type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Collaboration" description: Returns an updated collaboration object unless the owner has changed. "204": content: application/json: schema: $ref: "#/components/schemas/Collaboration" description: |- If the role is changed to `owner`, the collaboration is deleted and a new collaboration is created. The previous `owner` of the old collaboration will be a `co-owner` on the new collaboration. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the authenticated user does not have the right permissions to update the collaboration. Additionally, this error may occur when attempting to update the `expires_at` field for the collaboration without the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting enabled in the admin dashboard of the enterprise. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update collaboration tags: - Collaborations x-box-tag: user_collaborations /collections: get: description: |- Retrieves all collections for a given user. Currently, only the `favorites` collection is supported. operationId: get_collections parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/Collections" description: Returns all collections for the given user default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List all collections tags: - Collections x-box-tag: collections "/collections/{collection_id}/items": get: description: |- Retrieves the files and/or folders contained within this collection. operationId: get_collections_id_items parameters: - description: The ID of the collection. example: "926489" in: path name: collection_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/Items" description: Returns an array of items in the collection. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List collection items tags: - Collections x-box-tag: collections /comments: post: description: |- Adds a comment by the user to a specific file, or as a reply to an other comment. operationId: post_comments parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: item: description: The item to attach the comment to. properties: id: description: The ID of the item example: "11446498" type: string type: description: The type of the item that this comment will be placed on. enum: - file - comment example: file type: string required: - id - type type: object message: description: |- The text of the comment. To mention a user, use the `tagged_message` parameter instead. example: Review completed! type: string tagged_message: description: |- The text of the comment, including `@[user_id:name]` somewhere in the message to mention another user, which will send them an email notification, letting them know they have been mentioned. The `user_id` is the target user's ID, where the `name` can be any custom phrase. In the Box UI this name will link to the user's profile. If you are not mentioning another user, use `message` instead. example: "@[1234:John] Review completed!" type: string required: - message type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Comment" description: |- Returns the newly created comment object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create comment tags: - Comments x-box-tag: comments "/comments/{comment_id}": delete: description: Permanently deletes a comment. operationId: delete_comments_id parameters: - description: The ID of the comment. example: "12345" in: path name: comment_id required: true schema: type: string responses: "204": description: Returns an empty response when the comment has been deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove comment tags: - Comments x-box-tag: comments get: description: |- Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment. operationId: get_comments_id parameters: - description: The ID of the comment. example: "12345" in: path name: comment_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Comment--Full" description: Returns a full comment object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get comment tags: - Comments x-box-tag: comments put: description: Update the message of a comment. operationId: put_comments_id parameters: - description: The ID of the comment. example: "12345" in: path name: comment_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: message: description: The text of the comment to update example: Review completed! type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Comment--Full" description: Returns the updated comment object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update comment tags: - Comments x-box-tag: comments "/device_pinners/{device_pinner_id}": delete: description: Deletes an individual device pin. operationId: delete_device_pinners_id parameters: - description: The ID of the device pin example: "2324234" in: path name: device_pinner_id required: true schema: type: string responses: "204": description: Returns an empty response when the pin has been deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove device pin tags: - Device pinners x-box-tag: device_pinners get: description: Retrieves information about an individual device pin. operationId: get_device_pinners_id parameters: - description: The ID of the device pin example: "2324234" in: path name: device_pinner_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/DevicePinner" description: Returns information about a single device pin. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get device pin tags: - Device pinners x-box-tag: device_pinners "/enterprises/{enterprise_id}/device_pinners": get: description: |- Retrieves all the device pins within an enterprise. The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call. operationId: get_enterprises_id_device_pinners parameters: - description: The ID of the enterprise example: "3442311" in: path name: enterprise_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. example: ASC in: query name: direction required: false schema: enum: - ASC - DESC type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/DevicePinners" description: Returns a list of device pins for a given enterprise. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List enterprise device pins tags: - Device pinners x-box-tag: device_pinners /events: get: description: |- Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked. operationId: get_events parameters: - description: |- Defines the type of events that are returned * `all` returns everything for a user and is the default * `changes` returns events that may cause file tree changes such as file updates or collaborations. * `sync` is similar to `changes` but only applies to synced folders * `admin_logs` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for programmatically pulling from a 1 year history of events across all users within the enterprise and within a `created_after` and `created_before` time frame. The complete history of events will be returned in chronological order based on the event time, but latency will be much higher than `admin_logs_streaming`. * `admin_logs_streaming` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for polling for recent events across all users within the enterprise. Latency will be much lower than `admin_logs`, but events will not be returned in chronological order and may contain duplicates. example: all in: query name: stream_type schema: default: all enum: - all - changes - sync - admin_logs - admin_logs_streaming type: string - description: |- The location in the event stream to start receiving events from. * `now` will return an empty list events and the latest stream position for initialization. * `0` or `null` will return all events. example: "1348790499819" in: query name: stream_position schema: type: string - description: |- Limits the number of events returned Note: Sometimes, the events less than the limit requested can be returned even when there may be more events remaining. This is primarily done in the case where a number of events have already been retrieved and these retrieved events are returned rather than delaying for an unknown amount of time to see if there are any more results. example: 50 in: query name: limit schema: default: 100 format: int64 maximum: 500 type: integer - description: |- A comma-separated list of events to filter by. This can only be used when requesting the events with a `stream_type` of `admin_logs` or `adming_logs_streaming`. For any other `stream_type` this value will be ignored. example: - ACCESS_GRANTED explode: false in: query name: event_type schema: items: description: An event type that can be filtered by enum: - ACCESS_GRANTED - ACCESS_REVOKED - ADD_DEVICE_ASSOCIATION - ADD_LOGIN_ACTIVITY_DEVICE - ADMIN_LOGIN - APPLICATION_CREATED - APPLICATION_PUBLIC_KEY_ADDED - APPLICATION_PUBLIC_KEY_DELETED - CHANGE_ADMIN_ROLE - CHANGE_FOLDER_PERMISSION - COLLABORATION_ACCEPT - COLLABORATION_EXPIRATION - COLLABORATION_INVITE - COLLABORATION_REMOVE - COLLABORATION_ROLE_CHANGE - COMMENT_CREATE - COMMENT_DELETE - CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY - CONTENT_WORKFLOW_AUTOMATION_ADD - CONTENT_WORKFLOW_AUTOMATION_DELETE - CONTENT_WORKFLOW_POLICY_ADD - CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION - CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION - COPY - DATA_RETENTION_CREATE_RETENTION - DATA_RETENTION_REMOVE_RETENTION - DELETE - DELETE_USER - DEVICE_TRUST_CHECK_FAILED - DOWNLOAD - EDIT - EDIT_USER - EMAIL_ALIAS_CONFIRM - EMAIL_ALIAS_REMOVE - ENTERPRISE_APP_AUTHORIZATION_UPDATE - EXTERNAL_COLLAB_SECURITY_SETTINGS - FAILED_LOGIN - FILE_MARKED_MALICIOUS - FILE_WATERMARKED_DOWNLOAD - GROUP_ADD_ITEM - GROUP_ADD_USER - GROUP_CREATION - GROUP_DELETION - GROUP_EDITED - GROUP_REMOVE_ITEM - GROUP_REMOVE_USER - ITEM_MODIFY - ITEM_OPEN - ITEM_SHARED_UPDATE - ITEM_SYNC - ITEM_UNSYNC - LEGAL_HOLD_ASSIGNMENT_CREATE - LEGAL_HOLD_ASSIGNMENT_DELETE - LEGAL_HOLD_POLICY_CREATE - LEGAL_HOLD_POLICY_DELETE - LEGAL_HOLD_POLICY_UPDATE - LOCK - LOGIN - METADATA_INSTANCE_CREATE - METADATA_INSTANCE_DELETE - METADATA_INSTANCE_UPDATE - METADATA_TEMPLATE_CREATE - METADATA_TEMPLATE_DELETE - METADATA_TEMPLATE_UPDATE - MOVE - NEW_USER - OAUTH2_ACCESS_TOKEN_REVOKE - PREVIEW - REMOVE_DEVICE_ASSOCIATION - REMOVE_LOGIN_ACTIVITY_DEVICE - RENAME - RETENTION_POLICY_ASSIGNMENT_ADD - SHARE - SHARE_EXPIRATION - SHIELD_ALERT - SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED - SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION - SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED - SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION - SHIELD_JUSTIFICATION_APPROVAL - SIGN_DOCUMENT_ASSIGNED - SIGN_DOCUMENT_CANCELLED - SIGN_DOCUMENT_COMPLETED - SIGN_DOCUMENT_CONVERTED - SIGN_DOCUMENT_CREATED - SIGN_DOCUMENT_DECLINED - SIGN_DOCUMENT_EXPIRED - SIGN_DOCUMENT_SIGNED - SIGN_DOCUMENT_VIEWED_BY_SIGNED - SIGNER_DOWNLOADED - SIGNER_FORWARDED - STORAGE_EXPIRATION - TASK_ASSIGNMENT_CREATE - TASK_ASSIGNMENT_DELETE - TASK_ASSIGNMENT_UPDATE - TASK_CREATE - TASK_UPDATE - TERMS_OF_SERVICE_ACCEPT - TERMS_OF_SERVICE_REJECT - UNDELETE - UNLOCK - UNSHARE - UPDATE_COLLABORATION_EXPIRATION - UPDATE_SHARE_EXPIRATION - UPLOAD - USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE - WATERMARK_LABEL_CREATE - WATERMARK_LABEL_DELETE type: string type: array - description: |- The lower bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. example: 2012-12-12T10:53:43-08:00 in: query name: created_after schema: format: date-time type: string - description: |- The upper bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. example: 2013-12-12T10:53:43-08:00 in: query name: created_before required: false schema: format: date-time type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Events" description: |- Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a `chunk_size` parameter indicating how many events were returned in this chunk, as well as the next `stream_position` that can be queried. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List user and enterprise events tags: - Events x-box-tag: events options: description: |- Returns a list of real-time servers that can be used for long-polling updates to the [event stream](#get-events). Long polling is the concept where a HTTP request is kept open until the server sends a response, then repeating the process over and over to receive updated responses. Long polling the event stream can only be used for user events, not for enterprise events. To use long polling, first use this endpoint to retrieve a list of long poll URLs. Next, make a long poll request to any of the provided URLs. When an event occurs in monitored account a response with the value `new_change` will be sent. The response contains no other details as it only serves as a prompt to take further action such as sending a request to the [events endpoint](#get-events) with the last known `stream_position`. After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again. If no events occur for a while and the connection times out you will receive a response with the value `reconnect`. When you receive this response you’ll make another call to this endpoint to restart the process. If you receive no events in `retry_timeout` seconds then you will need to make another request to the real-time server (one of the URLs in the response for this endpoint). This might be necessary due to network errors. Finally, if you receive a `max_retries` error when making a request to the real-time server, you should start over by making a call to this endpoint first. operationId: options_events responses: "200": content: application/json: schema: $ref: "#/components/schemas/RealtimeServers" description: |- Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get events long poll endpoint tags: - Events x-box-tag: events "/file_requests/{file_request_id}": delete: description: Deletes a file request permanently. operationId: delete_file_requests_id parameters: - description: |- The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. example: "123" in: path name: file_request_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the file request has been successfully deleted. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file request is not found or has already been deleted, or the user does not have access to the associated folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_request_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete file request tags: - File requests x-box-sanitized: true x-box-tag: file_requests get: description: Retrieves the information about a file request. operationId: get_file_requests_id parameters: - description: |- The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. example: "123" in: path name: file_request_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileRequest" description: Returns a file request object. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file request is not found, or the user does not have access to the associated folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_request_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get file request tags: - File requests x-box-enable-explorer: true x-box-tag: file_requests put: description: |- Updates a file request. This can be used to activate or deactivate a file request. operationId: put_file_requests_id parameters: - description: |- The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. example: "123" in: path name: file_request_id required: true schema: type: string - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/FileRequestUpdateRequest" responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileRequest" description: Returns the updated file request object. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file request is not found, or the user does not have access to the associated folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_request_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file request. This indicates that the file request has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update file request tags: - File requests x-box-enable-explorer: true x-box-sanitized: true x-box-tag: file_requests "/file_requests/{file_request_id}/copy": post: description: |- Copies an existing file request that is already present on one folder, and applies it to another folder. operationId: post_file_requests_id_copy parameters: - description: |- The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. example: "123" in: path name: file_request_id required: true schema: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/FileRequestCopyRequest" responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileRequest" description: Returns updated file request object. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file request is not found, or the user does not have access to the associated folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_request_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Copy file request tags: - File requests x-box-enable-explorer: true x-box-sanitized: true x-box-tag: file_requests /file_version_legal_holds: get: description: |- Get a list of file versions on legal hold for a legal hold assignment. Due to ongoing re-architecture efforts this API might not return all file versions for this policy ID. Instead, this API will only return file versions held in the legacy architecture. Two new endpoints will available to request any file versions held in the new architecture. For file versions held in the new architecture, the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to return all past file versions available for this policy assignment, and the `GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to return any current (latest) versions of a file under legal hold. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. Once the re-architecture is completed this API will be deprecated. operationId: get_file_version_legal_holds parameters: - description: |- The ID of the legal hold policy to get the file version legal holds for. example: "133870" in: query name: policy_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersionLegalHolds" description: |- Returns the list of file version legal holds for a specific legal hold policy. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List file version legal holds tags: - File version legal holds x-box-tag: file_version_legal_holds "/file_version_legal_holds/{file_version_legal_hold_id}": get: description: |- Retrieves information about the legal hold policies assigned to a file version. operationId: get_file_version_legal_holds_id parameters: - description: The ID of the file version legal hold example: "2348213" in: path name: file_version_legal_hold_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersionLegalHold" description: Returns the legal hold policy assignments for the file version. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get file version legal hold tags: - File version legal holds x-box-tag: file_version_legal_holds /file_version_retentions: get: description: Retrieves all file version retentions for the given enterprise. operationId: get_file_version_retentions parameters: - description: Filters results by files with this ID. example: "43123123" in: query name: file_id required: false schema: type: string - description: Filters results by file versions with this ID. example: "1" in: query name: file_version_id required: false schema: type: string - description: Filters results by the retention policy with this ID. example: "982312" in: query name: policy_id required: false schema: type: string - description: |- Filters results by the retention policy with this disposition action. example: permanently_delete in: query name: disposition_action required: false schema: enum: - permanently_delete - remove_retention type: string - description: |- Filters results by files that will have their disposition come into effect before this date. example: 2012-12-12T10:53:43-08:00 in: query name: disposition_before required: false schema: type: string - description: |- Filters results by files that will have their disposition come into effect after this date. example: 2012-12-19T10:34:23-08:00 in: query name: disposition_after required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersionRetentions" description: Returns a list of all file version retentions for the enterprise. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List file version retentions tags: - File version retentions x-box-tag: file_version_retentions "/file_version_retentions/{file_version_retention_id}": get: description: Returns information about a file version retention. operationId: get_file_version_retentions_id parameters: - description: The ID of the file version retention example: "3424234" in: path name: file_version_retention_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersionRetention" description: Returns a file version retention object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get retention on file tags: - File version retentions x-box-tag: file_version_retentions /files/content: options: description: |- Performs a check to verify that a file will be accepted by Box before you upload the entire file. operationId: options_files_content requestBody: content: application/json: schema: properties: name: description: The name for the file example: File.mp4 type: string parent: allOf: - description: The parent for this item properties: id: description: The ID of parent item example: "123" type: string type: object - description: The parent folder to upload the file to size: description: The size of the file in bytes example: 1024 format: int32 type: integer type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/UploadUrl" description: |- If the check passed, the response will include a session URL that can be used to upload the file to. "409": content: application/json: schema: $ref: "#/components/schemas/ConflictError" description: |- If the check did not pass, the response will include some details on why it did not pass. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Preflight check before upload tags: - Files x-box-tag: uploads post: description: |- Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs. # Request body order The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. operationId: post_files_content parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit. example: 134b65991ed521fcfe4724b7d814ab8ded5185dc in: header name: content-md5 required: false schema: type: string requestBody: content: multipart/form-data: schema: properties: attributes: description: |- The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. properties: content_created_at: description: |- Defines the time the file was originally created at. If not set, the upload time will be used. example: 2012-12-12T10:53:43-08:00 format: date-time type: string content_modified_at: description: |- Defines the time the file was last modified at. If not set, the upload time will be used. example: 2012-12-12T10:53:43-08:00 format: date-time type: string name: description: The name of the file example: Photo.png type: string parent: description: The parent folder to upload the file to properties: id: description: |- The id of the parent folder. Use `0` for the user's root folder. example: "124132" type: string required: - id type: object required: - name - parent type: object file: description: |- The content of the file to upload to Box. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. format: binary type: string required: - attributes - file type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Files" description: Returns the new file object in a list. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing or incorrect. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the file already exists, or the account has run out of disk space. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Upload file tags: - Uploads x-box-tag: uploads /files/upload_sessions: post: description: Creates an upload session for a new file. operationId: post_files_upload_sessions requestBody: content: application/json: schema: properties: file_name: description: The name of new file example: Project.mov type: string file_size: description: The total number of bytes of the file to be uploaded example: 104857600 format: int64 type: integer folder_id: description: The ID of the folder to upload the new file to. example: "0" type: string required: - folder_id - file_size - file_name type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/UploadSession" description: Returns a new upload session. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `missing_destination`: No `folder_id` was provided * `invalid_folder_id`: `folder_id` is not valid * `item_name_invalid`: `file_name` is not valid * `missing_file_size`: `file_size` was not provided * `invalid_file_size`: `file_size` was not a valid number * `file_size_too_small`: `file_size` is below minimum file size for uploads via this API * `missing_file_name`: `file_name` was not provided "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the operation is not allowed for some reason. * `storage_limit_exceeded`: Account storage limit reached "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the parent folder could not be found, or the authenticated user does not have access to it. * `invalid_parameter`: The `folder_id` value represents a folder that the user does not have access to, or does not exist. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the file already exists, or the account has run out of disk space. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Create upload session tags: - Uploads (Chunked) x-box-tag: chunked_uploads "/files/upload_sessions/{upload_session_id}": delete: description: |- Abort an upload session and discard all data uploaded. This cannot be reversed. operationId: delete_files_upload_sessions_id parameters: - description: The ID of the upload session. example: D5E3F7A in: path name: upload_session_id required: true schema: type: string responses: "204": description: |- A blank response is returned if the session was successfully aborted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Remove upload session tags: - Uploads (Chunked) x-box-tag: chunked_uploads get: description: Return information about an upload session. operationId: get_files_upload_sessions_id parameters: - description: The ID of the upload session. example: D5E3F7A in: path name: upload_session_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/UploadSession" description: Returns an upload session object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Get upload session tags: - Uploads (Chunked) x-box-tag: chunked_uploads put: description: Updates a chunk of an upload session for a file. operationId: put_files_upload_sessions_id parameters: - description: The ID of the upload session. example: D5E3F7A in: path name: upload_session_id required: true schema: type: string - description: |- The [RFC3230][1] message digest of the chunk uploaded. Only SHA1 is supported. The SHA1 digest must be base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. To get the value for the `SHA` digest, use the openSSL command to encode the file part: `openssl sha1 -binary | base64` [1]: https://tools.ietf.org/html/rfc3230 example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM= in: header name: digest required: true schema: type: string - description: |- The byte range of the chunk. Must not overlap with the range of a part already uploaded this session. Each part’s size must be exactly equal in size to the part size specified in the upload session that you created. One exception is the last part of the file, as this can be smaller. When providing the value for `content-range`, remember that: * The lower bound of each part's byte range must be a multiple of the part size. * The higher bound must be a multiple of the part size - 1. example: bytes 8388608-16777215/445856194 in: header name: content-range required: true schema: type: string requestBody: content: application/octet-stream: schema: description: The binary content of the file format: binary type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/UploadedPart" description: Chunk has been uploaded successfully. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the chunk conflicts with another chunk previously uploaded. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if a precondition was not met. "416": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the content range does not match a specified range for the session. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Upload part of file tags: - Uploads (Chunked) x-box-tag: chunked_uploads "/files/upload_sessions/{upload_session_id}/commit": post: description: |- Close an upload session and create a file from the uploaded chunks. operationId: post_files_upload_sessions_id_commit parameters: - description: The ID of the upload session. example: D5E3F7A in: path name: upload_session_id required: true schema: type: string - description: |- The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`. [1]: https://tools.ietf.org/html/rfc3230 example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM= in: header name: digest required: true schema: type: string - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string - description: |- Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. example: "1" in: header name: if-none-match required: false schema: type: string requestBody: content: application/json: schema: properties: parts: description: The list details for the uploaded parts items: $ref: "#/components/schemas/UploadPart" type: array required: - parts type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Files" description: Returns the file object in a list. "202": description: |- Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. headers: Retry-After: description: |- Indicates the number of seconds the client should wait before attempting their commit request again. schema: type: integer "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if there is already a file with the same name in the target folder. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the `If-Match` or `If-None-Match` conditions fail. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Commit upload session tags: - Uploads (Chunked) x-box-tag: chunked_uploads "/files/upload_sessions/{upload_session_id}/parts": get: description: |- Return a list of the chunks uploaded to the upload session so far. operationId: get_files_upload_sessions_id_parts parameters: - description: The ID of the upload session. example: D5E3F7A in: path name: upload_session_id required: true schema: type: string - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/UploadParts" description: Returns a list of parts that have been uploaded. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: List parts tags: - Uploads (Chunked) x-box-tag: chunked_uploads "/files/{file_id}": delete: description: |- Deletes a file, either permanently or by moving it to the trash. The the enterprise settings determine whether the item will be permanently deleted from Box or moved to the trash. operationId: delete_files_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string responses: "204": description: |- Returns an empty response when the file has been successfully deleted. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found or has already been deleted, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete file tags: - Files x-box-sanitized: true x-box-tag: files get: description: Retrieves the details about a file. operationId: get_files_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?field=metadata.enterprise_12345.contractTemplate`. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. example: "1" in: header name: if-none-match required: false schema: type: string - description: |- The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: false schema: type: string - description: |- A header required to request specific `representations` of a file. Use this in combination with the `fields` query parameter to request a specific file representation. The general format for these representations is `X-Rep-Hints: [...]` where `[...]` is one or many hints in the format `[fileType?query]`. For example, to request a `png` representation in `32x32` as well as `64x64` pixel dimensions provide the following hints. `x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]` Additionally, a `text` representation is available for all document file types in Box using the `[extracted_text]` representation. `x-rep-hints: [extracted_text]` example: "[pdf]" in: header name: x-rep-hints required: false schema: nullable: true type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/File--Full" description: |- Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. "304": description: |- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "415": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if an action is performed on a file with an incorrect media type. * `unsupported_media_type` when requesting an `expiring_embed_link` for a file that is not supported by Box Embed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get file information tags: - Files x-box-enable-explorer: true x-box-tag: files post: description: |- Restores a file that has been moved to the trash. An optional new parent ID can be provided to restore the file to in case the original folder has been deleted. operationId: post_files_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: name: description: An optional new name for the file. example: Restored.docx type: string parent: allOf: - description: The parent for this item properties: id: description: The ID of parent item example: "123" type: string type: object - description: |- Specifies an optional ID of a folder to restore the file to when the original folder no longer exists. Please be aware that this ID will only be used if the original folder no longer exists. Use this ID to provide a fallback location to restore the file to if the original location has been deleted. type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/TrashFileRestored" description: Returns a file object when the file has been restored. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user does not have access to the folder the file is being restored to, or the user does not have permission to restore files from the trash. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the file is not in the trash. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if there is an file with the same name in the folder the file is being restored to. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Restore file tags: - Trashed files x-box-tag: trashed_files put: description: |- Updates a file. This can be used to rename or move a file, create a shared link, or lock a file. operationId: put_files_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string requestBody: content: application/json: schema: properties: description: description: |- The description for a file. This can be seen in the right-hand sidebar panel when viewing a file in the Box web app. Additionally, this index is used in the search index of the file, allowing users to find the file by the content in the description. example: The latest reports. Automatically updated maxLength: 256 type: string disposition_at: description: |- The retention expiration timestamp for the given file. This date cannot be shortened once set on a file. example: 2012-12-12T10:53:43-08:00 format: date-time type: string lock: description: |- Defines a lock on an item. This prevents the item from being moved, renamed, or otherwise changed by anyone other than the user who created the lock. Set this to `null` to remove the lock. properties: access: description: The type of this object. enum: - lock example: lock type: string expires_at: description: Defines the time at which the lock expires. example: 2012-12-12T10:53:43-08:00 format: date-time type: string is_download_prevented: description: Defines if the file can be downloaded while it is locked. example: true type: boolean required: - type type: object name: description: |- An optional different name for the file. This can be used to rename the file. example: NewFile.txt type: string parent: allOf: - description: The parent for this item properties: id: description: The ID of parent item example: "123" type: string type: object - description: |- An optional new parent folder for the file. This can be used to move the file to a new folder. permissions: description: Defines who can download a file. properties: can_download: description: |- Defines who is allowed to download this file. The possible values are either `open` for everyone or `company` for the other members of the user's enterprise. This setting overrides the download permissions that are normally part of the `role` of a collaboration. When set to `company`, this essentially removes the download option for external users with `viewer` or `editor` a roles. enum: - open - company example: open type: string type: object shared_link: allOf: - description: |- Defines a shared link for an item. Set this to `null` to remove the shared link. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link type: string type: object - description: |- Defines a shared link for a file. Set this to `null` to remove the shared link. tags: 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. example: - approved items: type: string maxItems: 100 minItems: 1 type: array type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/File--Full" description: |- Returns a file object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the new retention time > maximum retention length. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` returned when the authenticated user does not have access to the destination folder to move the file to. * Returned when retention time is shorter or equal to current retention timestamp. * Returned when a `file_id` that is not under retention is entered. * Returned when a file that is retained but the disposition action is set to `remove_retention` * `forbidden_by_policy` is returned if copying a folder is forbidden due to information barrier restrictions. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update file tags: - Files x-box-enable-explorer: true x-box-sanitized: true x-box-tag: files "/files/{file_id}#add_shared_link": put: description: Adds a shared link to a file. operationId: put_files_id#add_shared_link parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: |- The settings for the shared link to create on the file. Use an empty object (`{}`) to use the default settings for shared links. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the file (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean can_edit: description: |- If the shared link allows for editing of files. This can only be set when `access` is set to `open` or `company`. This value can only be `true` is `can_download` is also `true`. example: true type: boolean can_preview: description: |- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: true can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: file schema: $ref: "#/components/schemas/File--Full" description: |- Returns the base representation of a file with a new shared link attached. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when there is an incorrect permission combination "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add shared link to file tags: - Shared links (Files) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_files "/files/{file_id}#get_shared_link": get: description: Gets the information for a shared link on a file. operationId: get_files_id#get_shared_link parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: true can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: file schema: $ref: "#/components/schemas/File--Full" description: |- Returns the base representation of a file with the additional shared link information. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shared link for file tags: - Shared links (Files) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_files "/files/{file_id}#remove_shared_link": put: description: Removes a shared link from a file. operationId: put_files_id#remove_shared_link parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: |- By setting this value to `null`, the shared link is removed from the file. example: null nullable: true type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: null type: file schema: $ref: "#/components/schemas/File--Full" description: Returns a basic representation of a file, with the shared link removed. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove shared link from file tags: - Shared links (Files) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_files "/files/{file_id}#update_shared_link": put: description: Updates a shared link on a file. operationId: put_files_id#update_shared_link parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: The settings for the shared link to update. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean can_edit: description: |- If the shared link allows for editing of files. This can only be set when `access` is set to `open` or `company`. This value can only be `true` is `can_download` is also `true`. example: true type: boolean can_preview: description: |- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: true can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: file schema: $ref: "#/components/schemas/File--Full" description: |- Returns a basic representation of the file, with the updated shared link attached. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when there is an incorrect permission combination "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update shared link on file tags: - Shared links (Files) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_files "/files/{file_id}/collaborations": get: description: |- Retrieves a list of pending and active collaborations for a file. This returns all the users that have access to the file or have been invited to the file. operationId: get_files_id_collaborations parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Collaborations" description: |- Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List file collaborations tags: - Collaborations (List) x-box-tag: list_collaborations "/files/{file_id}/comments": get: description: Retrieves a list of comments for a file. operationId: get_files_id_comments parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/Comments" description: |- Returns a collection of comment objects. If there are no comments on this file an empty collection will be returned. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List file comments tags: - Comments x-box-tag: comments "/files/{file_id}/content": get: description: Returns the contents of a file in binary format. operationId: get_files_id_content parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: |- The byte range of the content to download. The format `bytes={start_byte}-{end_byte}` can be used to specify what section of the file to download. example: bytes=0-1024 in: header name: range required: false schema: type: string - description: |- The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: false schema: type: string - description: The file version to download example: "4" in: query name: version required: false schema: type: string - description: |- An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication. When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ in: query name: access_token required: false schema: type: string responses: "202": description: |- If the file is not ready to be downloaded yet `Retry-After` header will be returned indicating the time in seconds after which the file will be available for the client to download. This response can occur when the file was uploaded immediately before the download request. headers: Retry-After: description: The time in seconds after which to retry the download schema: type: integer "302": description: |- If the file is available to be downloaded the response will include a `Location` header for the file on `dl.boxcloud.com`. The `dl.boxcloud.com` URL is not persistent and clients will need to follow the redirect in order to actually download the file. headers: Location: description: A pointer to the download URL schema: format: url type: string default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Download file tags: - Downloads x-box-tag: downloads post: description: |- Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs. # Request body order The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. operationId: post_files_id_content parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit. example: 134b65991ed521fcfe4724b7d814ab8ded5185dc in: header name: content-md5 required: false schema: type: string requestBody: content: multipart/form-data: schema: properties: attributes: description: |- The additional attributes of the file being uploaded. Mainly the name and the parent folder. These attributes are part of the multi part request body and are in JSON format. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. properties: content_modified_at: description: |- Defines the time the file was last modified at. If not set, the upload time will be used. example: 2012-12-12T10:53:43-08:00 format: date-time type: string name: description: |- An optional new name for the file. If specified, the file will be renamed when the new version is uploaded. example: Photo 2.0.png type: string required: - name type: object file: description: |- The content of the file to upload to Box. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. format: binary type: string required: - attributes - file type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Files" description: Returns the new file object in a list. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Upload file version tags: - Uploads x-box-tag: uploads "/files/{file_id}/copy": post: description: Creates a copy of a file. operationId: post_files_id_copy parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: nullable: false properties: name: description: |- An optional new name for the copied file. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), and protected names like `.` and `..` are automatically sanitized by removing the non-allowed characters. example: FileCopy.txt maxLength: 255 type: string parent: description: The destination folder to copy the file to. properties: id: description: The ID of folder to copy the file to. example: "0" type: string required: - id type: object version: description: An optional ID of the specific file version to copy. example: "0" type: string required: - parent type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/File--Full" description: |- Returns a new file object representing the copied file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. "304": description: |- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the file. This indicates that the file has not changed since it was last requested. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user does not have the right permissions to create the copy a file. * `forbidden_by_policy`: Returned if copying a file is forbidden due to information barrier restrictions. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if either the source file or the destination folder could not be found, or the authenticated user does not have access to either. * `not_found` when the authenticated user does not have access to the source file or the destination folder "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. * `item_name_in_use` when a folder with the same name already exists. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Copy file tags: - Files x-box-enable-explorer: true x-box-sanitized: true x-box-tag: files "/files/{file_id}/metadata": get: description: Retrieves all metadata for a given file. operationId: get_files_id_metadata parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Metadatas" description: |- Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the user does not have access to the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List metadata instances on file tags: - Metadata instances (Files) x-box-sanitized: true x-box-tag: file_metadata "/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo": delete: description: |- Removes any classifications from a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. operationId: delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the classification is successfully deleted. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file does not have any classification applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the classification metadata template with the was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the method was not allowed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove classification from file tags: - Classifications on files x-box-sanitized: true x-box-tag: file_classifications get: description: |- Retrieves the classification metadata instance that has been applied to a file. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. operationId: get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Classification" description: |- Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the metadata template specified was not applied to this file or the user does not have access to the file. * `instance_not_found` - The metadata template was not applied to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the method was not allowed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get classification on file tags: - Classifications on files x-box-sanitized: true x-box-tag: file_classifications post: description: |- Adds a classification to a file by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. operationId: post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string requestBody: content: application/json: schema: properties: Box__Security__Classification__Key: description: |- The name of the classification to apply to this file. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. example: Sensitive type: string type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Classification" description: |- Returns the classification template instance that was applied to the file. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of them metadata template already exists on the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add classification to file tags: - Classifications on files x-box-sanitized: true x-box-tag: file_classifications put: description: |- Updates a classification on a file. The classification can only be updated if a classification has already been applied to the file before. When editing classifications, only values are defined for the enterprise will be accepted. operationId: put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string requestBody: content: application/json-patch+json: schema: description: |- A list containing the one change to make, to update the classification label. items: description: |- The operation to perform on the classification metadata template instance. In this case, it use used to replace the value stored for the `Box__Security__Classification__Key` field with a new value. properties: op: description: "`replace`" enum: - replace example: replace type: string path: description: "`/Box__Security__Classification__Key`" enum: - /Box__Security__Classification__Key example: /Box__Security__Classification__Key type: string value: description: |- The name of the classification to apply to this file. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. example: Sensitive type: string type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Classification" description: Returns the updated classification metadata template instance. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch operations. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update classification on file tags: - Classifications on files x-box-sanitized: true x-box-tag: file_classifications "/files/{file_id}/metadata/global/boxSkillsCards": delete: description: Removes any Box Skills cards metadata from a file. operationId: delete_files_id_metadata_global_boxSkillsCards parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the cards are successfully deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file does not have an instance of the Box Skill cards applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the metadata template for Box Skill cards was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the method was not allowed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove Box Skill cards from file tags: - Skills x-box-sanitized: true x-box-tag: skills get: description: List the Box Skills metadata cards that are attached to a file. operationId: get_files_id_metadata_global_boxSkillsCards parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SkillCardsMetadata" description: |- Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List Box Skill cards on file tags: - Skills x-box-tag: skills post: description: Applies one or more Box Skills metadata cards to a file. operationId: post_files_id_metadata_global_boxSkillsCards parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string requestBody: content: application/json: schema: properties: cards: description: A list of Box Skill cards to apply to this file. items: oneOf: - $ref: "#/components/schemas/KeywordSkillCard" - $ref: "#/components/schemas/TimelineSkillCard" - $ref: "#/components/schemas/TranscriptSkillCard" - $ref: "#/components/schemas/StatusSkillCard" type: array required: - cards type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/SkillCardsMetadata" description: |- Returns the instance of the template that was applied to the file, including the data that was applied to the template. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of them metadata template already exists on the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create Box Skill cards on file tags: - Skills x-box-tag: skills put: description: Updates one or more Box Skills metadata cards to a file. operationId: put_files_id_metadata_global_boxSkillsCards parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string requestBody: content: application/json-patch+json: schema: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) specification for the changes to make to the metadata template. The changes are represented as a JSON array of operation objects. items: description: An operation that replaces an existing card. properties: op: description: "`replace`" enum: - replace example: replace type: string path: description: |- The JSON Path that represents the card to replace. In most cases this will be in the format `/cards/{index}` where `index` is the zero-indexed position of the card in the list of cards. example: /cards/0 type: string value: allOf: - oneOf: - $ref: "#/components/schemas/KeywordSkillCard" - $ref: "#/components/schemas/TimelineSkillCard" - $ref: "#/components/schemas/TranscriptSkillCard" - $ref: "#/components/schemas/StatusSkillCard" - description: |- The card to insert into the list of cards at the position defined by `path`. type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/SkillCardsMetadata" description: |- Returns the updated metadata template, with the custom template data included. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: The requested file could not be found default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update Box Skill cards on file tags: - Skills x-box-tag: skills "/files/{file_id}/metadata/{scope}/{template_key}": delete: description: Deletes a piece of file metadata. operationId: delete_files_id_metadata_id_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string responses: "204": description: |- Returns an empty response when the metadata is successfully deleted. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the request parameters are not valid. This may happen of the `scope` is not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file does not have an instance of the metadata template applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the method was not allowed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove metadata instance from file tags: - Metadata instances (Files) x-box-sanitized: true x-box-tag: file_metadata get: description: |- Retrieves the instance of a metadata template that has been applied to a file. operationId: get_files_id_metadata_id_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Metadata" description: |- An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the metadata template specified was not applied to this file or the user does not have access to the file. * `instance_not_found` - The metadata template was not applied to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the method was not allowed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get metadata instance on file tags: - Metadata instances (Files) x-box-sanitized: true x-box-tag: file_metadata post: description: |- Applies an instance of a metadata template to a file. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. operationId: post_files_id_metadata_id_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string requestBody: content: application/json: schema: additionalProperties: description: |- A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be an a list of zero or more fields, as this template allows for any generic key-value pairs to be stored on the template. example: Aaron Levie type: string x-box-example-key: name example: name: Aaron Levie type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Metadata" description: |- Returns the instance of the template that was applied to the file, including the data that was applied to the template. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of them metadata template already exists on the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create metadata instance on file tags: - Metadata instances (Files) x-box-sanitized: true x-box-tag: file_metadata put: description: |- Updates a piece of metadata on a file. The metadata instance can only be updated if the template has already been applied to the file before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. operationId: put_files_id_metadata_id_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string requestBody: content: application/json-patch+json: schema: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) specification for the changes to make to the metadata instance. The changes are represented as a JSON array of operation objects. items: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a change to make to the metadata instance. properties: from: description: |- The location in the metadata JSON object to move or copy a value from. Required for `move` or `copy` operations and must be in the format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901). example: /nextState type: string op: description: |- The type of change to perform on the template. Some of these are hazardous as they will change existing templates. enum: - add - replace - remove - test - move - copy example: add type: string path: description: |- The location in the metadata JSON object to apply the changes to, in the format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901). The path must always be prefixed with a `/` to represent the root of the template. The characters `~` and `/` are reserved characters and must be escaped in the key. example: /currentState type: string value: description: |- The value to be set or tested. Required for `add`, `replace`, and `test` operations. For `add`, if the value exists already the previous value will be overwritten by the new value. For `replace`, the value must exist before replacing. For `test`, the existing value at the `path` location must match the specified value. example: reviewed type: string title: A metadata instance update operation type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Metadata" description: |- Returns the updated metadata template instance, with the custom template data included. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch objects. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update metadata instance on file tags: - Metadata instances (Files) x-box-sanitized: true x-box-tag: file_metadata "/files/{file_id}/tasks": get: description: |- Retrieves a list of all the tasks for a file. This endpoint does not support pagination. operationId: get_files_id_tasks parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Tasks" description: |- Returns a list of tasks on a file. If there are no tasks on this file an empty collection is returned instead. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file could not be found or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error when the `file_id` was not provided. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when an attempt was made to retrieve tasks for the file with ID `0`. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List tasks on file tags: - Tasks x-box-sanitized: true x-box-tag: tasks "/files/{file_id}/thumbnail.{extension}": get: description: |- Retrieves a thumbnail, or smaller image representation, of a file. Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `160x160`, and `320x320` can be returned in the `.jpg` format. Thumbnails can be generated for the image and video file formats listed [found on our community site][1]. [1]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327 operationId: get_files_id_thumbnail_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: The file format for the thumbnail example: png in: path name: extension required: true schema: enum: - png - jpg type: string - description: The minimum height of the thumbnail example: 32 in: query name: min_height schema: maximum: 320 minimum: 32 type: integer - description: The minimum width of the thumbnail example: 32 in: query name: min_width schema: maximum: 320 minimum: 32 type: integer - description: The maximum height of the thumbnail example: 320 in: query name: max_height required: false schema: maximum: 320 minimum: 32 type: integer - description: The maximum width of the thumbnail example: 320 in: query name: max_width required: false schema: maximum: 320 minimum: 32 type: integer responses: "200": content: image/jpg: schema: description: The thumbnail format: binary type: string image/png: schema: description: The thumbnail format: binary type: string description: |- When a thumbnail can be created the thumbnail data will be returned in the body of the response. "202": description: |- Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. headers: Location: description: |- A pointer to a placeholder graphic that can be used until the thumbnail has been generated. schema: format: url type: string Retry-After: description: |- The time in seconds after which the thumbnail will be available. Your application only attempt to get the thumbnail again after this time. schema: format: int64 type: integer "302": description: |- Returns an error when Box is not able to create a thumbnail for this file type. Instead, a `Location`-header pointing to a placeholder graphic for this file type will be returned. headers: Location: description: |- A pointer to a placeholder graphic that can be used for this file type. schema: format: url type: string "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `requested_preview_unavailable` - an incorrect dimension was requested. This will happen if the dimension requested is larger or smaller than the available file sizes for the thumbnail format, or when when any of the size constraints contradict each other. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file, or for additional reasons. * `preview_cannot_be_generated` - Box does not support thumbnails for this type of file default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get file thumbnail tags: - Files x-box-tag: files "/files/{file_id}/trash": delete: description: |- Permanently deletes a file that is in the trash. This action cannot be undone. operationId: delete_files_id_trash parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the file was permanently deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the file is not in the trash. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Permanently remove file tags: - Trashed files x-box-tag: trashed_files get: description: |- Retrieves a file that has been moved to the trash. Please note that only if the file itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. operationId: get_files_id_trash parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/TrashFile" description: |- Returns the file that was trashed, including information about when the it was moved to the trash. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the file can not be found directly in the trash. Please note that a `HTTP 404` is also returned if any of the file's parent folders have been moved to the trash. In that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get trashed file tags: - Trashed files x-box-tag: trashed_files "/files/{file_id}/upload_sessions": post: description: Creates an upload session for an existing file. operationId: post_files_id_upload_sessions parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string requestBody: content: application/json: schema: properties: file_name: description: The optional new name of new file example: Project.mov type: string file_size: description: The total number of bytes of the file to be uploaded example: 104857600 format: int64 type: integer required: - file_size type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/UploadSession" description: Returns a new upload session. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the file already exists, or if the account has run out of disk space. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. servers: - description: Server for file uploads url: https://upload.box.com/api/2.0 summary: Create upload session for existing file tags: - Uploads (Chunked) x-box-tag: chunked_uploads "/files/{file_id}/versions": get: description: |- Retrieve a list of the past versions for a file. Versions are only tracked by Box users with premium accounts. To fetch the ID of the current version of a file, use the `GET /file/:id` API. operationId: get_files_id_versions parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersions" description: Returns an array of past versions for this file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List all file versions tags: - File versions x-box-tag: file_versions "/files/{file_id}/versions/current": post: description: |- Promote a specific version of a file. If previous versions exist, this method can be used to promote one of the older versions to the top of the version history. This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the the same hash digest, `etag`, and name as the original. Other properties such as comments do not get updated to their former values. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. operationId: post_files_id_versions_current parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: description: The file version to promote properties: id: description: The file version ID example: "11446498" type: string type: description: The type to promote enum: - file_version example: file_version type: string type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/FileVersion--Full" description: Returns a newly created file version object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Promote file version tags: - File versions x-box-tag: file_versions "/files/{file_id}/versions/{file_version_id}": delete: description: |- Move a file version to the trash. Versions are only tracked for Box users with premium accounts. operationId: delete_files_id_versions_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: The ID of the file version example: "1234" in: path name: file_version_id required: true schema: type: string - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string responses: "204": description: |- Returns an empty response when the file has been successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove file version tags: - File versions x-box-tag: file_versions get: description: |- Retrieve a specific version of a file. Versions are only tracked for Box users with premium accounts. operationId: get_files_id_versions_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The ID of the file version example: "1234" in: path name: file_version_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersion--Full" description: |- Returns a specific version of a file. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get file version tags: - File versions x-box-tag: file_versions put: description: |- Restores a specific version of a file after it was deleted. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. operationId: put_files_id_versions_id parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string - description: The ID of the file version example: "1234" in: path name: file_version_id required: true schema: type: string requestBody: content: application/json: schema: description: |- The file version to be restored properties: trashed_at: description: |- Set this to `null` to clear the date and restore the file. example: "null" type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersion--Full" description: Returns a restored file version object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Restore file version tags: - File versions x-box-tag: file_versions "/files/{file_id}/watermark": delete: description: Removes the watermark from a file. operationId: delete_files_id_watermark parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "204": description: Removes the watermark and returns an empty response. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the file did not have a watermark applied to it. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove watermark from file tags: - Watermarks (Files) x-box-tag: file_watermarks get: description: Retrieve the watermark for a file. operationId: get_files_id_watermark parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Watermark" description: |- Returns an object containing information about the watermark associated for to this file. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the file does not have a watermark applied. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get watermark on file tags: - Watermarks (Files) x-box-tag: file_watermarks put: description: Applies or update a watermark on a file. operationId: put_files_id_watermark parameters: - description: |- The unique identifier that represents 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" in: path name: file_id required: true schema: type: string requestBody: content: application/json: schema: properties: watermark: description: The watermark to imprint on the file properties: imprint: description: |- The type of watermark to apply. Currently only supports one option. enum: - default example: default type: string required: - imprint type: object required: - watermark type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Watermark" description: |- Returns an updated watermark if a watermark already existed on this file. "201": content: application/json: schema: $ref: "#/components/schemas/Watermark" description: |- Returns a new watermark if no watermark existed on this file yet. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Apply watermark to file tags: - Watermarks (Files) x-box-tag: file_watermarks /folder_locks: get: description: |- Retrieves folder lock details for a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. operationId: get_folder_locks parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: query name: folder_id required: true schema: nullable: false type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FolderLocks" description: |- Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `folder_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List folder locks tags: - Folder Locks x-box-enable-explorer: true x-box-sanitized: true x-box-tag: folder_locks post: description: |- Creates a folder lock on a folder, preventing it from being moved and/or deleted. You must be authenticated as the owner or co-owner of the folder to use this endpoint. operationId: post_folder_locks requestBody: content: application/json: schema: properties: folder: description: The folder to apply the lock to. properties: id: description: The ID of the folder. example: "1234567890" type: string type: description: |- The content type the lock is being applied to. Only `folder` is supported. example: folder type: string required: - type - id type: object locked_operations: description: |- The operations to lock for the folder. If `locked_operations` is included in the request, both `move` and `delete` must also be included and both set to `true`. properties: delete: description: Whether deleting the folder should be locked. example: true type: boolean move: description: Whether moving the folder should be locked. example: true type: boolean required: - move - delete type: object required: - folder type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/FolderLock" description: |- Returns the instance of the folder lock that was applied to the folder, including the user that applied the lock and the operations set. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the folder was not found. * `not_found` - The folder could not be found, the user does not have access to the folder, or the user making call is not an owner or co-owner of folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create folder lock tags: - Folder Locks x-box-enable-explorer: false x-box-sanitized: true x-box-tag: folder_locks "/folder_locks/{folder_lock_id}": delete: description: |- Deletes a folder lock on a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. operationId: delete_folder_locks_id parameters: - description: The ID of the folder lock. example: "12345" in: path name: folder_lock_id required: true schema: nullable: false type: string responses: "204": description: Returns an empty response when the folder lock is successfully deleted. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder. * `insufficient_scope`: Returned an error if the application does not have the right scope to delete folders. Make sure your application has been configured to read and write all files and folders stored in Box. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the folder could not be found, or the authenticated user does not have access to the folder. * `not_found` when the authenticated user does not have access to the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete folder lock tags: - Folder Locks x-box-sanitized: true x-box-tag: folder_locks /folders: post: description: Creates a new empty folder within the specified parent folder. operationId: post_folders parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: folder_upload_email: allOf: - description: The Write Folder Upload Email object properties: access: 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. enum: - open - collaborators example: open nullable: false type: string title: Folder upload email type: object - description: |- Setting this object enables the upload email address. This email address can be used by users to directly upload files directly to the folder via email. name: description: |- The name for the new folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either. example: New Folder maxLength: 255 minLength: 1 type: string parent: description: The parent folder to create the new folder within. properties: id: description: The ID of parent folder example: "0" type: string required: - id type: object sync_state: 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 example: synced nullable: false type: string required: - name - parent type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns a folder object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing or incorrect. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user does not have the required access to perform the action. This might be because they don't have access to the folder or parent folder, or because the application does not have permission to write files and folders. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the parent folder could not be found, or the authenticated user does not have access to the parent folder. * `not_found` when the authenticated user does not have access to the parent folder "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. * `item_name_in_use`: Returned if a folder with the name already exists in the parent folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create folder tags: - Folders x-box-enable-explorer: true x-box-tag: folders /folders/trash/items: get: description: |- Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter. operationId: get_folders_trash_items parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - description: |- Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. example: true in: query name: usemarker required: false schema: type: boolean - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: |- The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. example: ASC in: query name: direction required: false schema: enum: - ASC - DESC type: string - description: |- Defines the **second** attribute by which items are sorted. Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. This parameter is not supported when using marker-based pagination. example: id in: query name: sort required: false schema: enum: - id - name - date - size type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Items" description: Returns a list of items that have been deleted "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` can appear when the `sort`, `direction` or `offset` parameter is provided when using marker based pagination, or when the `marker` parameter is provided but `usemarker` is set to `false` or `null`. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List trashed items tags: - Trashed items x-box-tag: trashed_items "/folders/{folder_id}": delete: description: |- Deletes a folder, either permanently or by moving it to the trash. operationId: delete_folders_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string - description: |- Delete a folder that is not empty by recursively deleting the folder and all of its content. example: true in: query name: recursive required: false schema: type: boolean responses: "204": description: |- Returns an empty response when the folder is successfully deleted or moved to the trash. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user makes a bad request. * `folder_not_empty`: Returned if the folder is not empty. Use the `recursive` query parameter to recursively delete the folder and its contents. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder, or when a folder lock has been applied to the folder to prevent deletion. * `insufficient_scope`: Returned an error if the application does not have the right scope to delete folders. Make sure your application has been configured to read and write all files and folders stored in Box. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the folder could not be found, or the authenticated user does not have access to the folder. * `not_found` when the authenticated user does not have access to the folder. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `operation_blocked_temporary`: Returned if the folder is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. "503": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the operation takes longer than 60 seconds. The operation will continue after this response has been returned. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete folder tags: - Folders x-box-sanitized: true x-box-tag: folders get: description: |- Retrieves details for a folder, including the first 100 entries in the folder. To fetch more items within the folder, please use the [Get items in a folder](#get-folders-id-items) endpoint. operationId: get_folders_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - 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. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?field=metadata.enterprise_12345.contractTemplate`. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. example: "1" in: header name: if-none-match required: false schema: type: string - description: |- The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns a folder, including the first 100 entries in the folder. To fetch more items within the folder, please use the [Get items in a folder](#get-folders-id-items) endpoint. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. "304": description: |- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `folder_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get folder information tags: - Folders x-box-enable-explorer: true x-box-sanitized: true x-box-tag: folders post: description: |- Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. # Folder locking During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders. operationId: post_folders_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: name: description: An optional new name for the folder. example: Restored Photos type: string parent: allOf: - description: The parent for this item properties: id: description: The ID of parent item example: "123" type: string type: object - description: |- Specifies an optional ID of a folder to restore the folder to when the original folder no longer exists. Please be aware that this ID will only be used if the original folder no longer exists. Use this ID to provide a fallback location to restore the folder to if the original location has been deleted. type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/TrashFolderRestored" description: Returns a folder object when the folder has been restored. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user does not have access to the folder the folder is being restored to, or the user does not have permission to restore folders from the trash. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the folder is not in the trash. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * Returned an error if there is a folder with the same name in the destination folder. * `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Restore folder tags: - Trashed folders x-box-tag: trashed_folders put: description: |- Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. operationId: put_folders_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Ensures this item hasn't recently changed before making changes. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `412 Precondition Failed` if it has changed since. example: "1" in: header name: if-match required: false schema: type: string requestBody: content: application/json: schema: properties: can_non_owners_invite: description: |- Specifies if users who are not the owner of the folder can invite new collaborators to the folder. example: true type: boolean can_non_owners_view_collaborators: description: |- Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. When setting this field to `false`, it is required to also set `can_non_owners_invite_collaborators` to `false` if it has not already been set. example: true type: boolean collections: description: |- An array of collections to make this folder a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the folder from all collections. [1]: ../advanced-files-and-folders/#get-collections items: description: The bare basic reference for an object properties: id: description: The unique identifier for this object example: "11446498" type: string type: description: The type for this object example: file type: string title: Reference type: object type: array description: description: The optional description of this folder example: Legal contracts for the new ACME deal maxLength: 256 nullable: false type: string folder_upload_email: allOf: - description: The Write Folder Upload Email object properties: access: 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. enum: - open - collaborators example: open nullable: false type: string title: Folder upload email type: object - description: |- Setting this object enables the upload email address. This email address can be used by users to directly upload files directly to the folder via email. Setting the value to `null` will disable the email address. is_collaboration_restricted_to_enterprise: description: |- Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. example: true type: boolean name: description: The optional new name for this folder. example: New Folder type: string parent: description: |- The parent folder for this folder. Use this to move the folder or to restore it out of the trash. properties: id: description: The ID of the new parent folder example: "0" type: string type: object shared_link: allOf: - description: |- Defines a shared link for an item. Set this to `null` to remove the shared link. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link type: string type: object - description: Enables the creation of a shared link for a folder. sync_state: 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 example: synced nullable: false type: string tags: 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. example: - approved items: type: string maxItems: 100 minItems: 1 type: array type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. This call will return synchronously. This holds true even when moving folders with a large a large number of items in all of its descendants. For very large folders, this means the call could take minutes or hours to return. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid, or if a folder lock is preventing a move operation. * `bad_request` when a parameter is missing or incorrect. This error also happens when a password is set for a shared link with an access type of `open`. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder or parent folder, or if the folder is being moved and a folder lock has been applied to prevent such operations. * `insufficient_scope`: Returned an error if the application does not have the right scope to update folders. Make sure your application has been configured to read and write all files and folders stored in Box. * `forbidden`: Returned when the user is not allowed to perform this action for other users. This can include trying to create a Shared Link with a `company` access level on a free account. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. Returns an error if there are too many actions in the request body. * `operation_limit_exceeded`: Returned when the user passes any parameters in addition to the `parent.id` in the request body. The calls to this endpoint have to be split up. The first call needs to include only the `parent.id`, the next call can include other parameters. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the folder or parent folder could not be found, or the authenticated user does not have access to either folder. * `not_found` when the authenticated user does not have access to the folder or parent folder. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. * `item_name_in_use`: Returned if a folder with the name already exists in the parent folder. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. "503": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the operation takes longer than 60 seconds. The operation will continue after this response has been returned. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update folder tags: - Folders x-box-enable-explorer: true x-box-sanitized: true x-box-tag: folders "/folders/{folder_id}#add_shared_link": put: description: Adds a shared link to a folder. operationId: put_folders_id#add_shared_link parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: |- The settings for the shared link to create on the folder. Use an empty object (`{}`) to use the default settings for shared links. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean can_edit: description: |- This value can only be `false` for items with a `type` of `folder`. example: false type: boolean can_preview: description: |- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: false can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: folder schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns the base representation of a folder with a new shared link attached. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when there is an incorrect permission combination "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `folder_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add shared link to folder tags: - Shared links (Folders) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_folders "/folders/{folder_id}#get_shared_link": get: description: Gets the information for a shared link on a folder. operationId: get_folders_id#get_shared_link parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: false can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: folder schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns the base representation of a folder with the additional shared link information. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `folder_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shared link for folder tags: - Shared links (Folders) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_folders "/folders/{folder_id}#remove_shared_link": put: description: Removes a shared link from a folder. operationId: put_folders_id#remove_shared_link parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: |- By setting this value to `null`, the shared link is removed from the folder. example: null nullable: true type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: null type: folder schema: $ref: "#/components/schemas/Folder--Full" description: Returns a basic representation of a folder, with the shared link removed. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `folder_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove shared link from folder tags: - Shared links (Folders) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_folders "/folders/{folder_id}#update_shared_link": put: description: Updates a shared link on a folder. operationId: put_folders_id#update_shared_link parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: The settings for the shared link to update. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean can_edit: description: |- This value can only be `false` for items with a `type` of `folder`. example: false type: boolean can_preview: description: |- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: false can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: folder schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns a basic representation of the folder, with the updated shared link attached. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when there is an incorrect permission combination "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `folder_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update shared link on folder tags: - Shared links (Folders) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_folders "/folders/{folder_id}/collaborations": get: description: |- Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder. operationId: get_folders_id_collaborations parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Collaborations" description: |- Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List folder collaborations tags: - Collaborations (List) x-box-tag: list_collaborations "/folders/{folder_id}/copy": post: description: |- Creates a copy of a folder within a destination folder. The original folder will not be changed. operationId: post_folders_id_copy parameters: - description: |- The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied. example: "0" in: path name: folder_id required: true schema: nullable: false type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: nullable: false properties: name: description: |- An optional new name for the copied folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either. example: New Folder maxLength: 255 minLength: 1 type: string parent: description: The destination folder to copy the folder to. properties: id: description: The ID of parent folder example: "0" type: string required: - id type: object required: - parent type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields. "304": description: |- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing. * `item_name_too_long` when the new folder name is too long. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user does not have the right permissions to copy a folder. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if either the source or destination folder could not be found, or the authenticated user does not have access to either folders. * `not_found` when the authenticated user does not have access to the parent folder "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if a folder by this name already exists in the destination folder, or if the destination folder is locked. * `item_name_in_use` when a folder with the same name already exists. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error when trying to copy the root folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Copy folder tags: - Folders x-box-enable-explorer: true x-box-tag: folders "/folders/{folder_id}/items": get: description: |- Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, please use the [Get a folder](#get-folders-id) endpoint instead. operationId: get_folders_id_items parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - 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. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?field=metadata.enterprise_12345.contractTemplate`. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. example: true in: query name: usemarker required: false schema: type: boolean - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: false schema: type: string - description: |- Defines the **second** attribute by which items are sorted. Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. This parameter is not supported for marker-based pagination on the root folder (the folder with an ID of `0`). example: id in: query name: sort required: false schema: enum: - id - name - date - size type: string - description: |- The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. example: ASC in: query name: direction required: false schema: enum: - ASC - DESC type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Items" description: Returns a collection of files, folders, and web links contained in a folder. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `folder_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List items in folder tags: - Folders x-box-enable-explorer: true x-box-sanitized: true x-box-tag: folders "/folders/{folder_id}/metadata": get: description: |- Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`. operationId: get_folders_id_metadata parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Metadatas" description: |- Returns all the metadata associated with a folder. This API does not support pagination and will therefore always return all of the metadata associated to the folder. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the request parameters are not valid. * `forbidden` - this operation is not allowed on the Root folder. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the user does not have access to the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List metadata instances on folder tags: - Metadata instances (Folders) x-box-sanitized: true x-box-tag: folder_metadata "/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo": delete: description: |- Removes any classifications from a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`. operationId: delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string responses: "204": description: |- Returns an empty response when the classification is successfully deleted. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the folder does not have any classification applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the classification metadata template with the was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the method was not allowed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove classification from folder tags: - Classifications on folders x-box-sanitized: true x-box-tag: folder_classifications get: description: |- Retrieves the classification metadata instance that has been applied to a folder. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`. operationId: get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Classification" description: |- Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the method was not allowed. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get classification on folder tags: - Classifications on folders x-box-sanitized: true x-box-tag: folder_classifications post: description: |- Adds a classification to a folder by specifying the label of the classification to add. This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`. operationId: post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string requestBody: content: application/json: schema: properties: Box__Security__Classification__Key: description: |- The name of the classification to apply to this folder. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. example: Sensitive type: string type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Classification" description: |- Returns the classification template instance that was applied to the folder. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of them metadata template already exists on the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add classification to folder tags: - Classifications on folders x-box-sanitized: true x-box-tag: folder_classifications put: description: |- Updates a classification on a folder. The classification can only be updated if a classification has already been applied to the folder before. When editing classifications, only values are defined for the enterprise will be accepted. operationId: put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string requestBody: content: application/json-patch+json: schema: description: |- A list containing the one change to make, to update the classification label. items: description: |- The operation to perform on the classification metadata template instance. In this case, it use used to replace the value stored for the `Box__Security__Classification__Key` field with a new value. properties: op: description: "`replace`" enum: - replace example: replace type: string path: description: "`/Box__Security__Classification__Key`" enum: - /Box__Security__Classification__Key example: /Box__Security__Classification__Key type: string value: description: |- The name of the classification to apply to this folder. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. example: Sensitive type: string type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Classification" description: Returns the updated classification metadata template instance. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch operations. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update classification on folder tags: - Classifications on folders x-box-sanitized: true x-box-tag: folder_classifications "/folders/{folder_id}/metadata/{scope}/{template_key}": delete: description: Deletes a piece of folder metadata. operationId: delete_folders_id_metadata_id_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string responses: "204": description: |- Returns an empty response when the metadata is successfully deleted. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the request parameters are not valid. This may happen of the `scope` is not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the folder does not have an instance of the metadata template applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove metadata instance from folder tags: - Metadata instances (Folders) x-box-sanitized: true x-box-tag: folder_metadata get: description: |- Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`. operationId: get_folders_id_metadata_id_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Metadata" description: |- An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get metadata instance on folder tags: - Metadata instances (Folders) x-box-sanitized: true x-box-tag: folder_metadata post: description: |- Applies an instance of a metadata template to a folder. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console. operationId: post_folders_id_metadata_id_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string requestBody: content: application/json: schema: additionalProperties: description: |- A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be an a list of zero or more fields, as this template allows for any generic key-value pairs to be stored on the template. example: Aaron Levie type: string x-box-example-key: name example: name: Aaron Levie type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Metadata" description: |- Returns the instance of the template that was applied to the folder, including the data that was applied to the template. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of them metadata template already exists on the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create metadata instance on folder tags: - Metadata instances (Folders) x-box-enable-explorer: false x-box-sanitized: true x-box-tag: folder_metadata put: description: |- Updates a piece of metadata on a folder. The metadata instance can only be updated if the template has already been applied to the folder before. When editing metadata, only values that match the metadata template schema will be accepted. The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed. operationId: put_folders_id_metadata_id_id parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string requestBody: content: application/json-patch+json: schema: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) specification for the changes to make to the metadata instance. The changes are represented as a JSON array of operation objects. items: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a change to make to the metadata instance. properties: from: description: |- The location in the metadata JSON object to move or copy a value from. Required for `move` or `copy` operations and must be in the format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901). example: /nextState type: string op: description: |- The type of change to perform on the template. Some of these are hazardous as they will change existing templates. enum: - add - replace - remove - test - move - copy example: add type: string path: description: |- The location in the metadata JSON object to apply the changes to, in the format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901). The path must always be prefixed with a `/` to represent the root of the template. The characters `~` and `/` are reserved characters and must be escaped in the key. example: /currentState type: string value: description: |- The value to be set or tested. Required for `add`, `replace`, and `test` operations. For `add`, if the value exists already the previous value will be overwritten by the new value. For `replace`, the value must exist before replacing. For `test`, the existing value at the `path` location must match the specified value. example: reviewed type: string title: A metadata instance update operation type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Metadata" description: |- Returns the updated metadata template instance, with the custom template data included. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch objects. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update metadata instance on folder tags: - Metadata instances (Folders) x-box-sanitized: true x-box-tag: folder_metadata "/folders/{folder_id}/trash": delete: description: |- Permanently deletes a folder that is in the trash. This action cannot be undone. operationId: delete_folders_id_trash parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string responses: "204": description: |- Returns an empty response when the folder was permanently deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the folder is not in the trash. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Permanently remove folder tags: - Trashed folders x-box-tag: trashed_folders get: description: |- Retrieves a folder that has been moved to the trash. Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. operationId: get_folders_id_trash parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/TrashFolder" description: |- Returns the folder that was trashed, including information about when the it was moved to the trash. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the folder can not be found directly in the trash. Please note that a `HTTP 404` is also returned if any of the folder's parent folders have been moved to the trash. In that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get trashed folder tags: - Trashed folders x-box-tag: trashed_folders "/folders/{folder_id}/watermark": delete: description: Removes the watermark from a folder. operationId: delete_folders_id_watermark parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string responses: "204": description: |- An empty response will be returned when the watermark was successfully deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the folder did not have a watermark applied to it default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove watermark from folder tags: - Watermarks (Folders) x-box-tag: folder_watermarks get: description: Retrieve the watermark for a folder. operationId: get_folders_id_watermark parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Watermark" description: |- Returns an object containing information about the watermark associated for to this folder. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the folder does not have a watermark applied. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get watermark for folder tags: - Watermarks (Folders) x-box-tag: folder_watermarks put: description: Applies or update a watermark on a folder. operationId: put_folders_id_watermark parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: path name: folder_id required: true schema: nullable: false type: string requestBody: content: application/json: schema: properties: watermark: description: The watermark to imprint on the folder properties: imprint: description: |- The type of watermark to apply. Currently only supports one option. enum: - default example: default type: string required: - imprint type: object required: - watermark type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Watermark" description: |- Returns an updated watermark if a watermark already existed on this folder. "201": content: application/json: schema: $ref: "#/components/schemas/Watermark" description: |- Returns a new watermark if no watermark existed on this folder yet. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Apply watermark to folder tags: - Watermarks (Folders) x-box-tag: folder_watermarks /group_memberships: post: description: |- Creates a group membership. Only users with admin-level permissions will be able to use this API. operationId: post_group_memberships parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: configurable_permissions: additionalProperties: description: A key value pair of custom permissions. example: true type: boolean x-box-example-key: can_run_reports description: |- Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of `member`. Setting these permissions overwrites the default access levels of an admin. Specifying a value of "null" for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default. example: can_run_reports: true type: object group: description: The group to add the user to. properties: id: description: The ID of the group to add the user to example: "4545523" type: string required: - id type: object role: description: The role of the user in the group. enum: - member - admin example: member type: string user: description: The user to add to the group. properties: id: description: The ID of the user to add to the group example: "1434325" type: string required: - id type: object required: - user - group type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/GroupMembership" description: Returns a new group membership object. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user cannot be added to a group. * `forbidden_by_policy`: Adding a user to a group is forbidden due to information barrier restrictions. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add user to group tags: - Group memberships x-box-tag: memberships "/group_memberships/{group_membership_id}": delete: description: |- Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. operationId: delete_group_memberships_id parameters: - description: The ID of the group membership. example: "434534" in: path name: group_membership_id required: true schema: type: string responses: "204": description: |- A blank response is returned if the membership was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove user from group tags: - Group memberships x-box-tag: memberships get: description: |- Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. operationId: get_group_memberships_id parameters: - description: The ID of the group membership. example: "434534" in: path name: group_membership_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/GroupMembership" description: Returns the group membership object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get group membership tags: - Group memberships x-box-tag: memberships put: description: |- Updates a user's group membership. Only admins of this group or users with admin-level permissions will be able to use this API. operationId: put_group_memberships_id parameters: - description: The ID of the group membership. example: "434534" in: path name: group_membership_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: configurable_permissions: additionalProperties: description: A key value pair of custom permissions. example: true type: boolean x-box-example-key: can_run_reports description: |- Custom configuration for the permissions an admin if a group will receive. This option has no effect on members with a role of `member`. Setting these permissions overwrites the default access levels of an admin. Specifying a value of "null" for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default. example: can_run_reports: true type: object role: description: The role of the user in the group. enum: - member - admin example: member type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/GroupMembership" description: Returns a new group membership object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update group membership tags: - Group memberships x-box-tag: memberships /groups: get: description: |- Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups. operationId: get_groups parameters: - description: |- Limits the results to only groups whose `name` starts with the search term. example: Engineering in: query name: filter_term required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/Groups" description: |- Returns a collection of group objects. If there are no groups, an empty collection will be returned. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List groups for enterprise tags: - Groups x-box-tag: groups post: description: |- Creates a new group of users in an enterprise. Only users with admin permissions can create new groups. operationId: post_groups parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: description: description: A human readable description of the group. example: '"Customer Support Group - as imported from Active Directory"' maxLength: 255 type: string external_sync_identifier: description: |- An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an **Active Directory Object ID** or a **Google Group ID**. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems. example: AD:123456 type: string invitability_level: description: |- Specifies who can invite the group to collaborate on folders. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group. enum: - admins_only - admins_and_members - all_managed_users example: admins_only type: string member_viewability_level: description: |- Specifies who can see the members of the group. * `admins_only` - the enterprise admin, co-admins, group's group admin * `admins_and_members` - all admins and group members * `all_managed_users` - all managed users in the enterprise enum: - admins_only - admins_and_members - all_managed_users example: admins_only type: string name: description: |- The name of the new group to be created. This name must be unique within the enterprise. example: Customer Support type: string provenance: description: |- Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups. example: Active Directory maxLength: 255 type: string required: - name type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Group" description: Returns the new group object. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error a conflict is stopping the group from being created. * `invalid_parameter`: Often returned if the group name is not unique in the enterprise. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create group tags: - Groups x-box-tag: groups /groups/terminate_sessions: post: description: |- Validates the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions. Returns the status for the POST request. operationId: post_groups_terminate_sessions requestBody: content: application/json: schema: properties: group_ids: description: A list of group IDs example: - "123456" - "456789" items: type: string type: array required: - group_ids type: object responses: "202": content: application/json: schema: $ref: "#/components/schemas/SessionTerminationMessage" description: Returns a message about the request status. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are not valid. * `Groups can not be NULL or EMPTY` when no value is provided * `group id format is string` when the provided group id format is incorrect * `Supported payload format is JSON` when the provided payload format is incorrect "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if there are insufficient permissions. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the resource could not be found. "429": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the request limit is exceeded. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if there is an internal server issue. "503": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the request timed out. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create jobs to terminate user group session tags: - Groups x-box-tag: session_termination "/groups/{group_id}": delete: description: |- Permanently deletes a group. Only users with admin-level permissions will be able to use this API. operationId: delete_groups_id parameters: - description: The ID of the group. example: "57645" in: path name: group_id required: true schema: type: string responses: "204": description: |- A blank response is returned if the group was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove group tags: - Groups x-box-tag: groups get: description: |- Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API. operationId: get_groups_id parameters: - description: The ID of the group. example: "57645" in: path name: group_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Group--Full" description: Returns the group object default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get group tags: - Groups x-box-tag: groups put: description: |- Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API. operationId: put_groups_id parameters: - description: The ID of the group. example: "57645" in: path name: group_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: description: description: A human readable description of the group. example: '"Customer Support Group - as imported from Active Directory"' maxLength: 255 type: string external_sync_identifier: description: |- An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an **Active Directory Object ID** or a **Google Group ID**. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems. example: AD:123456 type: string invitability_level: description: |- Specifies who can invite the group to collaborate on folders. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group. enum: - admins_only - admins_and_members - all_managed_users example: admins_only type: string member_viewability_level: description: |- Specifies who can see the members of the group. * `admins_only` - the enterprise admin, co-admins, group's group admin * `admins_and_members` - all admins and group members * `all_managed_users` - all managed users in the enterprise enum: - admins_only - admins_and_members - all_managed_users example: admins_only type: string name: description: |- The name of the new group to be created. Must be unique within the enterprise. example: Customer Support type: string provenance: description: |- Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`. Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups. example: Active Directory maxLength: 255 type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Group--Full" description: Returns the updated group object. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error a conflict is stopping the group from being created. * `invalid_parameter`: Often returned if the group name is not unique in the enterprise. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update group tags: - Groups x-box-tag: groups "/groups/{group_id}/collaborations": get: description: |- Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups. Each collaboration object has details on which files or folders the group has access to and with what role. operationId: get_groups_id_collaborations parameters: - description: The ID of the group. example: "57645" in: path name: group_id required: true schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/Collaborations" description: |- Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List group collaborations tags: - Collaborations (List) x-box-tag: list_collaborations "/groups/{group_id}/memberships": get: description: |- Retrieves all the members for a group. Only members of this group or users with admin-level permissions will be able to use this API. operationId: get_groups_id_memberships parameters: - description: The ID of the group. example: "57645" in: path name: group_id required: true schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/GroupMemberships" description: |- Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List members of group tags: - Group memberships x-box-tag: memberships /invites: post: description: |- Invites an existing external user to join an enterprise. The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console. operationId: post_invites parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: actionable_by: description: The user to invite properties: login: description: The login of the invited user example: john@example.com type: string required: - id type: object enterprise: description: The enterprise to invite the user to properties: id: description: The ID of the enterprise example: "1232234" type: string required: - id type: object required: - enterprise - actionable_by type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Invite" description: Returns a new invite object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create user invite tags: - Invites x-box-tag: invites "/invites/{invite_id}": get: description: Returns the status of a user invite. operationId: get_invites_id parameters: - description: The ID of an invite. example: "213723" in: path name: invite_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/Invite" description: Returns an invite object default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get user invite status tags: - Invites x-box-tag: invites /legal_hold_policies: get: description: |- Retrieves a list of legal hold policies that belong to an enterprise. operationId: get_legal_hold_policies parameters: - description: |- Limits results to policies for which the names start with this search term. This is a case-insensitive prefix. example: Sales Policy in: query name: policy_name required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/LegalHoldPolicies" description: Returns a list of legal hold policies. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List all legal hold policies tags: - Legal hold policies x-box-tag: legal_hold_policies post: description: Create a new legal hold policy. operationId: post_legal_hold_policies requestBody: content: application/json: schema: properties: description: description: A description for the policy. example: A custom policy for the sales team maxLength: 500 type: string filter_ended_at: description: |- The filter end date. When this policy is applied using a `custodian` legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required if `is_ongoing` is set to `false`. example: 2012-12-18T10:53:43-08:00 format: date-time maxLength: 500 type: string filter_started_at: description: |- The filter start date. When this policy is applied using a `custodian` legal hold assignments, it will only apply to file versions created or uploaded inside of the date range. Other assignment types, such as folders and files, will ignore the date filter. Required if `is_ongoing` is set to `false`. example: 2012-12-12T10:53:43-08:00 format: date-time maxLength: 500 type: string is_ongoing: description: |- Whether new assignments under this policy should continue applying to files even after initialization. When this policy is applied using a legal hold assignment, it will continue applying the policy to any new file versions even after it has been applied. For example, if a legal hold assignment is placed on a user today, and that user uploads a file tomorrow, that file will get held. This will continue until the policy is retired. Required if no filter dates are set. example: true type: boolean policy_name: description: The name of the policy. example: Sales Policy maxLength: 254 type: string required: - policy_name type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/LegalHoldPolicy" description: Returns a new legal hold policy object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if required parameters are missing, or neither `is_ongoing` or filter dates are specified. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if a policy with this name already exists. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create legal hold policy tags: - Legal hold policies x-box-tag: legal_hold_policies "/legal_hold_policies/{legal_hold_policy_id}": delete: description: |- Delete an existing legal hold policy. This is an asynchronous process. The policy will not be fully deleted yet when the response returns. operationId: delete_legal_hold_policies_id parameters: - description: The ID of the legal hold policy example: "324432" in: path name: legal_hold_policy_id required: true schema: type: string responses: "202": description: |- A blank response is returned if the policy was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove legal hold policy tags: - Legal hold policies x-box-tag: legal_hold_policies get: description: Retrieve a legal hold policy. operationId: get_legal_hold_policies_id parameters: - description: The ID of the legal hold policy example: "324432" in: path name: legal_hold_policy_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/LegalHoldPolicy" description: Returns a legal hold policy object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get legal hold policy tags: - Legal hold policies x-box-tag: legal_hold_policies put: description: Update legal hold policy. operationId: put_legal_hold_policies_id parameters: - description: The ID of the legal hold policy example: "324432" in: path name: legal_hold_policy_id required: true schema: type: string requestBody: content: application/json: schema: properties: description: description: A description for the policy. example: A custom policy for the sales team maxLength: 500 type: string policy_name: description: The name of the policy. example: Sales Policy maxLength: 254 type: string release_notes: description: Notes around why the policy was released. example: Required for GDPR maxLength: 500 type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/LegalHoldPolicy" description: Returns a new legal hold policy object. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if a policy with this name already exists. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update legal hold policy tags: - Legal hold policies x-box-tag: legal_hold_policies /legal_hold_policy_assignments: get: description: Retrieves a list of items a legal hold policy has been assigned to. operationId: get_legal_hold_policy_assignments parameters: - description: The ID of the legal hold policy example: "324432" in: query name: policy_id required: true schema: type: string - description: |- Filters the results by the type of item the policy was applied to. example: file in: query name: assign_to_type schema: enum: - file - file_version - folder - user type: string - description: |- Filters the results by the ID of item the policy was applied to. example: "1234323" in: query name: assign_to_id schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/LegalHoldPolicyAssignments" description: Returns a list of legal hold policy assignments. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List legal hold policy assignments tags: - Legal hold policy assignments x-box-tag: legal_hold_policy_assignments post: description: Assign a legal hold to a file, file version, folder, or user. operationId: post_legal_hold_policy_assignments requestBody: content: application/json: schema: properties: assign_to: description: The item to assign the policy to properties: id: description: The ID of item to assign the policy to example: "6564564" type: string type: description: The type of item to assign the policy to enum: - file - file_version - folder - user example: folder type: string required: - type - id type: object policy_id: description: The ID of the policy to assign. example: "123244" type: string required: - policy_id - assign_to type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/LegalHoldPolicyAssignment" description: Returns a new legal hold policy assignment. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Assign legal hold policy tags: - Legal hold policy assignments x-box-tag: legal_hold_policy_assignments "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}": delete: description: |- Remove a legal hold from an item. This is an asynchronous process. The policy will not be fully removed yet when the response returns. operationId: delete_legal_hold_policy_assignments_id parameters: - description: The ID of the legal hold policy assignment example: "753465" in: path name: legal_hold_policy_assignment_id required: true schema: type: string responses: "202": description: |- A blank response is returned if the assignment was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Unassign legal hold policy tags: - Legal hold policy assignments x-box-tag: legal_hold_policy_assignments get: description: Retrieve a legal hold policy assignment. operationId: get_legal_hold_policy_assignments_id parameters: - description: The ID of the legal hold policy assignment example: "753465" in: path name: legal_hold_policy_assignment_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/LegalHoldPolicyAssignment" description: Returns a legal hold policy object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get legal hold policy assignment tags: - Legal hold policy assignments x-box-tag: legal_hold_policy_assignments "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold": get: description: |- Get a list of previous file versions for a legal hold assignment. In some cases you may only need the latest file versions instead. In these cases, use the `GET /legal_hold_policy_assignments/:id/files_on_hold` API instead to return any current (latest) versions of a file for this legal hold policy assignment. Due to ongoing re-architecture efforts this API might not return all files held for this policy ID. Instead, this API will only return past file versions held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. operationId: get_legal_hold_policy_assignments_id_file_versions_on_hold parameters: - description: The ID of the legal hold policy assignment example: "753465" in: path name: legal_hold_policy_assignment_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersionLegalHolds" description: |- Returns the list of previous file versions held under legal hold for a specific legal hold policy assignment. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List previous file versions for legal hold policy assignment tags: - Legal hold policy assignments x-box-tag: legal_hold_policy_assignments "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold": get: description: |- Get a list of current file versions for a legal hold assignment. In some cases you may want to get previous file versions instead. In these cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API instead to return any previous versions of a file for this legal hold policy assignment. Due to ongoing re-architecture efforts this API might not return all file versions held for this policy ID. Instead, this API will only return the latest file version held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. operationId: get_legal_hold_policy_assignments_id_files_on_hold parameters: - description: The ID of the legal hold policy assignment example: "753465" in: path name: legal_hold_policy_assignment_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileVersionLegalHolds" description: |- Returns the list of current file versions held under legal hold for a specific legal hold policy assignment. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List current file versions for legal hold policy assignment tags: - Legal hold policy assignments x-box-tag: legal_hold_policy_assignments /metadata_cascade_policies: get: description: |- Retrieves a list of all the metadata cascade policies that are applied to a given folder. This can not be used on the root folder with ID `0`. operationId: get_metadata_cascade_policies parameters: - description: |- Specifies which folder to return policies for. This can not be used on the root folder with ID `0`. example: "31232" in: query name: folder_id required: true schema: type: string - description: |- The ID of the enterprise ID for which to find metadata cascade policies. If not specified, it defaults to the current enterprise. example: "31232" in: query name: owner_enterprise_id schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataCascadePolicies" description: Returns a list of metadata cascade policies "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error when any of the parameters are not in a valid format. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the folder can not be accessed. This error often happens when accessing the root folder with ID `0`. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the folder can not be found or the user does not have access to the folder. * `not_found` - The folder could not be found or the user does not have access to the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List metadata cascade policies tags: - Metadata cascade policies x-box-sanitized: true x-box-tag: metadata_cascade_policies post: description: |- Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to any files within that folder. In order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to. operationId: post_metadata_cascade_policies requestBody: content: application/json: schema: properties: folder_id: description: |- The ID of the folder to apply the policy to. This folder will need to already have an instance of the targeted metadata template applied to it. example: "1234567" type: string scope: description: |- The scope of the targeted metadata template. This template will need to already have an instance applied to the targeted folder. enum: - global - enterprise example: enterprise type: string templateKey: description: |- The key of the targeted metadata template. This template will need to already have an instance applied to the targeted folder. 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 example: productInfo type: string required: - folder_id - scope - templateKey type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/MetadataCascadePolicy" description: Returns a new of metadata cascade policy "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when any of the parameters are not in a valid format. * `bad_request` - Either the `scope`, `templateKey`, or `folder_id` are not in a valid format. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when trying to apply a policy to a restricted folder, for example the root folder with ID `0`. * `forbidden` - Although the folder ID was valid and the user has access to the folder, the policy could not be applied to this folder. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the template or folder can not be found, or when the user does not have access to the folder or template. * `instance_tuple_not_found` - The template could not be found or the user does not have access to the template. * `not_found` - The folder could not be found or the user does not have access to the folder. "409": content: application/json: schema: $ref: "#/components/schemas/ConflictError" description: |- Returns an error when a policy for this folder and template is already in place. * `tuple_already_exists` - A cascade policy for this combination of `folder_id`, `scope` and `templateKey` already exists. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create metadata cascade policy tags: - Metadata cascade policies x-box-sanitized: true x-box-tag: metadata_cascade_policies "/metadata_cascade_policies/{metadata_cascade_policy_id}": delete: description: Deletes a metadata cascade policy. operationId: delete_metadata_cascade_policies_id parameters: - description: The ID of the metadata cascade policy. example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7 in: path name: metadata_cascade_policy_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the policy is successfully deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove metadata cascade policy tags: - Metadata cascade policies x-box-sanitized: true x-box-tag: metadata_cascade_policies get: description: Retrieve a specific metadata cascade policy assigned to a folder. operationId: get_metadata_cascade_policies_id parameters: - description: The ID of the metadata cascade policy. example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7 in: path name: metadata_cascade_policy_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataCascadePolicy" description: Returns a metadata cascade policy "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get metadata cascade policy tags: - Metadata cascade policies x-box-sanitized: true x-box-tag: metadata_cascade_policies "/metadata_cascade_policies/{metadata_cascade_policy_id}/apply": post: description: |- Force the metadata on a folder with a metadata cascade policy to be applied to all of its children. This can be used after creating a new cascade policy to enforce the metadata to be cascaded down to all existing files within that folder. operationId: post_metadata_cascade_policies_id_apply parameters: - description: The ID of the cascade policy to force-apply. example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7 in: path name: metadata_cascade_policy_id required: true schema: type: string requestBody: content: application/json: schema: properties: conflict_resolution: description: |- Describes the desired behavior when dealing with the conflict where a metadata template already has an instance applied to a child. * `none` will preserve the existing value on the file * `overwrite` will force-apply the templates values over any existing values. enum: - none - overwrite example: none type: string required: - conflict_resolution type: object responses: "202": description: |- Returns an empty response when the API call was successful. The metadata cascade operation will be performed asynchronously. The API call will return directly, before the cascade operation is complete. There is currently no API to check for the status of this operation. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Force-apply metadata cascade policy to folder tags: - Metadata cascade policies x-box-sanitized: true x-box-tag: metadata_cascade_policies /metadata_queries/execute_read: post: 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. operationId: post_metadata_queries_execute_read requestBody: content: application/json: schema: $ref: "#/components/schemas/MetadataQuery" responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataQueryResults" description: Returns a list of files and folders that match this metadata query. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" 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" }`. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" 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`. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Query files/folders by metadata tags: - Search x-box-enable-explorer: true x-box-sanitized: true x-box-tag: search /metadata_query_indices: get: description: Retrieves the metadata query indices for a given scope and template key. operationId: get_metadata_query_indices parameters: - description: The scope of the metadata template example: global in: query name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: query name: template_key required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataQueryIndices" description: Returns a collection of metadata query indices for scope and template key. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error when any of the parameters are not in a valid format. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error when the scope and template combination cannot be found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List metadata query indices tags: - Search x-box-enable-explorer: true x-box-sanitized: true x-box-tag: search /metadata_templates: get: description: |- Finds a metadata template by searching for the ID of an instance of the template. operationId: get_metadata_templates parameters: - description: The ID of an instance of the metadata template to find. example: 01234500-12f1-1234-aa12-b1d234cb567e in: query name: metadata_instance_id required: true schema: format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplates" description: |- Returns a list containing the 1 metadata template that matches the instance ID. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Find metadata template by instance ID tags: - Metadata templates x-box-sanitized: true x-box-tag: metadata_templates /metadata_templates/enterprise: get: description: |- Used to retrieve all metadata templates created to be used specifically within the user's enterprise operationId: get_metadata_templates_enterprise parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplates" description: |- Returns all of the metadata templates within an enterprise and their corresponding schema. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List all metadata templates for enterprise tags: - Metadata templates x-box-sanitized: true x-box-tag: metadata_templates /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema: delete: description: |- Delete all classifications by deleting the classification metadata template. operationId: delete_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema responses: "204": description: |- Returns an empty response when the metadata template for classifications is successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete all classifications tags: - Classifications x-box-sanitized: true x-box-tag: classifications get: description: |- Retrieves the classification metadata template and lists all the classifications available to this enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. operationId: get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClassificationTemplate" description: |- Returns the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if any of the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when a template name is not correct. Please make sure the URL for the request is correct. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List all classifications tags: - Classifications x-box-sanitized: true x-box-tag: classifications /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add: put: description: |- Adds one or more new classifications to the list of classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add requestBody: content: application/json-patch+json: schema: description: |- An array that contains one or more classifications to add to the enterprise's list of classifications. items: description: A single classification to add to the enterprise. properties: data: description: The details of the classification to add. properties: classification: description: Additional details for the classification. properties: classificationDefinition: description: A longer description of the classification. example: Sensitive information that must not be shared. type: string colorID: description: |- An internal Box identifier used to assign a color to a classification label. Mapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows. * `0`: Yellow * `1`: Orange * `2`: Watermelon red * `3`: Purple rain * `4`: Light blue * `5`: Dark blue * `6`: Light green * `7`: Gray example: 4 type: number type: object key: description: |- The label of the classification as shown in the web and mobile interfaces. This is the only field required to add a classification. example: Sensitive type: string required: - key type: object fieldKey: description: "`Box__Security__Classification__Key`" example: Box__Security__Classification__Key type: string op: description: "`addEnumOption`" example: addEnumOption type: string required: - op - fieldKey - data type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClassificationTemplate" description: |- Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if any of the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when a template name is not correct. Please make sure the URL for the request is correct. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add classification tags: - Classifications x-box-sanitized: true x-box-tag: classifications /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#delete: put: description: |- Removes a classification from the list of classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#delete requestBody: content: application/json-patch+json: schema: description: An array that contains one or more classifications to remove. items: description: A single classification to remove. properties: enumOptionKey: description: The label of the classification to remove. example: Sensitive type: string fieldKey: description: "`Box__Security__Classification__Key`" example: Box__Security__Classification__Key type: string op: description: "`removeEnumOption`" example: removeEnumOption type: string required: - op - fieldKey - enumOptionKey type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClassificationTemplate" description: |- Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if any of the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when a template name is not correct. Please make sure the URL for the request is correct. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete classification tags: - Classifications x-box-sanitized: true x-box-tag: classifications /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update: put: description: |- Updates the labels and descriptions of one or more classifications available to the enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update requestBody: content: application/json-patch+json: schema: description: An array that contains one or more classifications to update. items: description: A single classification to update. properties: data: description: The details of the updated classification. properties: classification: description: Additional details for the classification. properties: classificationDefinition: description: A longer description of the classification. example: Sensitive information that must not be shared. type: string colorID: description: |- An internal Box identifier used to assign a color to a classification label. Mapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows. * `0`: Yellow * `1`: Orange * `2`: Watermelon red * `3`: Purple rain * `4`: Light blue * `5`: Dark blue * `6`: Light green * `7`: Gray example: 4 type: number type: object key: description: |- A new label for the classification, as it will be shown in the web and mobile interfaces. example: Very Sensitive type: string required: - key type: object enumOptionKey: description: The original label of the classification to change. example: Sensitive type: string fieldKey: description: "`Box__Security__Classification__Key`" example: Box__Security__Classification__Key type: string op: description: "`editEnumOption`" example: editEnumOption type: string required: - op - fieldKey - enumOptionKey - data type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClassificationTemplate" description: |- Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if any of the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when a template name is not correct. Please make sure the URL for the request is correct. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update classification tags: - Classifications x-box-sanitized: true x-box-tag: classifications /metadata_templates/global: get: description: |- Used to retrieve all generic, global metadata templates available to all enterprises using Box. operationId: get_metadata_templates_global parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplates" description: |- Returns all of the metadata templates available to all enterprises and their corresponding schema. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when the request parameters are not valid. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List all global metadata templates tags: - Metadata templates x-box-sanitized: true x-box-tag: metadata_templates /metadata_templates/schema: post: description: |- Creates a new metadata template that can be applied to files and folders. operationId: post_metadata_templates_schema requestBody: content: application/json: schema: properties: copyInstanceOnItemCopy: default: false description: |- Whether or not to copy any metadata attached to a file or folder when it is copied. By default, metadata is not copied along with a file or folder when it is copied. example: true type: boolean displayName: description: The display name of the template. example: Product Info maxLength: 4096 type: string fields: description: |- An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list. items: description: |- A field within a metadata template. Fields can be a basic text, date, or number field, or a list of options. properties: description: description: A description of the field. This is not shown to the user. example: The category maxLength: 4096 type: string displayName: description: |- The display name of the field as it is shown to the user in the web and mobile apps. example: Category maxLength: 4096 type: string hidden: description: |- Whether this field is hidden in the UI for the user and can only be set through the API instead. example: true type: boolean key: description: |- A unique identifier for the field. The identifier must be unique within the template to which it belongs. example: category maxLength: 256 type: string options: description: |- A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types. items: description: |- An option for a Metadata Template Field. Options only need to be provided for fields of type `enum` and `multiSelect`. Options represent the value(s) a user can select for the field either through the UI or through the API. properties: key: description: |- The text value of the option. This represents both the display name of the option and the internal key used when updating templates. example: Category 1 type: string required: - key title: Metadata Option (Write) type: object type: array type: description: |- The type of field. The basic fields are a `string` field for text, a `float` field for numbers, and a `date` fields to present the user with a date-time picker. Additionally, metadata templates support an `enum` field for a basic list of items, and ` multiSelect` field for a similar list of items where the user can select more than one value. enum: - string - float - date - enum - multiSelect example: string type: string required: - type - key - displayName title: Metadata Field (Write) type: object type: array hidden: default: false description: |- Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API. example: true type: boolean scope: description: |- The scope of the metadata template to create. Applications can only create templates for use within the authenticated user's enterprise. This value needs to be set to `enterprise`, as `global` scopes can not be created by applications. example: enterprise type: string templateKey: description: |- A unique identifier for the template. This identifier needs to be unique across the enterprise for which the metadata template is being created. When not provided, the API will create a unique `templateKey` based on the value of the `displayName`. example: productInfo maxLength: 64 pattern: ^[a-zA-Z_][-a-zA-Z0-9_]*$ type: string required: - scope - displayName type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplate" description: The schema representing the metadata template created. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the user does not have the permission to create the metadata template. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the application tries to create a template with the `global` scope. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create metadata template tags: - Metadata templates x-box-requires-admin: true x-box-sanitized: true x-box-tag: metadata_templates /metadata_templates/schema#classifications: post: description: |- When an enterprise does not yet have any classifications, this API call initializes the classification template with an initial set of classifications. If an enterprise already has a classification, the template will already exist and instead an API call should be made to add additional classifications. operationId: post_metadata_templates_schema#classifications requestBody: content: application/json: schema: properties: copyInstanceOnItemCopy: description: "`false`" example: false type: boolean displayName: description: "`Classification`" enum: - Classification example: Classification type: string fields: description: |- The classification template holds one field, which holds all the valid classification values. items: description: |- The `enum` field which holds all the valid classification values. properties: displayName: description: "`Classification`" enum: - Classification example: Classification type: string hidden: description: "`false`" example: false type: boolean key: description: "`Box__Security__Classification__Key`" enum: - Box__Security__Classification__Key example: Box__Security__Classification__Key type: string options: description: |- The actual list of classifications that are present on this template. items: description: An individual classification. properties: key: description: |- The display name and key this classification. This will be show in the Box UI. example: Sensitive type: string staticConfig: description: Additional information about the classification. properties: classification: description: Additional information about the classification. properties: classificationDefinition: description: A longer description of the classification. example: Sensitive information type: string colorID: description: |- An identifier used to assign a color to a classification label. Mapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows. * `0`: Yellow * `1`: Orange * `2`: Watermelon red * `3`: Purple rain * `4`: Light blue * `5`: Dark blue * `6`: Light green * `7`: Gray example: 4 type: number type: object type: object type: object type: array type: description: "`enum`" enum: - enum example: enum type: string type: object type: array hidden: description: "`false`" example: false type: boolean scope: description: |- The scope in which to create the classifications. This should be `enterprise` or `enterprise_{id}` where `id` is the unique ID of the enterprise. enum: - enterprise example: enterprise type: string templateKey: description: "`securityClassification-6VMVochwUWo`" enum: - securityClassification-6VMVochwUWo example: securityClassification-6VMVochwUWo type: string required: - scope - displayName type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClassificationTemplate" description: |- Returns a new `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if any of the request parameters are not valid. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when a template name is not correct. Please make sure the URL for the request is correct. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add initial classifications tags: - Classifications x-box-sanitized: true x-box-tag: classifications "/metadata_templates/{scope}/{template_key}/schema": delete: description: |- Delete a metadata template and its instances. This deletion is permanent and can not be reversed. operationId: delete_metadata_templates_id_id_schema parameters: - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string responses: "204": description: |- Returns an empty response when the metadata template is successfully deleted. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Request body does not contain a valid metadata schema. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Request body contains a scope that the user is not allowed to create a template for. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove metadata template tags: - Metadata templates x-box-sanitized: true x-box-tag: metadata_templates get: description: |- Retrieves a metadata template by its `scope` and `templateKey` values. To find the `scope` and `templateKey` for a template, list all templates for an enterprise or globally, or list all templates applied to a file or folder. operationId: get_metadata_templates_id_id_schema parameters: - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplate" description: |- Returns the metadata template matching the `scope` and `template` name. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if any of the request parameters are not valid. * `bad_request`: Often returned when the scope of the template is not recognised. Please make sure to use either `enterprise` or `global` as the `scope` value. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when a template with the given `scope` and `template_key` can not be found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get metadata template by name tags: - Metadata templates x-box-sanitized: true x-box-tag: metadata_templates put: description: |- Updates a metadata template. The metadata template can only be updated if the template already exists. The update is applied atomically. If any errors occur during the application of the operations, the metadata template will not be changed. operationId: put_metadata_templates_id_id_schema parameters: - description: The scope of the metadata template example: global in: path name: scope required: true schema: enum: - global - enterprise type: string - description: The name of the metadata template example: properties in: path name: template_key required: true schema: type: string requestBody: content: application/json-patch+json: schema: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) specification for the changes to make to the metadata template. The changes are represented as a JSON array of operation objects. items: description: |- A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a change to make to the metadata instance. properties: data: additionalProperties: description: The value of a custom data entry. example: Aaron Levie type: string x-box-example-key: name description: |- The data for the operation. This will vary depending on the operation being performed. example: name: Aaron Levie type: object enumOptionKey: description: |- For operations that affect a single `enum` option this defines the key of the option that is affected. example: option1 type: string enumOptionKeys: description: |- For operations that affect multiple `enum` options this defines the keys of the options that are affected. example: - option1 - option2 - option3 items: type: string type: array fieldKey: description: |- For operations that affect a single field this defines the key of the field that is affected. example: category type: string fieldKeys: description: |- For operations that affect multiple fields this defines the keys of the fields that are affected. example: - category - name items: type: string type: array multiSelectOptionKey: description: |- For operations that affect a single multi select option this defines the key of the option that is affected. example: option1 type: string multiSelectOptionKeys: description: |- For operations that affect multiple multi select options this defines the keys of the options that are affected. example: - option1 - option2 - option3 items: type: string type: array op: description: |- The type of change to perform on the template. Some of these are hazardous as they will change existing templates. enum: - editTemplate - addField - reorderFields - addEnumOption - reorderEnumOptions - reorderMultiSelectOptions - addMultiSelectOption - editField - removeField - editEnumOption - removeEnumOption - editMultiSelectOption - removeMultiSelectOption example: addEnumOption type: string required: - op title: A metadata template update operation type: object type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplate" description: |- Returns the updated metadata template, with the custom template data included. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: The request body does not contain a valid metadata schema. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- The request body contains a scope that the user is not allowed to create templates for. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: The requested template could not be found default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update metadata template tags: - Metadata templates x-box-sanitized: true x-box-tag: metadata_templates "/metadata_templates/{template_id}": get: description: Retrieves a metadata template by its ID. operationId: get_metadata_templates_id parameters: - description: The ID of the template example: f7a9891f in: path name: template_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplate" description: Returns the metadata template that matches the ID. "400": content: application/json: schema: $ref: "#/components/schemas/MetadataTemplate" description: |- Returned if any of the request parameters are not valid. * `bad_request`: Often returned with a message when the ID of the template is not recognised. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get metadata template by ID tags: - Metadata templates x-box-sanitized: true x-box-tag: metadata_templates /oauth2/revoke: post: description: |- Revoke an active Access Token, effectively logging a user out that has been previously authenticated. operationId: post_oauth2_revoke requestBody: content: application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PostOAuth2Revoke" responses: "200": description: Returns an empty response when the token was successfully revoked. "400": content: application/json: schema: $ref: "#/components/schemas/OAuth2Error" description: An authentication error. default: content: application/json: schema: $ref: "#/components/schemas/OAuth2Error" description: An authentication error. security: [] servers: - description: Server for server-side authentication url: https://api.box.com summary: Revoke access token tags: - Authorization x-box-tag: authorization /oauth2/token: post: description: |- Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion. An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the [authorize](#get-authorize) endpoint and Box will send you an authorization code. You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls. operationId: post_oauth2_token requestBody: content: application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PostOAuth2Token" responses: "200": content: application/json: schema: $ref: "#/components/schemas/AccessToken" description: |- Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer `. "400": content: application/json: schema: $ref: "#/components/schemas/OAuth2Error" description: An authentication error. default: content: application/json: schema: $ref: "#/components/schemas/OAuth2Error" description: An authentication error. security: [] servers: - description: Server for server-side authentication url: https://api.box.com summary: Request access token tags: - Authorization x-box-tag: authorization /oauth2/token#refresh: post: description: Refresh an Access Token using its client ID, secret, and refresh token. operationId: post_oauth2_token#refresh requestBody: content: application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PostOAuth2Token--RefreshAccessToken" responses: "200": content: application/json: schema: $ref: "#/components/schemas/AccessToken" description: |- Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer `. "400": content: application/json: schema: $ref: "#/components/schemas/OAuth2Error" description: An authentication error. default: content: application/json: schema: $ref: "#/components/schemas/OAuth2Error" description: An authentication error. security: [] servers: - description: Server for server-side authentication url: https://api.box.com summary: Refresh access token tags: - Authorization x-box-is-variation: true x-box-tag: authorization /recent_items: get: description: |- Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed. operationId: get_recent_items parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecentItems" description: Returns a list recent items access by a user. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List recently accessed items tags: - Recent items x-box-enable-explorer: true x-box-tag: recent_items /retention_policies: get: description: Retrieves all of the retention policies for an enterprise. operationId: get_retention_policies parameters: - description: |- Filters results by a case sensitive prefix of the name of retention policies. example: Sales Policy in: query name: policy_name required: false schema: type: string - description: Filters results by the type of retention policy. example: finite in: query name: policy_type required: false schema: enum: - finite - indefinite type: string - description: Filters results by the ID of the user who created policy. example: "21312321" in: query name: created_by_user_id required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RetentionPolicies" description: Returns a list retention policies in the enterprise. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns a `bad_request` if a non existent `policy_type` was specified. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the user specified in `created_by_user_id` does not exist. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List retention policies tags: - Retention policies x-box-tag: retention_policies post: description: Creates a retention policy. operationId: post_retention_policies requestBody: content: application/json: schema: properties: are_owners_notified: description: |- Whether owner and co-owners of a file are notified when the policy nears expiration. enum: - true - false example: true type: boolean can_owner_extend_retention: description: |- Whether the owner of a file will be allowed to extend the retention. enum: - true - false example: true type: boolean custom_notification_recipients: description: |- A list of users notified when the retention policy duration is about to end. items: $ref: "#/components/schemas/User--Mini" type: array description: description: The additional text description of the retention policy. example: Policy to retain all reports for at least one month type: string disposition_action: description: |- The disposition action of the retention policy. `permanently_delete` deletes the content retained by the policy permanently. `remove_retention` lifts retention policy from the content, allowing it to be deleted by users once the retention policy has expired. enum: - permanently_delete - remove_retention example: permanently_delete type: string policy_name: description: The name for the retention policy example: Some Policy Name type: string policy_type: description: |- The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown. enum: - finite - indefinite example: finite type: string retention_length: description: |- The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. example: "365" format: int32 minimum: 1 type: string retention_type: description: |- Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. enum: - modifiable - non-modifiable example: modifiable type: string required: - policy_name - policy_type - disposition_action type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/RetentionPolicy" description: Returns a new retention policy object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `bad_request` error with the `retention_length` was specified for a `infinite` retention policy, an incorrect `disposition_action` was set, or description exceeds maximum length of 500 characters. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if a retention policy with the given name already exists default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create retention policy tags: - Retention policies x-box-tag: retention_policies "/retention_policies/{retention_policy_id}": delete: description: Permanently deletes a retention policy. operationId: delete_retention_policies_id parameters: - description: The ID of the retention policy. example: "982312" in: path name: retention_policy_id required: true schema: type: string responses: "204": description: Returns an empty response when the policy has been deleted. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the policy is non-modifiable or the user does not have the required access to perform the action. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the policy is not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete retention policy tags: - Retention policies x-box-scopes: - manage_data_retention - data_retention x-box-tag: retention_policies get: description: Retrieves a retention policy. operationId: get_retention_policies_id parameters: - description: The ID of the retention policy. example: "982312" in: path name: retention_policy_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/RetentionPolicy" description: Returns the retention policy object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get retention policy tags: - Retention policies x-box-tag: retention_policies put: description: Updates a retention policy. operationId: put_retention_policies_id parameters: - description: The ID of the retention policy. example: "982312" in: path name: retention_policy_id required: true schema: type: string requestBody: content: application/json: schema: properties: are_owners_notified: description: |- Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. enum: - true - false example: false type: boolean can_owner_extend_retention: description: |- Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. example: false type: boolean custom_notification_recipients: description: A list of users notified when the retention duration is about to end. items: $ref: "#/components/schemas/User--Mini" type: array description: description: The additional text description of the retention policy. example: Policy to retain all reports for at least one month type: string disposition_action: description: |- The disposition action of the retention policy. `permanently_delete` deletes the content retained by the policy permanently. `remove_retention` lifts retention policy from the content, allowing it to be deleted by users once the retention policy has expired. enum: - permanently_delete - remove_retention example: permanently_delete type: string policy_name: description: The name for the retention policy example: Some Policy Name type: string retention_length: description: |- The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. example: "365" format: int32 type: string retention_type: description: |- Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. When updating a retention policy, you can use `non-modifiable` type only. You can convert a `modifiable` policy to `non-modifiable`, but not the other way around. example: non-modifiable type: string status: description: |- Used to retire a retention policy. If not retiring a policy, do not include this parameter or set it to `null`. example: retired type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/RetentionPolicy" description: Returns the updated retention policy object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `bad_request` if an incorrect `disposition_action` was set or description exceeds maximum length of 500 characters. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when a user wants to shorten the duration of a non-modifiable policy, or to convert a non-modifiable policy to a modifiable one. Note: Lengthening policy duration is allowed. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if a retention policy with the given name already exists default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update retention policy tags: - Retention policies x-box-tag: retention_policies "/retention_policies/{retention_policy_id}/assignments": get: description: |- Returns a list of all retention policy assignments associated with a specified retention policy. operationId: get_retention_policies_id_assignments parameters: - description: The ID of the retention policy. example: "982312" in: path name: retention_policy_id required: true schema: type: string - description: The type of the retention policy assignment to retrieve. example: metadata_template in: query name: type required: false schema: enum: - folder - enterprise - metadata_template type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/RetentionPolicyAssignments" description: |- Returns a list of the retention policy assignments associated with the specified retention policy. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if an unknown `type` is specified. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List retention policy assignments tags: - Retention policy assignments x-box-tag: retention_policy_assignments /retention_policy_assignments: post: description: Assigns a retention policy to an item. operationId: post_retention_policy_assignments requestBody: content: application/json: schema: properties: assign_to: description: The item to assign the policy to properties: id: description: |- The ID of item to assign the policy to. Set to `null` or omit when `type` is set to `enterprise`. example: "6564564" type: string type: description: The type of item to assign the policy to. enum: - enterprise - folder - metadata_template example: metadata_template type: string required: - type - id type: object filter_fields: description: |- If the `assign_to` type is `metadata_template`, then optionally add the `filter_fields` parameter which will require an array of objects with a field entry and a value entry. Currently only one object of `field` and `value` is supported. items: properties: field: description: The metadata attribute key id. example: a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4 type: string value: description: |- The metadata attribute field id. For value, only enum and multiselect types are supported. example: 0c27b756-0p87-4fe0-a43a-59fb661ccc4e type: string type: object type: array policy_id: description: The ID of the retention policy to assign example: "173463" type: string start_date_field: description: |- The date the retention policy assignment begins. If the `assigned_to` type is `metadata_template`, this field can be a date field's metadata attribute key id. example: upload_date type: string required: - policy_id - assign_to type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/RetentionPolicyAssignment" description: Returns a new retention policy assignment object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if an `id` is specified while assigning the retention policy to an enterprise. Returns an error if `start_date_field` is present but `assign_to.type` is not `metadata_template` Returns an error if `start_date_field` is present, but belongs to a different metadata template than the one specified in `assign_to.id` Returns an error if `start_date_field` is present, but the `retention_policy` has a `retention_length` of "indefinite" Returns an error if `start_date_field` is present, but cannot be resolved to a valid metadata date field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if no retention policy with the given `policy_id` exists. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if a retention policy of equal or greater length has already been assigned to this item. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Assign retention policy tags: - Retention policy assignments x-box-tag: retention_policy_assignments "/retention_policy_assignments/{retention_policy_assignment_id}": delete: description: |- Removes a retention policy assignment applied to content. operationId: delete_retention_policy_assignments_id parameters: - description: The ID of the retention policy assignment. example: "1233123" in: path name: retention_policy_assignment_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the policy assignment is successfully deleted. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the assignment relates to a retention policy that cannot be modified. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the retention policy assignment does not exist. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove retention policy assignment tags: - Retention policy assignments x-box-tag: retention_policy_assignments get: description: Retrieves a retention policy assignment operationId: get_retention_policy_assignments_id parameters: - description: The ID of the retention policy assignment. example: "1233123" in: path name: retention_policy_assignment_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/RetentionPolicyAssignment" description: Returns the retention policy assignment object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get retention policy assignment tags: - Retention policy assignments x-box-tag: retention_policy_assignments "/retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention": get: description: |- Returns a list of file versions under retention for a retention policy assignment. operationId: get_retention_policy_assignments_id_file_versions_under_retention parameters: - description: The ID of the retention policy assignment. example: "1233123" in: path name: retention_policy_assignment_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/FilesUnderRetention" description: |- Returns a list of file versions under retention that are associated with the specified retention policy assignment. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if `retention_policy_assignment_id` is not specified. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get file versions under retention tags: - Retention policy assignments x-box-tag: retention_policy_assignments "/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention": get: description: Returns a list of files under retention for a retention policy assignment. operationId: get_retention_policy_assignments_id_files_under_retention parameters: - description: The ID of the retention policy assignment. example: "1233123" in: path name: retention_policy_assignment_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/FilesUnderRetention" description: |- Returns a list of files under retention that are associated with the specified retention policy assignment. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if `retention_policy_assignment_id` is not specified. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get files under retention tags: - Retention policy assignments x-box-tag: retention_policy_assignments /search: get: description: |- Searches for files, folders, web links, and shared files across the users content or across the entire enterprise. operationId: get_search parameters: - description: |- The string to search for. This query is matched against item names, descriptions, text content of files, and various other fields of the different item types. This parameter supports a variety of operators to further refine the results returns. * `""` - by wrapping a query in double quotes only exact matches are returned by the API. Exact searches do not return search matches based on specific character sequences. Instead, they return matches based on phrases, that is, word sequences. For example: A search for `"Blue-Box"` may return search results including the sequence `"blue.box"`, `"Blue Box"`, and `"Blue-Box"`; any item containing the words `Blue` and `Box` consecutively, in the order specified. * `AND` - returns items that contain both the search terms. For example, a search for `marketing AND BoxWorks` returns items that have both `marketing` and `BoxWorks` within its text in any order. It does not return a result that only has `BoxWorks` in its text. * `OR` - returns items that contain either of the search terms. For example, a search for `marketing OR BoxWorks` returns a result that has either `marketing` or `BoxWorks` within its text. Using this operator is not necessary as we implicitly interpret multi-word queries as `OR` unless another supported boolean term is used. * `NOT` - returns items that do not contain the search term provided. For example, a search for `marketing AND NOT BoxWorks` returns a result that has only `marketing` within its text. Results containing `BoxWorks` are omitted. We do not support lower case (that is, `and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`) operators. This field is required unless the `mdfilters` parameter is defined. example: sales in: query name: query required: false schema: type: string - 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. example: user_content in: query name: scope required: false schema: default: user_content enum: - user_content - enterprise_content type: string - 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 explode: false in: query name: file_extensions required: false schema: items: type: string type: array - 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 explode: false in: query name: created_at_range required: false schema: items: type: string type: array - 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 explode: false in: query name: updated_at_range required: false schema: items: type: string type: array - 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 explode: false in: query name: size_range required: false schema: items: type: integer type: array - 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" explode: false in: query name: owner_user_ids required: false schema: items: type: string type: array - 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" explode: false in: query name: recent_updater_user_ids required: false schema: items: type: string type: array - 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. example: - "4535234" - "234123235" - "2654345" explode: false in: query name: ancestor_folder_ids required: false schema: items: type: string type: array - description: |- Limits the search results to any items that match the search query for a specific part of the file, for example the file description. Content types are defined as a comma separated lists of Box recognized content types. The allowed content types are as follows. * `name` - The name of the item, as defined by its `name` field. * `description` - The description of the item, as defined by its `description` field. * `file_content` - The actual content of the file. * `comments` - The content of any of the comments on a file or folder. * `tags` - Any tags that are applied to an item, as defined by its `tags` field. example: - name - description explode: false in: query name: content_types required: false schema: items: enum: - name - description - file_content - comments - tag type: string type: array - description: |- Limits the search results to any items of this type. This parameter only takes one value. By default the API returns items that match any of these types. * `file` - Limits the search results to files * `folder` - Limits the search results to folders * `web_link` - Limits the search results to web links, also known as bookmarks example: file in: query name: type required: false schema: enum: - file - folder - web_link type: string - description: |- Determines if the search should look in the trash for items. By default, this API only returns search results for items not currently in the trash (`non_trashed_only`). * `trashed_only` - Only searches for items currently in the trash * `non_trashed_only` - Only searches for items currently not in the trash example: non_trashed_only in: query name: trash_content required: false schema: default: non_trashed_only enum: - non_trashed_only - trashed_only type: string - 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. example: - filters: category: online scope: enterprise templateKey: contract in: query name: mdfilters required: false schema: description: |- A list of metadata templates to filter the search results by. Required unless `query` parameter is defined. items: $ref: "#/components/schemas/MetadataFilter" maxItems: 1 minItems: 1 type: array x-example: - filters: category: online contractValue: 1000000 scope: enterprise templateKey: contract - 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. example: modified_at in: query name: sort required: false schema: default: relevance enum: - modified_at - relevance type: string - 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. example: ASC in: query name: direction required: false schema: default: DESC enum: - DESC - ASC type: string - description: |- Defines the maximum number of items to return as part of a page of results. example: 100 in: query name: limit required: false schema: default: 30 format: int64 maximum: 200 type: integer - 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) example: true in: query name: include_recent_shared_links required: false schema: default: false type: boolean - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - 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 name: deleted_user_ids required: false schema: items: type: string type: array - 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 name: deleted_at_range required: false schema: items: type: string type: array responses: "200": content: application/json: schema: oneOf: - $ref: "#/components/schemas/SearchResults" - $ref: "#/components/schemas/SearchResultsWithSharedLinks" description: |- Returns a collection of search results. If there are no matching search results, the `entries` array will be empty. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request was not valid. This can have multiple reasons and the `context_info` object will provide you with more details. * `missing_parameter` - Please provide at least the `query` or `mdfilters` query parameter in a search. * `invalid_parameter` - Any of the fields might not be in the right format. This could for example mean that one of the RFC3339 dates is incorrect, or a string is provided where an integer is expected. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user does not have the permission to make this API call. * The developer provided a `scope` of `enterprise_content` but did not request this scope to be enabled for the user through our support channels. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user does not have access to an item mentioned in the request. * The developer provided a folder ID in `ancestor_folder_ids` that either does not exist or the user does not have access to. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Search for content tags: - Search x-box-enable-explorer: true x-box-tag: search /shared_items: get: description: |- Returns the file represented by a shared link. A shared file can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared file when only given a shared link. The `shared_link_permission_options` array field can be returned by requesting it in the `fields` query parameter. operationId: get_shared_items parameters: - description: |- Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. example: "1" in: header name: if-none-match required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- A header containing the shared link and optional password for the shared link. The format for this header is as follows. `shared_link=[link]&shared_link_password=[password]` example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/File--Full" description: |- Returns a full file resource if the shared link is valid and the user has access to it. "304": description: |- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Find file for shared link tags: - Shared links (Files) x-box-enable-explorer: true x-box-tag: shared_links_files /shared_items#folders: get: description: |- Return the folder represented by a shared link. A shared folder can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared folder when only given a shared link. operationId: get_shared_items#folders parameters: - description: |- Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. example: "1" in: header name: if-none-match required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- A header containing the shared link and optional password for the shared link. The format for this header is as follows. `shared_link=[link]&shared_link_password=[password]` example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns a full folder resource if the shared link is valid and the user has access to it. "304": description: |- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Find folder for shared link tags: - Shared links (Folders) x-box-enable-explorer: true x-box-tag: shared_links_folders /shared_items#web_links: get: description: |- Returns the web link represented by a shared link. A shared web link can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared web link when only given a shared link. operationId: get_shared_items#web_links parameters: - description: |- Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. example: "1" in: header name: if-none-match required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- A header containing the shared link and optional password for the shared link. The format for this header is as follows. `shared_link=[link]&shared_link_password=[password]` example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebLink" description: |- Returns a full file resource if the shared link is valid and the user has access to it. "304": description: |- Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Find web link for shared link tags: - Shared links (Web Links) x-box-enable-explorer: true x-box-tag: shared_links_web_links /shield_information_barrier_reports: get: description: Lists shield information barrier reports with specific IDs. operationId: get_shield_information_barrier_reports parameters: - description: The ID of the shield information barrier. example: "1910967" in: query name: shield_information_barrier_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: properties: entries: description: A list of shield barrier reports. items: $ref: "#/components/schemas/ShieldInformationBarrierReport" type: array 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string type: object description: Returns a paginated list of shield information barrier report objects. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List shield information barrier reports tags: - Shield information barrier reports x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_reports post: description: Creates a shield information barrier report for a given barrier. operationId: post_shield_information_barrier_reports requestBody: content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierReference" responses: "201": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierReport" description: Returns the shield information barrier report information object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier report was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `conflict` error if a shield information barrier report is currently being created. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create shield information barrier report tags: - Shield information barrier reports x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_reports "/shield_information_barrier_reports/{shield_information_barrier_report_id}": get: description: Retrieves a shield information barrier report by its ID. operationId: get_shield_information_barrier_reports_id parameters: - description: The ID of the shield information barrier Report. example: "3423" in: path name: shield_information_barrier_report_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierReport" description: Returns the shield information barrier report object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier Report was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shield information barrier report by ID tags: - Shield information barrier reports x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_reports /shield_information_barrier_segment_members: get: description: |- Lists shield information barrier segment members based on provided segment IDs. operationId: get_shield_information_barrier_segment_members parameters: - description: The ID of the shield information barrier segment. example: "3423" in: query name: shield_information_barrier_segment_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: properties: entries: items: $ref: "#/components/schemas/ShieldInformationBarrierSegmentMember" type: array 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string type: object description: |- Returns a paginated list of shield information barrier segment member objects. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List shield information barrier segment members tags: - Shield information barrier segment members x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_members post: description: Creates a new shield information barrier segment member. operationId: post_shield_information_barrier_segment_members requestBody: content: application/json: schema: properties: shield_information_barrier: $ref: "#/components/schemas/ShieldInformationBarrier--Base" shield_information_barrier_segment: description: |- The `type` and `id` of the requested shield information barrier segment. properties: id: description: |- The ID reference of the requesting shield information barrier segment. example: "432554" type: string type: description: The type of the shield barrier segment for this member. enum: - shield_information_barrier_segment example: shield_information_barrier_segment type: string type: object type: description: -| A type of the shield barrier segment member. enum: - shield_information_barrier_segment_member example: shield_information_barrier_segment_member type: string user: allOf: - $ref: "#/components/schemas/User--Base" - description: The `type` and `id` of the requested shield information barrier segment Member. required: - shield_information_barrier_segment - user type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierSegmentMember" description: Returns a new shield information barrier segment Member object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the shield information barrier or Segment was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create shield information barrier segment member tags: - Shield information barrier segment members x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_members "/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}": delete: description: |- Deletes a shield information barrier segment member based on provided ID. operationId: delete_shield_information_barrier_segment_members_id parameters: - description: The ID of the shield information barrier segment Member. example: "7815" in: path name: shield_information_barrier_segment_member_id required: true schema: type: string responses: "204": description: |- Returns an empty response if the segment member was deleted successfully. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier segment member was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete shield information barrier segment member by ID tags: - Shield information barrier segment members x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_members get: description: |- Retrieves a shield information barrier segment member by its ID. operationId: get_shield_information_barrier_segment_members_id parameters: - description: The ID of the shield information barrier segment Member. example: "7815" in: path name: shield_information_barrier_segment_member_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierSegmentMember" description: Returns the shield information barrier segment member object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier segment member was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shield information barrier segment member by ID tags: - Shield information barrier segment members x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_members /shield_information_barrier_segment_restrictions: get: description: |- Lists shield information barrier segment restrictions based on provided segment ID. operationId: get_shield_information_barrier_segment_restrictions parameters: - description: The ID of the shield information barrier segment. example: "3423" in: query name: shield_information_barrier_segment_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: properties: entries: items: $ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction" type: array 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string type: object description: |- Returns a paginated list of shield information barrier segment restriction objects. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List shield information barrier segment restrictions tags: - Shield information barrier segment restrictions x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_restrictions post: description: |- Creates a shield information barrier segment restriction object. operationId: post_shield_information_barrier_segment_restrictions requestBody: content: application/json: schema: properties: restricted_segment: description: |- The `type` and `id` of the restricted shield information barrier segment. properties: id: description: |- The ID reference of the restricted shield information barrier segment. example: "1910967" type: string type: description: |- The type of the restricted shield information barrier segment. enum: - shield_information_barrier_segment example: shield_information_barrier_segment type: string type: object shield_information_barrier: $ref: "#/components/schemas/ShieldInformationBarrier--Base" shield_information_barrier_segment: description: |- The `type` and `id` of the requested shield information barrier segment. properties: id: description: |- The ID reference of the requesting shield information barrier segment. example: "1910967" type: string type: description: The type of the shield barrier segment for this member. enum: - shield_information_barrier_segment example: shield_information_barrier_segment type: string type: object type: description: |- The type of the shield barrier segment restriction for this member. enum: - shield_information_barrier_segment_restriction example: shield_information_barrier_segment_restriction type: string required: - type - shield_information_barrier_segment - restricted_segment type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction" description: |- Returns the newly created Shield Information Barrier Segment Restriction object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier or Segment was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create shield information barrier segment restriction tags: - Shield information barrier segment restrictions x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_restrictions "/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}": delete: description: |- Delete shield information barrier segment restriction based on provided ID. operationId: delete_shield_information_barrier_segment_restrictions_id parameters: - description: The ID of the shield information barrier segment Restriction. example: "4563" in: path name: shield_information_barrier_segment_restriction_id required: true schema: type: string responses: "204": description: Empty body in response "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier segment restriction was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete shield information barrier segment restriction by ID tags: - Shield information barrier segment restrictions x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_restrictions get: description: |- Retrieves a shield information barrier segment restriction based on provided ID. operationId: get_shield_information_barrier_segment_restrictions_id parameters: - description: The ID of the shield information barrier segment Restriction. example: "4563" in: path name: shield_information_barrier_segment_restriction_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction" description: |- Returns the shield information barrier segment restriction object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier segment restriction was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shield information barrier segment restriction by ID tags: - Shield information barrier segment restrictions x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segment_restrictions /shield_information_barrier_segments: get: description: |- Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID. operationId: get_shield_information_barrier_segments parameters: - description: The ID of the shield information barrier. example: "1910967" in: query name: shield_information_barrier_id required: true schema: type: string - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: properties: entries: items: $ref: "#/components/schemas/ShieldInformationBarrierSegment" type: array 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string type: object description: Returns a paginated list of shield information barrier segment objects. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information Barrier of given ID was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List shield information barrier segments tags: - Shield information barrier segments x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segments post: description: Creates a shield information barrier segment. operationId: post_shield_information_barrier_segments requestBody: content: application/json: schema: properties: description: description: Description of the shield information barrier segment example: |- 'Corporate division that engages in advisory_based financial transactions on behalf of individuals, corporations, and governments.' type: string name: description: Name of the shield information barrier segment example: Investment Banking type: string shield_information_barrier: $ref: "#/components/schemas/ShieldInformationBarrier--Base" required: - shield_information_barrier - name type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierSegment" description: Returns a new shield information barrier segment object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the shield information barrier was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if there exists an shield information barrier segment with same name. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create shield information barrier segment tags: - Shield information barrier segments x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segments "/shield_information_barrier_segments/{shield_information_barrier_segment_id}": delete: description: |- Deletes the shield information barrier segment based on provided ID. operationId: delete_shield_information_barrier_segments_id parameters: - description: The ID of the shield information barrier segment. example: "3423" in: path name: shield_information_barrier_segment_id required: true schema: type: string responses: "204": description: Empty body in response "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier segment with specified ID was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete shield information barrier segment tags: - Shield information barrier segments x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segments get: description: Retrieves shield information barrier segment based on provided ID.. operationId: get_shield_information_barrier_segments_id parameters: - description: The ID of the shield information barrier segment. example: "3423" in: path name: shield_information_barrier_segment_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierSegment" description: Returns the shield information barrier segment object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier segment was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shield information barrier segment with specified ID tags: - Shield information barrier segments x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segments put: description: Updates the shield information barrier segment based on provided ID.. operationId: put_shield_information_barrier_segments_id parameters: - description: The ID of the shield information barrier segment. example: "3423" in: path name: shield_information_barrier_segment_id required: true schema: type: string requestBody: content: application/json: schema: description: |- An object containing update(s) to be made on the Shield Information Barrier Segment. Possible properties include 'name' and 'description', the value in object is the update. properties: description: description: |- The updated description for the shield information barrier segment. example: |- 'Corporate division that engages in advisory_based financial transactions on behalf of individuals, corporations, and governments.' nullable: true type: string name: description: The updated name for the shield information barrier segment. example: Investment Banking pattern: \S+ type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrierSegment" description: Returns the updated shield information barrier segment object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information Barrier Segment was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if there exists a shield information Barrier Segment with the same name. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update shield information barrier segment with specified ID tags: - Shield information barrier segments x-box-scopes: - manage_managed_users x-box-tag: shield_information_barrier_segments /shield_information_barriers: get: description: |- Retrieves a list of shield information barrier objects for the enterprise of JWT. operationId: get_shield_information_barriers parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: properties: entries: items: $ref: "#/components/schemas/ShieldInformationBarrier" type: array 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string type: object description: |- Returns a paginated list of shield information barrier objects, empty list if currently no barrier. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns a `not_found` error if could not find an enterprise using JWT. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List shield information barriers tags: - Shield information barriers x-box-scopes: - manage_managed_users x-box-tag: shield_information_barriers post: description: |- Creates a shield information barrier to separate individuals/groups within the same firm and prevents confidential information passing between them. operationId: post_shield_information_barriers requestBody: content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrier" responses: "201": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrier" description: Returns a new shield information barrier object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the enterprise was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create shield information barrier tags: - Shield information barriers x-box-scopes: - manage_managed_users x-box-tag: shield_information_barriers /shield_information_barriers/change_status: post: description: Change status of shield information barrier with the specified ID. operationId: post_shield_information_barriers_change_status requestBody: content: application/json: schema: properties: id: description: The ID of the shield information barrier. example: "1910967" type: string status: description: The desired status for the shield information barrier. enum: - pending - disabled example: pending type: string required: - id - status type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrier" description: Returns the updated shield information barrier object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier was not found. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if there exists Conflicts with existing information barriers. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add changed status of shield information barrier with specified ID tags: - Shield information barriers x-box-scopes: - manage_managed_users x-box-tag: shield_information_barriers "/shield_information_barriers/{shield_information_barrier_id}": get: description: Get shield information barrier based on provided ID.. operationId: get_shield_information_barriers_id parameters: - description: The ID of the shield information barrier. example: "1910967" in: path name: shield_information_barrier_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShieldInformationBarrier" description: Returns the shield information barrier object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns a `not_found` error if the shield information barrier was not found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shield information barrier with specified ID tags: - Shield information barriers x-box-scopes: - manage_managed_users x-box-tag: shield_information_barriers /sign_requests: get: description: |- Gets sign requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the sign request will not return in the list. operationId: get_sign_requests parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/SignRequests" description: Returns a collection of sign requests default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List sign requests tags: - Box Sign x-box-tag: sign_requests post: description: |- Creates a sign request. This involves preparing a document for signing and sending the sign request to signers. operationId: post_sign_requests requestBody: content: application/json: schema: $ref: "#/components/schemas/SignRequestCreateRequest" responses: "201": content: application/json: schema: $ref: "#/components/schemas/SignRequest" description: Returns a Sign Request object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create sign request tags: - Box Sign x-box-tag: sign_requests "/sign_requests/{sign_request_id}": get: description: Gets a sign request by ID. operationId: get_sign_requests_id parameters: - description: The ID of the sign request example: "33243242" in: path name: sign_request_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SignRequest" description: Returns a sign request "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the sign request cannot be found, the user does not have access to the sign request, or `sign_files` and/or `parent_folder` is deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get sign request by ID tags: - Box Sign x-box-tag: sign_requests "/sign_requests/{sign_request_id}/cancel": post: description: Cancels a sign request. operationId: post_sign_requests_id_cancel parameters: - description: The ID of the sign request example: "33243242" in: path name: sign_request_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SignRequest" description: Returns a Sign Request object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the sign request cannot be found or the user does not have access to the sign request. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Cancel sign request tags: - Box Sign x-box-tag: sign_requests "/sign_requests/{sign_request_id}/resend": post: description: Resends a sign request email to all outstanding signers. operationId: post_sign_requests_id_resend parameters: - description: The ID of the sign request example: "33243242" in: path name: sign_request_id required: true schema: type: string responses: "202": description: |- Returns an empty response when the API call was successful. The email notifications will be sent asynchronously. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the sign request cannot be found or the user does not have access to the sign request. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Resend sign request tags: - Box Sign x-box-tag: sign_requests "/skill_invocations/{skill_id}": put: description: |- An alternative method that can be used to overwrite and update all Box Skill metadata cards on a file. operationId: put_skill_invocations_id parameters: - description: The ID of the skill to apply this metadata for. example: "33243242" in: path name: skill_id required: true schema: type: string requestBody: content: application/json: schema: properties: file: description: The file to assign the cards to. properties: id: description: The ID of the file example: "3243244" type: string type: description: "`file`" enum: - file example: file type: string type: object file_version: description: The optional file version to assign the cards to. properties: id: description: The ID of the file version example: "731381601045" type: string type: description: "`file_version`" enum: - file_version example: file_version type: string type: object metadata: description: |- The metadata to set for this skill. This is a list of Box Skills cards. These cards will overwrite any existing Box skill cards on the file. properties: cards: description: A list of Box Skill cards to apply to this file. items: oneOf: - $ref: "#/components/schemas/KeywordSkillCard" - $ref: "#/components/schemas/TimelineSkillCard" - $ref: "#/components/schemas/TranscriptSkillCard" - $ref: "#/components/schemas/StatusSkillCard" type: array type: object status: description: Defines the status of this invocation. Set this to `success` when setting Skill cards. enum: - invoked - processing - success - transient_failure - permanent_failure example: success type: string usage: description: |- A descriptor that defines what items are affected by this call. Set this to the default values when setting a card to a `success` state, and leave it out in most other situations. properties: unit: description: "`file`" example: file type: string value: description: "`1`" example: 1 type: number type: object required: - status - metadata - file type: object responses: "200": description: Returns an empty response when the card has been successfully updated. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file could not be found or the user does not have access. * `not_found` - The file could not be found, or the user does not have access to the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update all Box Skill cards on file tags: - Skills x-box-tag: skills /storage_policies: get: description: Fetches all the storage policies in the enterprise. operationId: get_storage_policies parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/StoragePolicies" description: Returns a collection of storage policies. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List storage policies tags: - Storage policies x-box-tag: storage_policies "/storage_policies/{storage_policy_id}": get: description: Fetches a specific storage policy. operationId: get_storage_policies_id parameters: - description: The ID of the storage policy. example: "34342" in: path name: storage_policy_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/StoragePolicy" description: Returns a storage policy object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get storage policy tags: - Storage policies x-box-tag: storage_policies /storage_policy_assignments: get: description: Fetches all the storage policy assignment for an enterprise or user. operationId: get_storage_policy_assignments parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The target type to return assignments for example: user in: query name: resolved_for_type required: true schema: enum: - user - enterprise type: string - description: The ID of the user or enterprise to return assignments for example: "984322" in: query name: resolved_for_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/StoragePolicyAssignments" description: |- Returns a collection of storage policies for the enterprise or user. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List storage policy assignments tags: - Storage policy assignments x-box-tag: storage_policy_assignments post: description: Creates a storage policy assignment for an enterprise or user. operationId: post_storage_policy_assignments requestBody: content: application/json: schema: properties: assigned_to: description: |- The user or enterprise to assign the storage policy to. properties: id: description: The ID of the user or enterprise example: "9987987" type: string type: description: The type to assign the policy to. enum: - user - enterprise example: user type: string required: - type - id type: object storage_policy: description: |- The storage policy to assign to the user or enterprise properties: id: description: The ID of the storage policy to assign. example: "1434325" type: string type: description: The type to assign. enum: - storage_policy example: storage_policy type: string required: - type - id type: object required: - storage_policy - assigned_to type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/StoragePolicyAssignment" description: Returns the new storage policy assignment created. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Assign storage policy tags: - Storage policy assignments x-box-tag: storage_policy_assignments "/storage_policy_assignments/{storage_policy_assignment_id}": delete: description: |- Delete a storage policy assignment. Deleting a storage policy assignment on a user will have the user inherit the enterprise's default storage policy. There is a rate limit for calling this endpoint of only twice per user in a 24 hour time frame. operationId: delete_storage_policy_assignments_id parameters: - description: The ID of the storage policy assignment. example: "932483" in: path name: storage_policy_assignment_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the storage policy assignment is successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Unassign storage policy tags: - Storage policy assignments x-box-tag: storage_policy_assignments get: description: Fetches a specific storage policy assignment. operationId: get_storage_policy_assignments_id parameters: - description: The ID of the storage policy assignment. example: "932483" in: path name: storage_policy_assignment_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/StoragePolicyAssignment" description: Returns a storage policy assignment object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get storage policy assignment tags: - Storage policy assignments x-box-tag: storage_policy_assignments put: description: Updates a specific storage policy assignment. operationId: put_storage_policy_assignments_id parameters: - description: The ID of the storage policy assignment. example: "932483" in: path name: storage_policy_assignment_id required: true schema: type: string requestBody: content: application/json: schema: properties: storage_policy: description: |- The storage policy to assign to the user or enterprise properties: id: description: The ID of the storage policy to assign. example: "1434325" type: string type: description: The type to assign. enum: - storage_policy example: storage_policy type: string required: - type - id type: object required: - storage_policy type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/StoragePolicyAssignment" description: Returns an updated storage policy assignment object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update storage policy assignment tags: - Storage policy assignments x-box-tag: storage_policy_assignments /task_assignments: post: description: |- Assigns a task to a user. A task can be assigned to more than one user by creating multiple assignments. operationId: post_task_assignments requestBody: content: application/json: schema: properties: assign_to: description: The user to assign the task to. properties: id: description: |- The ID of the user to assign to the task. To specify a user by their email address use the `login` parameter. example: "3242343" type: string login: description: |- The email address of the user to assign to the task. To specify a user by their user ID please use the `id` parameter. example: john@example.com type: string type: object task: description: The task to assign to a user. properties: id: description: The ID of the task example: "11446498" type: string type: description: The type of the item to assign. enum: - task example: task type: string required: - id - type type: object required: - task - assign_to type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/TaskAssignment" description: Returns a new task assignment object. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if a change is attempted for a completed task or the user does not have access to the item linked to the task for the given task assignment. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error when the task cannot be found. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if any of the IDs for this request were not valid, or if the targeted user does not have access to the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Assign task tags: - Task assignments x-box-sanitized: true x-box-tag: task_assignments "/task_assignments/{task_assignment_id}": delete: description: Deletes a specific task assignment. operationId: delete_task_assignments_id parameters: - description: The ID of the task assignment. example: "12345" in: path name: task_assignment_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the task assignment was successfully deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the task assignment for the given ID does not exist or is inaccessible to your account. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Unassign task tags: - Task assignments x-box-sanitized: true x-box-tag: task_assignments get: description: Retrieves information about a task assignment. operationId: get_task_assignments_id parameters: - description: The ID of the task assignment. example: "12345" in: path name: task_assignment_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskAssignment" description: |- Returns a task assignment, specifying who the task has been assigned to and by whom. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the task assignment could not be found or the user does not have access to the file the task is assigned to. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get task assignment tags: - Task assignments x-box-sanitized: true x-box-tag: task_assignments put: description: |- Updates a task assignment. This endpoint can be used to update the state of a task assigned to a user. operationId: put_task_assignments_id parameters: - description: The ID of the task assignment. example: "12345" in: path name: task_assignment_id required: true schema: type: string requestBody: content: application/json: schema: properties: message: description: An optional message by the assignee that can be added to the task. example: Looks good to me type: string resolution_state: description: |- The state of the task assigned to the user. * For a task with an `action` value of `complete` this can be `incomplete` or `completed`. * For a task with an `action` of `review` this can be `incomplete`, `approved`, or `rejected`. enum: - completed - incomplete - approved - rejected example: completed type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskAssignment" description: Returns the updated task assignment object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if a resolution state is incompatible with the action type of the task. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the task assignment could not be found or the user does not have access to the file the task is assigned to. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update task assignment tags: - Task assignments x-box-sanitized: true x-box-tag: task_assignments /tasks: post: description: |- Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately. operationId: post_tasks requestBody: content: application/json: schema: properties: action: default: review description: |- The action the task assignee will be prompted to do. Must be * `review` defines an approval task that can be approved or rejected * `complete` defines a general task which can be completed enum: - review - complete example: review type: string completion_rule: default: all_assignees description: |- Defines which assignees need to complete this task before the task is considered completed. * `all_assignees` (default) requires all assignees to review or approve the the task in order for it to be considered completed. * `any_assignee` accepts any one assignee to review or approve the the task in order for it to be considered completed. enum: - all_assignees - any_assignee example: all_assignees type: string due_at: description: |- Defines when the task is due. Defaults to `null` if not provided. example: 2012-12-12T10:53:43-08:00 format: date-time type: string item: description: The file to attach the task to. properties: id: description: The ID of the file example: "11446498" type: string type: description: "`file`" enum: - file example: file type: string required: - id - type type: object message: default: "" description: An optional message to include with the task. example: Please review type: string required: - item type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Task" description: Returns the newly created task. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. This may be because the `action` or `completion_rule` are not one of the allowed values. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user does not have the permission to create a task on the file. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file could not be found or the user does not have access to the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create task tags: - Tasks x-box-sanitized: true x-box-tag: tasks "/tasks/{task_id}": delete: description: Removes a task from a file. operationId: delete_tasks_id parameters: - description: The ID of the task. example: "12345" in: path name: task_id required: true schema: type: string responses: "204": description: Returns an empty response when the task was successfully deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the task could not be found or the user does not have access to the file the task is assigned to. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove task tags: - Tasks x-box-sanitized: true x-box-tag: tasks get: description: Retrieves information about a specific task. operationId: get_tasks_id parameters: - description: The ID of the task. example: "12345" in: path name: task_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Task" description: Returns a task object. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the task could not be found or the user does not have access to the file the task is assigned to. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get task tags: - Tasks x-box-sanitized: true x-box-tag: tasks put: description: |- Updates a task. This can be used to update a task's configuration, or to update its completion state. operationId: put_tasks_id parameters: - description: The ID of the task. example: "12345" in: path name: task_id required: true schema: type: string requestBody: content: application/json: schema: properties: action: description: |- The action the task assignee will be prompted to do. Must be * `review` defines an approval task that can be approved or rejected * `complete` defines a general task which can be completed enum: - review - complete example: review type: string completion_rule: description: |- Defines which assignees need to complete this task before the task is considered completed. * `all_assignees` (default) requires all assignees to review or approve the the task in order for it to be considered completed. * `any_assignee` accepts any one assignee to review or approve the the task in order for it to be considered completed. enum: - all_assignees - any_assignee example: all_assignees type: string due_at: description: When the task is due at. example: 2012-12-12T10:53:43-08:00 format: date-time type: string message: description: The message included with the task. example: Please review type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Task" description: Returns the updated task object "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. This may be because the `action` or `completion_rule` are not one of the allowed values. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the user does not have the permission to update a task on the file. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the file could not be found or the user does not have access to the file. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update task tags: - Tasks x-box-sanitized: true x-box-tag: tasks "/tasks/{task_id}/assignments": get: description: Lists all of the assignments for a given task. operationId: get_tasks_id_assignments parameters: - description: The ID of the task. example: "12345" in: path name: task_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskAssignments" description: |- Returns a collection of task assignment defining what task on a file has been assigned to which users and by who. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the task could not be found or the user does not have access to the file the task is assigned to. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the task assignment ID was omitted in the request. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List task assignments tags: - Task assignments x-box-sanitized: true x-box-tag: task_assignments /terms_of_service_user_statuses: get: description: |- Retrieves an overview of users and their status for a terms of service, including Whether they have accepted the terms and when. operationId: get_terms_of_service_user_statuses parameters: - description: The ID of the terms of service. example: "324234" in: query name: tos_id required: true schema: type: string - description: Limits results to the given user ID. example: "123334" in: query name: user_id required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TermsOfServiceUserStatuses" description: Returns a list of terms of service statuses. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List terms of service user statuses tags: - Terms of service user statuses x-box-tag: terms_of_service_user_statuses post: description: Sets the status for a terms of service for a user. operationId: post_terms_of_service_user_statuses requestBody: content: application/json: schema: properties: is_accepted: description: Whether the user has accepted the terms. example: true type: boolean tos: description: The terms of service to set the status for. properties: id: description: The ID of terms of service example: "1232132" type: string type: description: The type of object. enum: - terms_of_service example: terms_of_service type: string required: - id - type type: object user: description: The user to set the status for. properties: id: description: The ID of user example: "3423423" type: string type: description: The type of object. enum: - user example: user type: string required: - id - type type: object required: - tos - user - is_accepted type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/TermsOfServiceUserStatus" description: Returns a terms of service status object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create terms of service status for new user tags: - Terms of service user statuses x-box-tag: terms_of_service_user_statuses "/terms_of_service_user_statuses/{terms_of_service_user_status_id}": put: description: Updates the status for a terms of service for a user. operationId: put_terms_of_service_user_statuses_id parameters: - description: The ID of the terms of service status. example: "324234" in: path name: terms_of_service_user_status_id required: true schema: type: string requestBody: content: application/json: schema: properties: is_accepted: description: Whether the user has accepted the terms. example: true type: boolean required: - is_accepted type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/TermsOfServiceUserStatus" description: Returns the updated terms of service status object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update terms of service status for existing user tags: - Terms of service user statuses x-box-tag: terms_of_service_user_statuses /terms_of_services: get: description: |- Returns the current terms of service text and settings for the enterprise. operationId: get_terms_of_services parameters: - description: Limits the results to the terms of service of the given type. example: managed in: query name: tos_type required: false schema: enum: - external - managed type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TermsOfServices" description: |- Returns a collection of terms of service text and settings for the enterprise. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List terms of services tags: - Terms of service x-box-tag: terms_of_services post: description: |- Creates a terms of service for a given enterprise and type of user. operationId: post_terms_of_services requestBody: content: application/json: schema: properties: status: description: Whether this terms of service is active. enum: - enabled - disabled example: enabled type: string text: description: |- The terms of service text to display to users. The text can be set to empty if the `status` is set to `disabled`. example: By collaborating on this file you are accepting... type: string tos_type: description: |- The type of user to set the terms of service for. enum: - external - managed example: managed type: string required: - status - text type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Task" description: Returns a new task object default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create terms of service tags: - Terms of service x-box-tag: terms_of_services "/terms_of_services/{terms_of_service_id}": get: description: Fetches a specific terms of service. operationId: get_terms_of_services_id parameters: - description: The ID of the terms of service. example: "324234" in: path name: terms_of_service_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TermsOfService" description: Returns a terms of service object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get terms of service tags: - Terms of service x-box-tag: terms_of_services put: description: Updates a specific terms of service. operationId: put_terms_of_services_id parameters: - description: The ID of the terms of service. example: "324234" in: path name: terms_of_service_id required: true schema: type: string requestBody: content: application/json: schema: properties: status: description: Whether this terms of service is active. enum: - enabled - disabled example: enabled type: string text: description: |- The terms of service text to display to users. The text can be set to empty if the `status` is set to `disabled`. example: By collaborating on this file you are accepting... type: string required: - status - text type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/TermsOfService" description: Returns an updated terms of service object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update terms of service tags: - Terms of service x-box-tag: terms_of_services /users: get: description: |- Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`. The application and the authenticated user need to have the permission to look up users in the entire enterprise. operationId: get_users parameters: - description: |- Limits the results to only users who's `name` or `login` start with the search term. For externally managed users, the search term needs to completely match the in order to find the user, and it will only return one user at a time. example: john in: query name: filter_term required: false schema: type: string - description: |- Limits the results to the kind of user specified. * `all` returns every kind of user for whom the `login` or `name` partially matches the `filter_term`. It will only return an external user if the login matches the `filter_term` completely, and in that case it will only return that user. * `managed` returns all managed and app users for whom the `login` or `name` partially matches the `filter_term`. * `external` returns all external users for whom the `login` matches the `filter_term` exactly. example: managed in: query name: user_type required: false schema: enum: - all - managed - external type: string - description: |- Limits the results to app users with the given `external_app_user_id` value. When creating an app user, an `external_app_user_id` value can be set. This value can then be used in this endpoint to find any users that match that `external_app_user_id` value. example: my-user-1234 in: query name: external_app_user_id required: false schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. example: true in: query name: usemarker required: false schema: type: boolean - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Users" description: Returns all of the users in the enterprise. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List enterprise users tags: - Users x-box-tag: users post: description: |- Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. operationId: post_users parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: address: description: The user’s address example: 900 Jefferson Ave, Redwood City, CA 94063 maxLength: 255 type: string can_see_managed_users: description: |- Whether the user can see other enterprise users in their contact list example: true type: boolean external_app_user_id: description: |- An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. example: my-user-1234 type: string is_exempt_from_device_limits: description: Whether to exempt the user from enterprise device limits example: true type: boolean is_exempt_from_login_verification: description: Whether the user must use two-factor authentication example: true type: boolean is_external_collab_restricted: description: |- Whether the user is allowed to collaborate with users outside their enterprise example: true type: boolean is_platform_access_only: description: Specifies that the user is an app user. example: true type: boolean is_sync_enabled: description: Whether the user can use Box Sync example: true type: boolean job_title: description: The user’s job title example: CEO maxLength: 100 type: string language: description: |- The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. example: en type: string login: description: |- The email address the user uses to log in Required, unless `is_platform_access_only` is set to `true`. example: boss@box.com type: string name: description: The name of the user example: Aaron Levie maxLength: 50 type: string phone: description: The user’s phone number example: "6509241374" maxLength: 100 type: string role: description: The user’s enterprise role enum: - coadmin - user example: user type: string space_amount: description: |- The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. example: 11345156112 format: int64 type: integer status: description: The user's account status enum: - active - inactive - cannot_delete_edit - cannot_delete_edit_upload example: active type: string timezone: description: The user's timezone example: Africa/Bujumbura format: timezone type: string tracking_codes: description: |- Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. items: $ref: "#/components/schemas/TrackingCode" type: array required: - name type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/User" description: Returns a user object for the newly created user. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create user tags: - Users x-box-tag: users /users/me: get: description: |- Retrieves information about the user who is currently authenticated. In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of. operationId: get_users_me parameters: - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/User--Full" description: Returns a single user object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get current user tags: - Users x-box-tag: users /users/terminate_sessions: post: description: |- Validates the roles and permissions of the user, and creates asynchronous jobs to terminate the user's sessions. Returns the status for the POST request. operationId: post_users_terminate_sessions requestBody: content: application/json: schema: properties: user_ids: description: A list of user IDs example: - "123456" - "456789" items: type: string type: array user_logins: description: A list of user logins example: - user@sample.com - user2@sample.com items: type: string type: array required: - user_ids - user_logins type: object responses: "202": content: application/json: schema: $ref: "#/components/schemas/SessionTerminationMessage" description: Returns a message about the request status. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are not valid. * `Users can not be NULL or EMPTY` when no value is provided * `User id format is string` when the provided user id format is incorrect * `Supported payload format is JSON` when the provided payload format is incorrect "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if there are insufficient permissions. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the resource could not be found. "429": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the rate limit is exceeded. "500": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if there is an internal server issue. "503": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the request timed out. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create jobs to terminate users session tags: - Users x-box-tag: session_termination "/users/{user_id}": delete: description: |- Deletes a user. By default this will fail if the user still owns any content. Move their owned content first before proceeding, or use the `force` field to delete the user and their files. operationId: delete_users_id parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string - description: |- Whether the user will receive email notification of the deletion example: true in: query name: notify schema: type: boolean - description: |- Whether the user should be deleted even if this user still own files example: true in: query name: force schema: type: boolean responses: "204": description: Removes the user and returns an empty response. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete user tags: - Users x-box-tag: users get: description: |- Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead. operationId: get_users_id parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/User--Full" description: |- Returns a single user object. Not all available fields are returned by default. Use the [fields](#param-fields) query parameter to explicitly request any specific fields using the [fields](#get-users-id--request--fields) parameter. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get user tags: - Users x-box-tag: users put: description: |- Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. operationId: put_users_id parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: address: description: The user’s address example: 900 Jefferson Ave, Redwood City, CA 94063 maxLength: 255 type: string can_see_managed_users: description: |- Whether the user can see other enterprise users in their contact list example: true type: boolean enterprise: description: |- Set this to `null` to roll the user out of the enterprise and make them a free user example: null nullable: true type: string external_app_user_id: description: |- An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. Note: In order to update this field, you need to request a token using the application that created the app user. example: my-user-1234 type: string is_exempt_from_device_limits: description: Whether to exempt the user from enterprise device limits example: true type: boolean is_exempt_from_login_verification: description: Whether the user must use two-factor authentication example: true type: boolean is_external_collab_restricted: description: |- Whether the user is allowed to collaborate with users outside their enterprise example: true type: boolean is_password_reset_required: description: Whether the user is required to reset their password example: true type: boolean is_sync_enabled: description: Whether the user can use Box Sync example: true type: boolean job_title: description: The user’s job title example: CEO maxLength: 100 type: string language: description: |- The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. example: en type: string login: description: |- The email address the user uses to log in Note: If the target user's email is not confirmed, then the primary login address cannot be changed. example: somename@box.com type: string name: description: The name of the user example: Aaron Levie maxLength: 50 type: string notification_email: description: |- An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Set this value to `null` to remove the notification email. nullable: true properties: email: description: The email address to send the notifications to. example: notifications@example.com type: string type: object notify: description: |- Whether the user should receive an email when they are rolled out of an enterprise example: true type: boolean phone: description: The user’s phone number example: "6509241374" maxLength: 100 type: string role: description: The user’s enterprise role enum: - coadmin - user example: user type: string space_amount: description: |- The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. example: 11345156112 format: int64 type: integer status: description: The user's account status enum: - active - inactive - cannot_delete_edit - cannot_delete_edit_upload example: active type: string timezone: description: The user's timezone example: Africa/Bujumbura format: timezone type: string tracking_codes: description: |- Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. items: $ref: "#/components/schemas/TrackingCode" type: array type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/User--Full" description: Returns the updated user object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` when a parameter is formatted incorrectly, for example when the `notification_email` has an incorrectly formatted email address. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user is not allowed to make the changes. * `access_denied_insufficient_permissions` when the user does not have the right permissions, for example when updating the notification email is turned off for the enterprise. * `denied_by_policy` when the user does not have the right permissions due to the information barrier restrictions. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update user tags: - Users x-box-enable-explorer: true x-box-tag: users "/users/{user_id}/avatar": delete: description: |- Removes an existing user avatar. You cannot reverse this operation. operationId: delete_users_id_avatar parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string responses: "204": description: "* `no_content`: Removes the avatar and returns an empty response." "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `forbidden`: Returned if the user does not have necessary permissions or is not activated. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `not_found`: Returned if the user or user avatar does not exist or cannot be found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Delete user avatar tags: - User avatars x-box-tag: avatars get: description: Retrieves an image of a the user's avatar. operationId: get_users_id_avatar parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string responses: "200": content: image/jpg: schema: description: The avatar format: binary type: string description: |- When an avatar can be found for the user the image data will be returned in the body of the response. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get user avatar tags: - User avatars x-box-tag: avatars post: description: Adds or updates a user avatar. operationId: post_users_id_avatar parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string requestBody: content: multipart/form-data: schema: properties: pic: description: |- The image file to be uploaded to Box. Accepted file extensions are `.jpg` or `.png`. The maximum file size is 1MB. format: binary type: string required: - pic type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/UserAvatar" description: |- * `ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated. "201": content: application/json: schema: $ref: "#/components/schemas/UserAvatar" description: |- * `created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `bad_request`: Returns an error when: * An image is not included in the request * The uploaded file is empty * The image size exceeds 1024 * 1024 pixels or 1MB * The file extension is other than `.jpg` or `.png`. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `forbidden`: Returns an error if the user does not have permissions necessary to upload an avatar or is not activated. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- * `not_found`: Returns an error if the user does not exist or cannot be found. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add or update user avatar tags: - User avatars x-box-tag: avatars "/users/{user_id}/email_aliases": get: description: |- Retrieves all email aliases for a user. The collection does not include the primary login for the user. operationId: get_users_id_email_aliases parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EmailAliases" description: Returns a collection of email aliases. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List user's email aliases tags: - Email aliases x-box-tag: email_aliases post: description: Adds a new email alias to a user account.. operationId: post_users_id_email_aliases parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string requestBody: content: application/json: schema: properties: email: description: |- The email address to add to the account as an alias. Note: The domain of the email alias needs to be registered to your enterprise. See the [domain verification guide]( https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification ) for steps to add a new domain. example: alias@example.com type: string required: - email type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/EmailAlias" description: Returns the newly created email alias object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create email alias tags: - Email aliases x-box-tag: email_aliases "/users/{user_id}/email_aliases/{email_alias_id}": delete: description: Removes an email alias from a user. operationId: delete_users_id_email_aliases_id parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string - description: The ID of the email alias. example: "23432" in: path name: email_alias_id required: true schema: type: string responses: "204": description: Removes the alias and returns an empty response. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove email alias tags: - Email aliases x-box-tag: email_aliases "/users/{user_id}/folders/0": put: description: |- Move all of the items (files, folders and workflows) owned by a user into another user's account Only the root folder (`0`) can be transferred. Folders can only be moved across users by users with administrative permissions. All existing shared links and folder-level collaborations are transferred during the operation. Please note that while collaborations at the individual file-level are transferred during the operation, the collaborations are deleted when the original user is deleted. This call will be performed synchronously which might lead to a slow response when the source user has a large number of items in all of its folders. If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously. There is currently no way to check for when this operation is finished. The destination folder's name will be in the format `{User}'s Files and Folders`, where `{User}` is the display name of the user. To make this API call your application will need to have the "Read and write all files and folders stored in Box" scope enabled. Please make sure the destination user has access to `Relay` or `Relay Lite`, and has access to the files and folders involved in the workflows being transferred. Admins will receive an email when the operation is completed. operationId: put_users_id_folders_0 parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array - description: |- Determines if users should receive email notification for the action performed. example: true in: query name: notify required: false schema: type: boolean requestBody: content: application/json: schema: properties: owned_by: description: The user who the folder will be transferred to properties: id: description: |- The ID of the user who the folder will be transferred to example: "1232234" type: string required: - id type: object required: - owned_by type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Folder--Full" description: |- Returns the information for the newly created destination folder. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when folder ownership cannot be transferred to another user. * `forbidden_by_policy`: Returned if ownership transfer is forbidden due to information barrier restrictions. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Transfer owned folders tags: - Transfer folders x-box-tag: transfer "/users/{user_id}/memberships": get: description: |- Retrieves all the groups for a user. Only members of this group or users with admin-level permissions will be able to use this API. operationId: get_users_id_memberships parameters: - description: The ID of the user. example: "12345" in: path name: user_id required: true schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - 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. example: 1000 in: query name: offset required: false schema: default: 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/GroupMemberships" description: |- Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List user's groups tags: - Group memberships x-box-tag: memberships /web_links: post: description: Creates a web link object within a folder. operationId: post_web_links requestBody: content: application/json: schema: properties: description: description: Description of the web link. example: Cloud Content Management type: string name: description: Name of the web link. Defaults to the URL if not set. example: Box Website type: string parent: description: The parent folder to create the web link within. properties: id: description: The ID of parent folder example: "0" type: string required: - id type: object shared_link: description: The settings for the shared link to update. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object url: description: |- The URL that this web link links to. Must start with `"http://"` or `"https://"`. example: https://box.com type: string required: - parent - url type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebLink" description: Returns the newly created web link object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create web link tags: - Web links x-box-tag: web_links "/web_links/{web_link_id}": delete: description: Deletes a web link. operationId: delete_web_links_id parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string responses: "204": description: |- An empty response will be returned when the web link was successfully deleted. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove web link tags: - Web links x-box-tag: web_links get: description: Retrieve information about a web link. operationId: get_web_links_id parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string - description: |- The URL, and optional password, for the shared link of this item. This header can be used to access items that have not been explicitly shared with a user. Use the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`. This header can be used on the file or folder shared, as well as on any files or folders nested within the item. example: shared_link=[link]&shared_link_password=[password] in: header name: boxapi required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebLink" description: Returns the web link object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get web link tags: - Web links x-box-tag: web_links post: description: |- Restores a web link that has been moved to the trash. An optional new parent ID can be provided to restore the web link to in case the original folder has been deleted. operationId: post_web_links_id parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array requestBody: content: application/json: schema: properties: name: description: An optional new name for the web link. example: Restored.docx type: string parent: allOf: - description: The parent for this item properties: id: description: The ID of parent item example: "123" type: string type: object - description: |- Specifies an optional ID of a folder to restore the web link to when the original folder no longer exists. Please be aware that this ID will only be used if the original folder no longer exists. Use this ID to provide a fallback location to restore the web link to if the original location has been deleted. type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/TrashWebLinkRestored" description: Returns a web link object when it has been restored. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the user does not have access to the folder the web link is being restored to, or the user does not have permission to restore web link from the trash. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the web link is not in the trash. "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if there is an web link with the same name in the folder the web link is being restored to. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Restore web link tags: - Trashed web links x-box-tag: trashed_web_links put: description: Updates a web link object. operationId: put_web_links_id parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string requestBody: content: application/json: schema: properties: description: description: A new description of the web link. example: Cloud Content Management type: string name: description: A new name for the web link. Defaults to the URL if not set. example: Box Website type: string parent: allOf: - description: The parent for this item properties: id: description: The ID of parent item example: "123" type: string type: object - description: |- The new parent folder to put the web link in. Use this to move the web link to a different folder. shared_link: description: The settings for the shared link to update. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object url: description: |- The new URL that the web link links to. Must start with `"http://"` or `"https://"`. example: https://box.com type: string type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebLink" description: Returns the updated web link object. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update web link tags: - Web links x-box-tag: web_links "/web_links/{web_link_id}#add_shared_link": put: description: Adds a shared link to a web link. operationId: put_web_links_id#add_shared_link parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: |- The settings for the shared link to create on the web link. Use an empty object (`{}`) to use the default settings for shared links. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the file (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean can_edit: description: This value can only be `true` is `type` is `file`. example: false type: boolean can_preview: description: |- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: false can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: web_link schema: $ref: "#/components/schemas/WebLink" description: |- Returns the base representation of a web link with a new shared link attached. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when there is an incorrect permission combination "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Add shared link to web link tags: - Shared links (Web Links) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_web_links "/web_links/{web_link_id}#get_shared_link": get: description: Gets the information for a shared link on a web link. operationId: get_web_links_id#get_shared_link parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: false can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: web_link schema: $ref: "#/components/schemas/WebLink" description: |- Returns the base representation of a web link with the additional shared link information. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get shared link for web link tags: - Shared links (Web Links) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_web_links "/web_links/{web_link_id}#remove_shared_link": put: description: Removes a shared link from a web link. operationId: put_web_links_id#remove_shared_link parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: |- By setting this value to `null`, the shared link is removed from the web link. example: null nullable: true type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: null type: web_link schema: $ref: "#/components/schemas/WebLink" description: |- Returns a basic representation of a web link, with the shared link removed. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove shared link from web link tags: - Shared links (Web Links) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_web_links "/web_links/{web_link_id}#update_shared_link": put: description: Updates a shared link on a web link. operationId: put_web_links_id#update_shared_link parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string - description: |- Explicitly request the `shared_link` fields to be returned for this item. example: shared_link in: query name: fields required: true schema: type: string requestBody: content: application/json: schema: properties: shared_link: description: The settings for the shared link to update. properties: access: description: |- The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. enum: - open - company - collaborators example: open type: string password: description: |- The password required to access the shared link. Set the password to `null` to remove it. A password can only be set when `access` is set to `open`. example: do-not-use-this-password type: string permissions: properties: can_download: description: |- If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. example: true type: boolean can_edit: description: This value can only be `true` is `type` is `file`. example: true type: boolean can_preview: description: |- If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. example: true type: boolean type: object unshared_at: description: |- The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. example: 2012-12-12T10:53:43-08:00 format: date-time type: string vanity_name: description: |- Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. example: my-shared-link minLength: 12 type: string type: object type: object responses: "200": content: application/json: examples: default: value: etag: "1" id: "12345" shared_link: access: open download_count: 0 download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf effective_access: open effective_permission: can_download is_password_enabled: false permissions: can_download: true can_edit: false can_preview: true preview_count: 0 unshared_at: 2020-09-21T10:34:41-07:00 url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1 vanity_name: null vanity_url: null type: web_link schema: $ref: "#/components/schemas/WebLink" description: |- Returns a basic representation of the web link, with the updated shared link attached. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned when there is an incorrect permission combination "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the user does not have all the permissions to complete the update. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the file is not found, or the user does not have access to the file. "405": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the `file_id` is not in a recognized format. "412": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update shared link on web link tags: - Shared links (Web Links) x-box-enable-explorer: true x-box-sanitized: true x-box-tag: shared_links_web_links "/web_links/{web_link_id}/trash": delete: description: |- Permanently deletes a web link that is in the trash. This action cannot be undone. operationId: delete_web_links_id_trash parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string responses: "204": description: |- Returns an empty response when the web link was permanently deleted. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the web link is not in the trash. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Permanently remove web link tags: - Trashed web links x-box-tag: trashed_web_links get: description: Retrieves a web link that has been moved to the trash. operationId: get_web_links_id_trash parameters: - description: The ID of the web link. example: "12345" in: path name: web_link_id required: true schema: type: string - 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. example: - id - type - name explode: false in: query name: fields required: false schema: items: type: string type: array responses: "200": content: application/json: schema: $ref: "#/components/schemas/TrashWebLink" description: |- Returns the web link that was trashed, including information about when the it was moved to the trash. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the web link is not in the trash. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get trashed web link tags: - Trashed web links x-box-tag: trashed_web_links /webhooks: get: description: |- Returns all defined webhooks for the requesting application. This API only returns webhooks that are applied to files or folders that are owned by the authenticated user. This means that an admin can not see webhooks created by a service account unless the admin has access to those folders, and vice versa. operationId: get_webhooks parameters: - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/Webhooks" description: Returns a list of webhooks. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the application does not have the permission to manage webhooks. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List all webhooks tags: - Webhooks x-box-tag: webhooks post: description: Creates a webhook. operationId: post_webhooks requestBody: content: application/json: schema: properties: address: description: The URL that is notified by this webhook example: https://example.com/webhooks type: string target: description: The item that will trigger the webhook properties: id: description: The ID of the item to trigger a webhook example: "1231232" type: string type: description: The type of item to trigger a webhook enum: - file - folder example: file type: string type: object triggers: description: |- An array of event names that this webhook is to be triggered for example: - FILE.UPLOADED items: description: The event name that triggered this webhook enum: - FILE.UPLOADED - FILE.PREVIEWED - FILE.DOWNLOADED - FILE.TRASHED - FILE.DELETED - FILE.RESTORED - FILE.COPIED - FILE.MOVED - FILE.LOCKED - FILE.UNLOCKED - FILE.RENAMED - COMMENT.CREATED - COMMENT.UPDATED - COMMENT.DELETED - TASK_ASSIGNMENT.CREATED - TASK_ASSIGNMENT.UPDATED - METADATA_INSTANCE.CREATED - METADATA_INSTANCE.UPDATED - METADATA_INSTANCE.DELETED - FOLDER.CREATED - FOLDER.RENAMED - FOLDER.DOWNLOADED - FOLDER.RESTORED - FOLDER.DELETED - FOLDER.COPIED - FOLDER.MOVED - FOLDER.TRASHED - WEBHOOK.DELETED - COLLABORATION.CREATED - COLLABORATION.ACCEPTED - COLLABORATION.REJECTED - COLLABORATION.REMOVED - COLLABORATION.UPDATED - SHARED_LINK.DELETED - SHARED_LINK.CREATED - SHARED_LINK.UPDATED - SIGN_REQUEST.COMPLETED - SIGN_REQUEST.DECLINED - SIGN_REQUEST.EXPIRED example: FILE.UPLOADED title: Webhook Trigger type: string type: array required: - target - triggers - address type: object responses: "201": content: application/json: schema: $ref: "#/components/schemas/Webhook" description: Returns the new webhook object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the parameters were incorrect. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the application does not have the permission to manage webhooks. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the target item could not be found "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the a webhook for this combination of target, application, and user already exists. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create webhook tags: - Webhooks x-box-tag: webhooks "/webhooks/{webhook_id}": delete: description: Deletes a webhook. operationId: delete_webhooks_id parameters: - description: The ID of the webhook. example: "3321123" in: path name: webhook_id required: true schema: type: string responses: "204": description: |- An empty response will be returned when the webhook was successfully deleted. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the application does not have the permission to manage webhooks. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the webhook could not be found default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Remove webhook tags: - Webhooks x-box-tag: webhooks get: description: Retrieves a specific webhook operationId: get_webhooks_id parameters: - description: The ID of the webhook. example: "3321123" in: path name: webhook_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Webhook" description: Returns a webhook object "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the application does not have the permission to manage webhooks. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returns an error if the webhook could not be found default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get webhook tags: - Webhooks x-box-tag: webhooks put: description: Updates a webhook. operationId: put_webhooks_id parameters: - description: The ID of the webhook. example: "3321123" in: path name: webhook_id required: true schema: type: string requestBody: content: application/json: schema: properties: address: description: The URL that is notified by this webhook example: https://example.com/webhooks type: string target: description: The item that will trigger the webhook properties: id: description: The ID of the item to trigger a webhook example: "1231232" type: string type: description: The type of item to trigger a webhook enum: - file - folder example: file type: string type: object triggers: description: |- An array of event names that this webhook is to be triggered for example: - FILE.UPLOADED items: description: The event name that triggered this webhook enum: - FILE.UPLOADED - FILE.PREVIEWED - FILE.DOWNLOADED - FILE.TRASHED - FILE.DELETED - FILE.RESTORED - FILE.COPIED - FILE.MOVED - FILE.LOCKED - FILE.UNLOCKED - FILE.RENAMED - COMMENT.CREATED - COMMENT.UPDATED - COMMENT.DELETED - TASK_ASSIGNMENT.CREATED - TASK_ASSIGNMENT.UPDATED - METADATA_INSTANCE.CREATED - METADATA_INSTANCE.UPDATED - METADATA_INSTANCE.DELETED - FOLDER.CREATED - FOLDER.RENAMED - FOLDER.DOWNLOADED - FOLDER.RESTORED - FOLDER.DELETED - FOLDER.COPIED - FOLDER.MOVED - FOLDER.TRASHED - WEBHOOK.DELETED - COLLABORATION.CREATED - COLLABORATION.ACCEPTED - COLLABORATION.REJECTED - COLLABORATION.REMOVED - COLLABORATION.UPDATED - SHARED_LINK.DELETED - SHARED_LINK.CREATED - SHARED_LINK.UPDATED - SIGN_REQUEST.COMPLETED - SIGN_REQUEST.DECLINED - SIGN_REQUEST.EXPIRED example: FILE.UPLOADED title: Webhook Trigger type: string type: array type: object responses: "200": content: application/json: schema: $ref: "#/components/schemas/Webhook" description: Returns the new webhook object. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the parameters were incorrect. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the application does not have the permission to manage webhooks. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the target item or webhook could not be found "409": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the a webhook for this combination of target, application, and user already exists. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Update webhook tags: - Webhooks x-box-tag: webhooks /workflows: get: description: |- Returns list of workflows that act on a given `folder ID`, and have a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in to use this endpoint. operationId: get_workflows parameters: - description: |- The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. example: "12345" in: query name: folder_id required: true schema: nullable: false type: string - description: Type of trigger to search for. example: WORKFLOW_MANUAL_START in: query name: trigger_type required: false schema: nullable: false type: string - description: The maximum number of items to return per page. example: 1000 in: query name: limit required: false schema: format: int64 maximum: 1000 type: integer - description: |- Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii in: query name: marker required: false schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Workflows" description: Returns the workflow. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: Returned if the trigger type is not `WORKFLOW_MANUAL_START`. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned if the folder is not found, or the user does not have access to the folder. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: List workflows tags: - Workflows x-box-tag: workflows "/workflows/{workflow_id}/start": post: description: |- Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`. You application must be authorized to use the `Manage Box Relay` application scope within the developer console. operationId: post_workflows_id_start parameters: - description: The ID of the workflow. example: "12345" in: path name: workflow_id required: true schema: type: string requestBody: content: application/json: schema: properties: files: description: |- The array of files for which the workflow should start. All files must be in the workflow's configured folder. items: description: A file the workflow should start for properties: id: description: The id of the file example: "12345678" type: string type: description: The type of the file object enum: - file example: file type: string type: object type: array flow: description: The flow that will be triggered properties: id: description: The id of the flow example: "123456789" type: string type: description: The type of the flow object example: flow type: string type: object folder: description: The folder object for which the workflow is configured. properties: id: description: The id of the folder example: "87654321" type: string type: description: The type of the folder object enum: - folder example: folder type: string type: object outcomes: description: A list of outcomes required to be configured at start time. items: description: |- A configurable outcome the workflow should complete. If you have a `task_completion_rule`, you may input `all_assignees` or `any_assignee` in the `variable_value` field. Similarly, if you have a `collaborator_role`, you may input `editor`, `viewer`, `previewer`, `uploader`, `previewer uploader`, `viewer uploader` , `co-owner` in the `variable_value` field. properties: id: description: The id of the outcome example: "890375782" type: string parameter: description: |- This is a placeholder example for various objects that can be passed in - refer to the guides section to find out more information. example: placeholder type: string type: description: The type of the outcome object enum: - outcome example: outcome type: string type: object type: array type: description: The type of the parameters object enum: - workflow_parameters example: workflow_parameters type: string required: - flow - files - folder type: object responses: "204": description: Starts the workflow. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. * `workflow_is_not_enabled` when the workflow is not enabled * `workflow_not_active_on_provided_folder` when the workflow is not enabled for the specified folder id * `parameters_provided_do_not_match_target_outcome` when the provided parameters do not match the expected parameters "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if there are insufficient permissions. * `insufficient_access` when the user does not have access rights to file or folder * `missing_relay_full_access` when the user does not have access to Relay Full "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the workflow could not be found, or the authenticated user does not have access to the workflow. * `workflow_not_found` when the workflow is not found * `flow_missing_or_inaccessible` when the flow is not a manual start flow default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Starts workflow based on request body tags: - Workflows x-box-tag: workflows /zip_downloads: post: description: |- Creates a request to download multiple files and folders as a single `zip` archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a `download_url` and a `status_url` that can be used to download the archive. The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first operationId: post_zip_downloads requestBody: content: application/json: schema: $ref: "#/components/schemas/ZipDownloadRequest" responses: "202": content: application/json: examples: default: value: download_url: https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content expires_at: 2020-07-22T11:26:08Z name_conflicts: - - download_name: 3aa6a7.pdf id: "12345" original_name: Report.pdf type: file - download_name: 5d53f2.pdf id: "34325" original_name: Report.pdf type: file status_url: https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status schema: $ref: "#/components/schemas/ZipDownload" description: |- If the `zip` archive is ready to be downloaded, the API will return a response that will include a `download_url`, a `status_url`, as well as any conflicts that might have occurred when creating the request. "400": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if some of the parameters are missing or not valid. In most cases, this error might happen because the JSON request body is not valid JSON, any of the items has an incorrect or missing ID, any of the items is not a file or folder, or the root folder with ID `0` has been added to the list of folders to add to the archive. The following is a list of common error codes for this response. * `bad_request` - the request body is missing, invalid, or both the list of files and folders are empty. Additionally, it this error might be returned when attempting to add the root folder with ID `0` to an archive. * `zip_download_file_count_exceeded_limit` - the requested files and folders would result in an archive with more than 10,000 files. The request will have to be split into multiple requests to reduce the number of files per archive. * `zip_download_pre_compressed_bytes_exceeded_limit` - the requested files and folders would result in an archive with more than the allowed download limit. The request will have to be split into multiple requests to reduce the size of the archive. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when an authorization header is provided but the user does not have access to the items. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Create zip download tags: - Zip Downloads x-box-reference-category: zip_downloads x-box-tag: zip_downloads "/zip_downloads/{zip_download_id}/content": get: description: |- Returns the contents of a `zip` archive in binary format. This URL does not require any form of authentication and could be used in a user's browser to download the archive to a user's device. By default, this URL is only valid for a few seconds from the creation of the request for this archive. Once a download has started it can not be stopped and resumed, instead a new request for a zip archive would need to be created. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `download_url` field in the response to this endpoint. operationId: get_zip_downloads_id_content parameters: - description: The unique identifier that represent this `zip` archive. example: Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd in: path name: zip_download_id required: true schema: type: string responses: "200": content: application/octet-stream: schema: description: |- The binary content of the archive, which will include the items requested for this download. format: binary type: string description: |- Returns the content of the items requested for this download, formatted as a stream of files and folders in a `zip` archive. headers: Content-Disposition: description: The name of the archive to be downloaded schema: example: attachment;filename="Avatars.zip";filename*=UTF-8''Avatars.zip type: string "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the ID of this download request is not valid. This error can also be returned if this URL has been called before. To re-download this archive, please create a new request for a zip download. "429": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the number of concurrent zip downloads has been reached for either the user or the enterprise. * `user_too_many_concurrent_downloads` - the maximum of 5 parallel downloads of zip archives per user has been met. * `enterprise_too_many_concurrent_downloads` - the maximum of 10 parallel downloads of zip archives per enterprise has been met. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. security: [] servers: - description: |- An opaque server URL for downloading zip downloads. The format of this URL might change over time. url: https://dl.boxcloud.com/2.0 summary: Download zip archive tags: - Zip Downloads x-box-reference-category: zip_downloads x-box-tag: zip_downloads "/zip_downloads/{zip_download_id}/status": get: description: |- Returns the download status of a `zip` archive, allowing an application to inspect the progress of the download as well as the number of items that might have been skipped. This endpoint can only be accessed once the download has started. Subsequently this endpoint is valid for 12 hours from the start of the download. The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](e://post_zip_downloads) API to request to create a `zip` archive, and then follow the `status_url` field in the response to this endpoint. operationId: get_zip_downloads_id_status parameters: - description: The unique identifier that represent this `zip` archive. example: Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd in: path name: zip_download_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ZipDownloadStatus" description: Returns the status of the `zip` archive that is being downloaded. "401": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when the access token provided in the `Authorization` header is not recognized or not provided. "403": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returned when an authorization header is provided but the user does not have access to the items. "404": content: application/json: schema: $ref: "#/components/schemas/ClientError" description: |- Returns an error if the ID of this download request is not valid, or if the status of a download is requested before the download has been started. default: content: application/json: schema: $ref: "#/components/schemas/ClientError" description: An unexpected client error. summary: Get zip download status tags: - Zip Downloads x-box-reference-category: zip_downloads x-box-tag: zip_downloads components: schemas: AccessToken: description: A token that can be used to make authenticated API calls. properties: access_token: description: The requested access token. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string expires_in: description: The time in seconds in seconds by which this token will expire. example: 3600 format: int64 type: integer issued_token_type: description: |- The type of downscoped access token returned. This is only returned if an access token has been downscoped. enum: - urn:ietf:params:oauth:token-type:access_token example: urn:ietf:params:oauth:token-type:access_token format: urn type: string refresh_token: description: |- The refresh token for this access token, which can be used to request a new access token when the current one expires. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string restricted_to: 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/FileScope" type: array token_type: description: The type of access token returned. enum: - bearer example: bearer type: string title: Access token type: object x-box-resource-id: access_token x-box-tag: authorization Classification: description: |- An instance of the classification metadata template, containing the classification applied to the file or folder. To get more details about the classification applied to an item, request the classification metadata template. properties: $canEdit: description: Whether an end user can change the classification. example: true type: boolean $parent: 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}`. example: folder_59449484661, type: string $scope: description: |- The scope of the enterprise that this classification has been applied for. This will be in the format `enterprise_{enterprise_id}`. example: enterprise_27335 type: string $template: description: "`securityClassification-6VMVochwUWo`" enum: - securityClassification-6VMVochwUWo example: securityClassification-6VMVochwUWo type: string $type: description: |- The unique ID of this classification instance. This will be include the name of the classification template and a unique ID. example: securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8 type: string $typeVersion: description: |- The version of the metadata template. This version starts at 0 and increases every time the template is updated. This is mostly for internal use. example: 5 type: number $version: description: |- The version of the metadata instance. This version starts at 0 and increases every time a classification is updated. example: 1 type: integer Box__Security__Classification__Key: description: The name of the classification applied to the item. example: Sensitive type: string title: Classification type: object x-box-resource-id: classification x-box-tag: classifications ClassificationTemplate: description: |- A metadata template that holds the security classifications defined by an enterprise. properties: copyInstanceOnItemCopy: description: |- Classifications are always copied along when the file or folder is copied. example: true type: boolean displayName: description: The name of this template as shown in web and mobile interfaces. enum: - Classification example: Classification type: string fields: description: |- A list of fields for this classification template. This includes only one field, the `Box__Security__Classification__Key`, which defines the different classifications available in this enterprise. items: description: |- The metadata template field that represents the available classifications. properties: displayName: description: "`Classification`" enum: - Classification example: Classification type: string hidden: description: Classifications are always visible to web and mobile users. example: false type: boolean id: description: The unique ID of the field. example: 822227e0-47a5-921b-88a8-494760b2e6d2 type: string key: description: "`Box__Security__Classification__Key`" enum: - Box__Security__Classification__Key example: Box__Security__Classification__Key type: string options: description: A list of classifications available in this enterprise. items: description: A single classification available in this enterprise. properties: id: description: The unique ID of this classification. example: 46aea176-3483-4431-856c-6b5b13d1cc50 type: string key: description: The display name and key for this classification. example: Sensitive type: string staticConfig: description: Additional information about the classification. properties: classification: description: |- Additional information about the classification. This is not an exclusive list of properties, and more object fields might be returned. These fields are used for internal Box Shield and Box Governance purposes and no additional value must be derived from these fields. properties: classificationDefinition: description: A longer description of the classification. example: Sensitive information type: string colorID: description: |- An internal Box identifier used to assign a color to a classification label. Mapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows. * `0`: Yellow * `1`: Orange * `2`: Watermelon red * `3`: Purple rain * `4`: Light blue * `5`: Dark blue * `6`: Light green * `7`: Gray example: 4 type: number type: object type: object type: object minItems: 1 type: array type: description: "`enum`" enum: - enum example: enum type: string type: object maxItems: 1 minItems: 1 type: array hidden: description: This template is always available in web and mobile interfaces. example: false type: boolean id: description: The ID of the classification template. example: 58063d82-4128-7b43-bba9-92f706befcdf type: string scope: description: |- The scope of the classification template. This is in the format `enterprise_{id}` where the `id` is the enterprise ID. example: enterprise_123456 type: string templateKey: description: "`securityClassification-6VMVochwUWo`" enum: - securityClassification-6VMVochwUWo example: securityClassification-6VMVochwUWo type: string type: description: "`metadata_template`" enum: - metadata_template example: metadata_template nullable: false type: string required: - type title: Classification Template type: object x-box-resource-id: classification_template x-box-tag: classifications ClientError: description: A generic error properties: code: description: A Box-specific error code 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 example: item_name_invalid type: string 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. properties: message: description: More details on the error. example: Something went wrong. type: string type: object 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/ nullable: false type: string message: description: A short message describing the error. example: Method Not Allowed nullable: false type: string request_id: description: |- A unique identifier for this response, which can be used when contacting Box support. example: abcdef123456 nullable: false type: string status: description: The HTTP status of the response. example: 400 format: int32 nullable: false type: integer type: description: "`error`" enum: - error example: error nullable: false type: string title: Client error type: object x-box-resource-id: client_error Collaboration: description: |- Collaborations define access permissions for users and groups to files and folders, similar to access control lists. A collaboration object grants a user or group access to a file or folder with permissions defined by a specific role. properties: acceptance_requirements_status: properties: strong_password_requirement: properties: enterprise_has_strong_password_required_for_external_users: description: |- Whether or not the enterprise that owns the content requires a strong password to collaborate on the content. example: true type: boolean user_has_strong_password: description: |- Whether or not the user has a strong password set for their account. The field is `null` when a strong password is not required. example: true nullable: true type: boolean type: object terms_of_service_requirement: properties: is_accepted: description: |- Whether or not the terms of service have been accepted. The field is `null` when there is no terms of service required. example: true nullable: true type: boolean terms_of_service: allOf: - $ref: "#/components/schemas/TermsOfService--Base" - description: |- The terms of service that must be accepted before the collaboration can be accepted. The field is `null` when there is no terms of service required. type: object two_factor_authentication_requirement: properties: enterprise_has_two_factor_auth_enabled: description: |- Whether or not the enterprise that owns the content requires two-factor authentication to be enabled in order to collaborate on the content. example: true type: boolean user_has_two_factor_authentication_enabled: description: |- Whether or not the user has two-factor authentication enabled. The field is `null` when two-factor authentication is not required. example: true nullable: true type: boolean type: object type: object accessible_by: allOf: - $ref: "#/components/schemas/User--Collaborations" - description: The user or group that is granted access. acknowledged_at: description: |- When the `status` of the collaboration object changed to `accepted` or `rejected`. example: 2012-12-12T10:55:20-08:00 format: date-time type: string created_at: description: When the collaboration object was created. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Collaborations" - description: The user who created the collaboration object. - example: - id: 33224412 - type: user - login: dylan@example.com - name: Dylan Smith expires_at: description: |- When the collaboration will expire, or `null` if no expiration date is set. example: 2012-12-26T10:53:43-08:00 format: date-time nullable: true type: string id: description: The unique identifier for this collaboration. example: "12345678" type: string invite_email: description: |- The email address used to invite an unregistered collaborator, if they are not a registered user. example: john@example.com nullable: true type: string item: allOf: - oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - $ref: "#/components/schemas/WebLink" - description: |- The file or folder to which access is granted. The field is `null` when the collaboration `status` is `pending`. nullable: true modified_at: description: When the collaboration object was last modified. example: 2012-12-12T10:53:43-08:00 format: date-time type: string role: description: The level of access granted. enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner - owner example: editor type: string status: description: |- The status of the collaboration invitation. If the status is `pending`, `login` and `name` return an empty string. enum: - accepted - pending - rejected example: accepted type: string type: description: "`collaboration`" enum: - collaboration example: collaboration type: string title: Collaboration type: object x-box-resource-id: collaboration x-box-tag: user_collaborations CollaborationAllowlistEntries: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/CollaborationAllowlistEntry" type: array description: A list of allowed domains for collaboration. title: Allowed collaboration domains type: object x-box-resource-id: collaboration_allowlist_entries x-box-tag: collaboration_allowlist_entries CollaborationAllowlistEntry: description: |- An entry that describes an approved domain for which users can collaborate with files and folders in your enterprise or vice versa. properties: created_at: description: The time the entry was created at example: 2012-12-12T10:53:43-08:00 format: date-time type: string direction: description: The direction of the collaborations to allow. enum: - inbound - outbound - both example: both type: string domain: description: The whitelisted domain example: example.com type: string enterprise: allOf: - description: A representation of a Box enterprise properties: id: description: The unique identifier for this enterprise. example: "11446498" type: string name: description: The name of the enterprise example: Acme Inc. type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string title: Enterprise type: object - description: The enterprise this list is applied to id: description: The unique identifier for this entry example: "11446498" type: string type: description: "`collaboration_whitelist_entry`" enum: - collaboration_whitelist_entry example: collaboration_whitelist_entry type: string title: Allowed collaboration domain type: object x-box-resource-id: collaboration_allowlist_entry x-box-tag: collaboration_allowlist_entries CollaborationAllowlistExemptTarget: description: |- The user that is exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise. properties: created_at: description: The time the entry was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string enterprise: allOf: - description: A representation of a Box enterprise properties: id: description: The unique identifier for this enterprise. example: "11446498" type: string name: description: The name of the enterprise example: Acme Inc. type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string title: Enterprise type: object - description: The enterprise this entry belongs to id: description: The unique identifier for this exemption example: "11446498" type: string modified_at: description: The time the entry was modified example: 2012-12-12T10:53:43-08:00 format: date-time type: string type: description: "`collaboration_whitelist`" enum: - collaboration_whitelist example: collaboration_whitelist type: string user: allOf: - description: A representation of a Box enterprise properties: id: description: The unique identifier for this enterprise. example: "11446498" type: string name: description: The name of the enterprise example: Acme Inc. type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string title: Enterprise type: object - description: The user that has been exempt title: Allowed collaboration domains user exemption type: object x-box-resource-id: collaboration_allowlist_exempt_target x-box-tag: collaboration_allowlist_exempt_targets CollaborationAllowlistExemptTargets: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/CollaborationAllowlistExemptTarget" type: array description: |- A list of users that is exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise. title: Allowed collaboration domains user exemptions type: object x-box-resource-id: collaboration_allowlist_exempt_targets x-box-tag: collaboration_allowlist_exempt_targets Collaborations: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/Collaboration" type: array description: A list of collaborations title: Collaborations type: object x-box-resource-id: collaborations x-box-tag: user_collaborations Collection: description: |- A collection of items, including files and folders. Currently, the only collection available is the `favorites` collection. The contents of a collection can be explored in a similar way to which the contents of a folder is explored. properties: collection_type: description: |- The type of the collection. This is used to determine the proper visual treatment for collections. enum: - favorites example: favorites type: string id: description: The unique identifier for this collection. example: "11446498" type: string name: description: The name of the collection. enum: - Favorites example: Favorites type: string type: description: "`collection`" enum: - collection example: collection type: string title: Collection type: object x-box-resource-id: collection x-box-tag: collections Collections: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/Collection" type: array description: A list of collections title: Collections type: object x-box-resource-id: collections x-box-tag: collections Comment: allOf: - $ref: "#/components/schemas/Comment--Base" - properties: created_at: description: The time this comment was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: |- A mini user object representing the author of the comment is_reply_comment: description: |- Whether or not this comment is a reply to another comment example: true type: boolean item: allOf: - description: The bare basic reference for an object properties: id: description: The unique identifier for this object example: "11446498" type: string type: description: The type for this object example: file type: string title: Reference type: object - description: The file this comment was placed on message: description: The text of the comment, as provided by the user example: "@Aaron Levie these tigers are cool!" type: string modified_at: description: The time this comment was last modified example: 2012-12-12T10:53:43-08:00 format: date-time type: string description: Standard representation of a comment. title: Comment type: object x-box-resource-id: comment x-box-variant: standard Comment--Base: description: Base representation of a comment. properties: id: description: The unique identifier for this comment. example: "11446498" type: string type: description: "`comment`" enum: - comment example: comment type: string title: Comment (Base) type: object x-box-resource-id: comment--base x-box-sanitized: true x-box-tag: comments x-box-variant: base x-box-variants: - base - standard - full Comment--Full: allOf: - $ref: "#/components/schemas/Comment" - properties: tagged_message: description: |- The string representing the comment text with @mentions included. @mention format is @[id:username] where `id` is user's Box ID and `username` is their display name. example: "@[1234567:Aaron Levie] these tigers are cool!" type: string description: |- Comments are messages created on files. Comments can be made independently or created as responses to other comments title: Comment (Full) type: object x-box-resource-id: comment--full x-box-variant: full Comments: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/Comment" type: array description: A list of comments title: Comments type: object x-box-resource-id: comments x-box-tag: comments ConflictError: allOf: - $ref: "#/components/schemas/ClientError" - properties: context_info: properties: conflicts: description: A list of the file conflicts that caused this error. items: $ref: "#/components/schemas/FileConflict" type: array type: object description: |- The error that occurs when a file can not be created due to a conflict. title: Conflict error type: object x-box-resource-id: conflict_error x-box-tag: uploads DevicePinner: description: |- Device pins allow enterprises to control what devices can use native Box applications. properties: id: description: The unique identifier for this device pin. example: "11446498" type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user that the device pin belongs to product_name: description: The type of device being pinned example: iPad type: string type: description: "`device_pinner`" enum: - device_pinner example: device_pinner type: string title: Device pinner type: object x-box-resource-id: device_pinner x-box-tag: device_pinners DevicePinners: description: A list of device pins properties: entries: items: $ref: "#/components/schemas/DevicePinner" type: array limit: default: 100 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. example: 200 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer order: description: The order by which items are returned. items: description: The order in which a pagination is ordered properties: by: description: The field that is ordered by enum: - id example: id type: string direction: description: The direction to order by, either ascending or descending enum: - asc - desc example: asc type: string type: object type: array title: Device pinners type: object x-box-resource-id: device_pinners x-box-tag: device_pinners EmailAlias: description: An email alias for a user. properties: email: description: The email address example: alias@example.com type: string id: description: The unique identifier for this object example: "11446498" type: string is_confirmed: description: Whether the email address has been confirmed example: true type: boolean type: description: "`email_alias`" enum: - email_alias example: email_alias type: string title: Email alias type: object x-box-resource-id: email_alias x-box-tag: email_aliases EmailAliases: description: A list of email aliases properties: entries: items: $ref: "#/components/schemas/EmailAlias" type: array total_count: description: The number of email aliases. example: 5000 format: int64 type: integer title: Email aliases type: object x-box-resource-id: email_aliases x-box-tag: email_aliases Enterprise--Base: description: |- A mini representation of a enterprise, used when nested within another resource. properties: id: description: The unique identifier for this enterprise example: "1910967" type: string type: description: "`enterprise`" enum: - enterprise example: enterprise nullable: false type: string title: Enterprise (Base) type: object x-box-resource-id: enterprise--base x-box-variant: base x-box-variants: - base - mini - standard - full Event: description: The description of an event that happened within Box properties: additional_details: description: |- This object provides additional information about the event if available. This can include how a user performed an event as well as additional information to correlate an event to external KeySafe logs. Not all events have an `additional_details` object. This object is only available in the Enterprise Events. example: key: value type: object created_at: description: When the event object was created example: 2022-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: |- The user that performed the action represented by the event. Some events may be performed by users not logged into Box. In that case, not all attributes of the object are populated and the event is attributed to a unknown user (`user_id = 2`) event_id: description: The ID of the event object. You can use this to detect duplicate events example: f82c3ba03e41f7e8a7608363cc6c0390183c3f83 type: string event_type: allOf: - description: An event type that can trigger an event enum: - ACCESS_GRANTED - ACCESS_REVOKED - ADD_DEVICE_ASSOCIATION - ADD_LOGIN_ACTIVITY_DEVICE - ADMIN_LOGIN - APPLICATION_CREATED - APPLICATION_PUBLIC_KEY_ADDED - APPLICATION_PUBLIC_KEY_DELETED - CHANGE_ADMIN_ROLE - CHANGE_FOLDER_PERMISSION - COLLABORATION_ACCEPT - COLLABORATION_EXPIRATION - COLLABORATION_INVITE - COLLABORATION_REMOVE - COLLABORATION_ROLE_CHANGE - COLLAB_ADD_COLLABORATOR - COLLAB_INVITE_COLLABORATOR - COLLAB_REMOVE_COLLABORATOR - COLLAB_ROLE_CHANGE - COMMENT_CREATE - COMMENT_DELETE - CONTENT_ACCESS - CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY - CONTENT_WORKFLOW_AUTOMATION_ADD - CONTENT_WORKFLOW_AUTOMATION_DELETE - CONTENT_WORKFLOW_POLICY_ADD - CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION - CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION - COPY - DATA_RETENTION_CREATE_RETENTION - DATA_RETENTION_REMOVE_RETENTION - DELETE - DELETE_USER - DEVICE_TRUST_CHECK_FAILED - DOWNLOAD - EDIT - EDIT_USER - EMAIL_ALIAS_CONFIRM - EMAIL_ALIAS_REMOVE - ENABLE_TWO_FACTOR_AUTH - ENTERPRISE_APP_AUTHORIZATION_UPDATE - FAILED_LOGIN - FILE_MARKED_MALICIOUS - FILE_WATERMARKED_DOWNLOAD - GROUP_ADD_ITEM - GROUP_ADD_USER - GROUP_CREATION - GROUP_DELETION - GROUP_EDITED - GROUP_REMOVE_ITEM - GROUP_REMOVE_USER - ITEM_COPY - ITEM_CREATE - ITEM_DOWNLOAD - ITEM_MAKE_CURRENT_VERSION - ITEM_MODIFY - ITEM_MOVE - ITEM_OPEN - ITEM_PREVIEW - ITEM_RENAME - ITEM_SHARED - ITEM_SHARED_CREATE - ITEM_SHARED_UNSHARE - ITEM_SHARED_UPDATE - ITEM_SYNC - ITEM_TRASH - ITEM_UNDELETE_VIA_TRASH - ITEM_UNSYNC - ITEM_UPLOAD - LEGAL_HOLD_ASSIGNMENT_CREATE - LEGAL_HOLD_ASSIGNMENT_DELETE - LEGAL_HOLD_POLICY_CREATE - LEGAL_HOLD_POLICY_DELETE - LEGAL_HOLD_POLICY_UPDATE - LOCK - LOCK_CREATE - LOCK_DESTROY - LOGIN - MASTER_INVITE_ACCEPT - MASTER_INVITE_REJECT - METADATA_INSTANCE_CREATE - METADATA_INSTANCE_DELETE - METADATA_INSTANCE_UPDATE - METADATA_TEMPLATE_CREATE - METADATA_TEMPLATE_DELETE - METADATA_TEMPLATE_UPDATE - MOVE - NEW_USER - PREVIEW - REMOVE_DEVICE_ASSOCIATION - REMOVE_LOGIN_ACTIVITY_DEVICE - RENAME - RETENTION_POLICY_ASSIGNMENT_ADD - SHARE - SHARE_EXPIRATION - SHIELD_ALERT - SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED - SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION - SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED - SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION - SHIELD_JUSTIFICATION_APPROVAL - SIGN_DOCUMENT_ASSIGNED - SIGN_DOCUMENT_CANCELLED - SIGN_DOCUMENT_COMPLETED - SIGN_DOCUMENT_CONVERTED - SIGN_DOCUMENT_CREATED - SIGN_DOCUMENT_DECLINED - SIGN_DOCUMENT_EXPIRED - SIGN_DOCUMENT_SIGNED - SIGN_DOCUMENT_VIEWED_BY_SIGNED - SIGNER_DOWNLOADED - SIGNER_FORWARDED - STORAGE_EXPIRATION - TAG_ITEM_CREATE - TASK_ASSIGNMENT_CREATE - TASK_ASSIGNMENT_DELETE - TASK_ASSIGNMENT_UPDATE - TASK_CREATE - TASK_UPDATE - TERMS_OF_SERVICE_ACCEPT - TERMS_OF_SERVICE_REJECT - UNDELETE - UNLOCK - UNSHARE - UPDATE_COLLABORATION_EXPIRATION - UPDATE_SHARE_EXPIRATION - UPLOAD - USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE - WATERMARK_LABEL_CREATE - WATERMARK_LABEL_DELETE example: FILE_MARKED_MALICIOUS title: Event Type type: string - description: The event type that triggered this event recorded_at: description: When the event object was recorded in database example: 2022-12-12T10:54:43-08:00 format: date-time type: string session_id: description: |- The session of the user that performed the action. Not all events will populate this attribute. example: 70090280850c8d2a1933c1 type: string source: allOf: - oneOf: - $ref: "#/components/schemas/User" - $ref: "#/components/schemas/EventSource" - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - description: |- The resource that triggered this event. For more information, check out the guide on event triggers. type: description: "`event`" example: event type: string title: Event type: object x-box-resource-id: event x-box-tag: events EventSource: description: |- The source file or folder that triggered an event in the event stream. properties: classification: description: |- The object containing classification information for the item that triggered the event. This field will not appear if the item does not have a classification set. properties: name: description: The classification's name example: Top Secret type: string type: object item_id: description: | The unique identifier that represents the item. example: "560284318361" nullable: false type: string item_name: description: | The name of the item. example: report.pdf nullable: false type: string item_type: description: | The type of the item that the event represents. Can be `file` or `folder`. enum: - file - folder example: file nullable: false type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this item. - 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 required: - item_type - item_id - item_name title: Event source type: object x-box-resource-id: event_source Events: description: A list of event objects properties: chunk_size: description: The number of events returned in this response. example: 2 format: int64 type: integer entries: items: $ref: "#/components/schemas/Event" type: array next_stream_position: description: |- The stream position of the start of the next page (chunk) of events. example: "1152922976252290886" type: string title: Events type: object x-box-resource-id: events x-box-tag: events File: allOf: - $ref: "#/components/schemas/File--Mini" - properties: content_created_at: 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 format: date-time nullable: true type: string content_modified_at: 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 format: date-time nullable: true type: string created_at: description: The date and time when the file was created on Box. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: false type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this file description: description: The optional description of this file example: Contract for Q1 renewal maxLength: 256 nullable: false type: string item_status: 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 example: active nullable: false type: string modified_at: description: The date and time when the file was last updated on Box. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: false type: string 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 parent: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: The folder that this file is located within. nullable: true path_collection: allOf: - description: A list of parent folders for an item. properties: entries: description: The parent folders for this item items: $ref: "#/components/schemas/Folder--Mini" nullable: false type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection type: object - description: |- The tree of folders that this file is contained in, starting at the root. - nullable: false purged_at: description: |- The time at which this file is expected to be purged from the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string shared_link: allOf: - 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. properties: access: description: |- The access level for this shared link. * `open` - provides access to this item to anyone with this link * `company` - only provides access to this item to people the same company * `collaborators` - only provides access to this item to people who are collaborators on this item If this field is omitted when creating the shared link, the access level will be set to the default access level specified by the enterprise admin. enum: - open - company - collaborators example: open nullable: false type: string download_count: description: The number of times this item has been downloaded. example: 3 nullable: false type: integer download_url: 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 format: url nullable: true type: string x-box-premium-feature: true effective_access: 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 type: string effective_permission: 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 type: string is_password_enabled: description: Defines if the shared link requires a password to access the item. example: true nullable: false type: boolean permissions: 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. properties: can_download: 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`. example: true nullable: false type: boolean can_edit: 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`. example: false nullable: false type: boolean can_preview: 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. example: true nullable: false type: boolean required: - can_download - can_preview - can_edit type: object preview_count: description: The number of times this item has been previewed. example: 3 nullable: false type: integer unshared_at: 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 format: date-time nullable: true type: string 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 format: url nullable: false type: string vanity_name: description: The custom name of a shared link, as used in the `vanity_url` field. example: my_url nullable: true type: string vanity_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/ format: url nullable: true type: string required: - url - accessed - effective_access - effective_permission - is_password_enabled - download_count - preview_count title: Shared link type: object - description: |- The shared link for this file. This will be `null` if no shared link has been created for this file. - nullable: true size: description: |- The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. example: 629644 nullable: false type: integer trashed_at: description: The time at which this file was put in the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string description: |- A standard representation of a file, as returned from any file API endpoints by default required: - description - size - path_collection - created_at - modified_at - modified_by - owned_by - item_status title: File type: object x-box-resource-id: file x-box-variant: standard File--Base: description: |- The bare basic representation of a file, the minimal amount of fields returned when using the `fields` query parameter. properties: etag: 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. example: "1" nullable: true type: string id: 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" nullable: false type: string type: description: "`file`" enum: - file example: file nullable: false type: string required: - id - type title: File (Base) type: object x-box-resource-id: file--base x-box-sanitized: true x-box-tag: files x-box-variant: base x-box-variants: - base - mini - standard - full File--Full: allOf: - $ref: "#/components/schemas/File" - properties: allowed_invitee_roles: description: |- A list of the types of roles that user can be invited at when sharing this file. example: - editor items: enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner type: string nullable: false type: array classification: allOf: - description: The classification applied to an item properties: color: 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. example: "#FF0000" type: string definition: description: An explanation of the meaning of this classification. example: Content that should not be shared outside the company. type: string name: description: The name of the classification example: Top Secret type: string type: object - description: Details about the classification applied to this file. - nullable: true comment_count: description: The number of comments on this file example: 10 type: integer disposition_at: description: The retention expiration timestamp for the given file example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string expires_at: description: When the file will automatically be deleted example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string expiring_embed_link: allOf: - allOf: - description: The basics of an access token properties: access_token: description: The requested access token. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string expires_in: description: The time in seconds in seconds by which this token will expire. example: 3600 format: int64 type: integer restricted_to: 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/FileScope" type: array token_type: description: The type of access token returned. enum: - bearer example: bearer type: string type: object - properties: url: description: |- The actual expiring embed URL for this file, constructed from the file ID and access tokens specified in this object. example: https://cloud.app.box.com/preview/expiring_embed/... format: url type: string description: An expiring Box Embed Link. title: Expiring embed link type: 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. extension: description: |- Indicates the (optional) file extension for this file. By default, this is set to an empty string. example: pdf type: string has_collaborations: description: Specifies if this file has any other collaborators. example: true nullable: false type: boolean is_accessible_via_shared_link: description: |- Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder. enum: - true - false example: true type: boolean is_externally_owned: description: |- Specifies if this file is owned by a user outside of the authenticated enterprise. example: true nullable: false type: boolean is_package: description: |- Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files. example: true type: boolean lock: allOf: - 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: app_type: 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 type: string created_at: description: The time this lock was created at. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created the lock. expired_at: description: The time this lock is to expire at, which might be in the past. example: 2012-12-12T10:53:43-08:00 format: date-time type: string id: description: The unique identifier for this lock example: "11446498" type: string is_download_prevented: description: Whether or not the file can be downloaded while locked. example: true type: boolean type: description: "`lock`" enum: - lock example: lock type: string title: Lock type: object - 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 metadata: allOf: - additionalProperties: additionalProperties: $ref: "#/components/schemas/Metadata" 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 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 title: Item metadata instances type: object - 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. permissions: allOf: - allOf: - description: The permissions that the authenticated user has for an item. properties: can_delete: description: Specifies if the current user can delete this item. example: true nullable: false type: boolean can_download: description: Specifies if the current user can download this item. example: true nullable: false type: boolean can_invite_collaborator: 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 type: boolean can_rename: description: Specifies if the user can rename this item. example: true nullable: false type: boolean can_set_share_access: description: |- Specifies if the user can change the access level of an existing shared link on this item. example: true nullable: false type: boolean can_share: description: Specifies if the user can create a shared link for this item. example: true nullable: false type: boolean required: - can_delete - can_download - can_invite_collaborator - can_rename - can_set_share_access - can_share type: object - properties: can_annotate: description: Specifies if the user can place annotations on this file. example: true nullable: false type: boolean can_comment: description: Specifies if the user can place comments on this file. example: true nullable: false type: boolean can_preview: description: Specifies if the user can preview this file. example: true nullable: false type: boolean can_upload: description: Specifies if the user can upload a new version of this file. example: true nullable: false type: boolean can_view_annotations_all: description: Specifies if the user view all annotations placed on this file example: true nullable: false type: boolean can_view_annotations_self: description: |- Specifies if the user view annotations placed by themselves on this file example: true nullable: false type: boolean 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 type: object - description: |- Describes the permissions that the current user has for this file. - nullable: false representations: allOf: - description: A list of file representations properties: entries: description: A list of files items: description: A file representation properties: content: description: |- An object containing the URL that can be used to actually fetch the representation. properties: url_template: description: |- The download URL that can be used to fetch the representation. Make sure to make an authenticated API call to this endpoint. This URL is a template and will require the `{+asset_path}` to be replaced by a path. In general, for unpaged representations it can be replaced by an empty string. For paged representations, replace the `{+asset_path}` with the page to request plus the extension for the file, for example `1.pdf`. When requesting the download URL the following additional query params can be passed along. * `set_content_disposition_type` - Sets the `Content-Disposition` header in the API response with the specified disposition type of either `inline` or `attachment`. If not supplied, the `Content-Disposition` header is not included in the response. * `set_content_disposition_filename` - Allows the application to define the representation's file name used in the `Content-Disposition` header. If not defined, the filename is derived from the source file name in Box combined with the extension of the representation. example: https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567 type: string type: object info: description: |- An object containing the URL that can be used to fetch more info on this representation. properties: url: 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. example: https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048 type: string type: object properties: description: An object containing the size and type of this presentation. properties: dimensions: description: The width by height size of this representation in pixels. example: 2048x2048 format: x type: string paged: description: |- Indicates if the representation is build up out of multiple pages. example: true type: boolean thumb: description: |- Indicates if the representation can be used as a thumbnail of the file. example: true type: boolean type: object representation: description: Indicates the file type of the returned representation. example: png type: string status: description: An object containing the status of this representation. properties: state: description: |- The status of the representation. * `success` defines the representation as ready to be viewed. * `viewable` defines a video to be ready for viewing. * `pending` defines the representation as to be generated. Retry this endpoint to re-check the status. * `none` defines that the representation will be created when requested. Request the URL defined in the `info` object to trigger this generation. enum: - success - viewable - pending - none example: success type: string type: object type: object type: array title: Representations type: object - 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. shared_link_permission_options: description: |- A list of the types of roles that user can be invited at when sharing this file. example: - can_preview items: enum: - can_preview - can_download - can_edit type: string nullable: true type: array tags: allOf: - 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. example: - approved items: type: string maxItems: 100 minItems: 1 type: array - nullable: false uploader_display_name: allOf: - 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`. example: Ellis Wiggins nullable: false title: Uploader display name type: string version_number: description: The version number of this file example: "1" type: string watermark_info: allOf: - description: Details about the watermark applied to this item properties: is_watermarked: description: Specifies if this item has a watermark applied. example: true nullable: false type: boolean type: object - description: Details about the watermark applied to this file description: |- A full representation of a file, as can be returned from any file API endpoints by default title: File (Full) type: object x-box-resource-id: file--full x-box-variant: full File--Mini: allOf: - $ref: "#/components/schemas/File--Base" - properties: file_version: allOf: - $ref: "#/components/schemas/FileVersion--Mini" - description: The information about the current version of the file. name: description: The name of the file example: Contract.pdf type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false sha1: description: |- The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37 format: digest nullable: false type: string description: |- A mini representation of a file, used when nested under another resource. required: - sequence_id - sha1 title: File (Mini) type: object x-box-resource-id: file--mini x-box-variant: mini FileConflict: allOf: - $ref: "#/components/schemas/File--Mini" - properties: file_version: $ref: "#/components/schemas/FileVersion--Mini" sha1: description: The SHA1 hash of the file. example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37 type: string description: A representation of a file that is used to show title: File (Conflict) type: object x-box-resource-id: file_conflict x-box-sanitized: true x-box-tag: null FileRequest: description: |- A standard representation of a file request, as returned from any file request API endpoints by default. properties: created_at: description: The date and time when the file request was created. example: 2020-09-28T10:53:43-08:00 format: date-time nullable: false type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this file request. description: description: |- The optional description of this file request. This is shown in the Box UI to users uploading files. This defaults to description of the file request that was copied to create this file request. example: Following documents are requested for your process nullable: true type: string etag: description: |- The HTTP `etag` of this file. This can be used in combination with the `If-Match` header when updating a file request. By providing that header, a change will only be performed on the file request if the `etag` on the file request still matches the `etag` provided in the `If-Match` header. example: "1" nullable: true type: string expires_at: description: |- The date after which a file request will no longer accept new submissions. After this date, the `status` will automatically be set to `inactive`. example: 2020-09-28T10:53:43-08:00 format: date-time type: string folder: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: |- The folder that this file request is associated with. Files submitted through the file request form will be uploaded to this folder. nullable: false id: description: The unique identifier for this file request. example: "42037322" readOnly: true type: string is_description_required: description: |- Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This defaults to setting of file request that was copied to create this file request. example: true type: boolean is_email_required: description: |- Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This defaults to setting of file request that was copied to create this file request. example: true type: boolean status: description: |- The status of the file request. This defaults to `active`. When the status is set to `inactive`, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a `HTTP 404` status code. This defaults to status of file request that was copied to create this file request. enum: - active - inactive example: active type: string title: description: |- The title of file request. This is shown in the Box UI to users uploading files. This defaults to title of the file request that was copied to create this file request. example: Please upload documents type: string type: description: "`file_request`" enum: - file_request example: file_request readOnly: true type: string updated_at: description: The date and time when the file request was last updated. example: 2020-09-28T10:53:43-08:00 format: date-time nullable: false type: string updated_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this file request. - nullable: false url: description: |- The generated URL for this file request. This URL can be shared with users to let them upload files to the associated folder. example: /f/19e57f40ace247278a8e3d336678c64a readOnly: true type: string required: - folder - created_at - updated_at title: File Request type: object x-box-resource-id: file_request x-box-tag: file_requests FileRequestCopyRequest: allOf: - $ref: "#/components/schemas/FileRequestUpdateRequest" - properties: folder: description: The folder to associate the new file request to. properties: id: description: |- The ID of the folder to associate the new file request to. example: "42037322" type: string type: description: "`folder`" enum: - folder example: folder type: string required: - id type: object description: The request body to copy a file request. required: - folder title: File Request (Copy) type: object FileRequestUpdateRequest: description: The request body to update a file request. properties: description: description: |- An optional new description for the file request. This can be used to change the description of the file request. This will default to the value on the existing file request. example: Please upload required documents type: string expires_at: description: |- The date after which a file request will no longer accept new submissions. After this date, the `status` will automatically be set to `inactive`. This will default to the value on the existing file request. example: 2020-09-28T10:53:43-08:00 format: date-time type: string is_description_required: description: |- Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This will default to the value on the existing file request. example: true type: boolean is_email_required: description: |- Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This will default to the value on the existing file request. example: true type: boolean status: description: |- An optional new status of the file request. When the status is set to `inactive`, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a `HTTP 404` status code. This will default to the value on the existing file request. enum: - active - inactive example: active type: string title: description: |- An optional new title for the file request. This can be used to change the title of the file request. This will default to the value on the existing file request. example: Please upload required documents type: string title: File Request (Update) type: object FileScope: description: A relation between a file and the scopes for which the file can be accessed properties: object: allOf: - $ref: "#/components/schemas/File--Mini" - description: The file for which the file can be accessed scope: description: The file scopes for the file access 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 example: item_download type: string title: File scope type: object FileVersion: allOf: - $ref: "#/components/schemas/FileVersion--Mini" - properties: created_at: description: When the file version object was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_at: description: When the file version object was last updated example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last updated the file version name: description: The name of the file version example: tigers.jpeg type: string purged_at: description: When the file version object will be permanently deleted. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string restored_at: description: When the file version was restored from the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string restored_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who restored the file version from the trash. size: description: Size of the file version in bytes example: 629644 format: int64 type: integer trashed_at: description: When the file version object was trashed. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string trashed_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who trashed the file version uploader_display_name: allOf: - 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`. example: Ellis Wiggins nullable: false title: Uploader display name type: string description: A standard representation of a file version title: File version type: object x-box-resource-id: file_version x-box-variant: standard FileVersion--Base: description: |- The bare basic representation of a file version, the minimal amount of fields returned when using the `fields` query parameter. properties: id: description: The unique identifier that represent a file version. example: "12345" nullable: false type: string type: description: "`file_version`" enum: - file_version example: file_version nullable: false type: string required: - id - type title: File version (Base) type: object x-box-resource-id: file_version--base x-box-sanitized: true x-box-variant: base x-box-variants: - base - mini - standard - full FileVersion--Full: allOf: - $ref: "#/components/schemas/FileVersion" - properties: version_number: description: The version number of this file version example: "1" type: string description: |- A full representation of a file version, as can be returned from any file version API endpoints by default title: File version (Full) type: object x-box-resource-id: file_version--full x-box-variant: full FileVersion--Mini: allOf: - $ref: "#/components/schemas/FileVersion--Base" - properties: sha1: description: The SHA1 hash of this version of the file. example: 134b65991ed521fcfe4724b7d814ab8ded5185dc type: string description: |- A mini representation of a file version, used when nested within another resource. title: File version (Mini) type: object x-box-resource-id: file_version--mini x-box-variant: mini FileVersionLegalHold: description: |- File-Version-Legal-Hold is an entity representing all holds on a File Version. properties: deleted_at: description: |- Time that this File-Version-Legal-Hold was deleted. example: 2012-12-12T10:53:43-08:00 format: date-time type: string file: allOf: - $ref: "#/components/schemas/File--Mini" - description: |- The file for the file version held. Note that there is no guarantee that the current version of this file is held. file_version: allOf: - $ref: "#/components/schemas/FileVersion--Mini" - description: The file version that is held id: description: The unique identifier for this file version legal hold example: "11446498" type: string legal_hold_policy_assignments: description: List of assignments contributing to this Hold. items: $ref: "#/components/schemas/LegalHoldPolicyAssignment" type: array type: description: "`file_version_legal_hold`" enum: - file_version_legal_hold example: file_version_legal_hold type: string title: File version legal hold type: object x-box-resource-id: file_version_legal_hold x-box-tag: file_version_legal_holds FileVersionLegalHolds: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/FileVersionLegalHold" type: array description: A list of file version legal holds. title: File version legal holds type: object x-box-resource-id: file_version_legal_holds x-box-tag: file_version_legal_holds FileVersionRetention: description: |- A retention policy blocks permanent deletion of content for a specified amount of time. Admins can apply policies to specified folders, or an entire enterprise. A file version retention is a record for a retained file version. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. For more information about retention policies, please visit our help documentation properties: applied_at: description: |- When this file version retention object was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string disposition_at: description: |- When the retention expires on this file version retention example: 2012-12-12T10:53:43-08:00 format: date-time type: string file: allOf: - $ref: "#/components/schemas/File--Mini" - description: The file this file version retention was applied to file_version: allOf: - $ref: "#/components/schemas/FileVersion--Mini" - description: |- The file version this file version retention was applied to id: description: The unique identifier for this file version retention. example: "11446498" type: string type: description: "`file_version_retention`" enum: - file_version_retention example: file_version_retention type: string winning_retention_policy: allOf: - $ref: "#/components/schemas/RetentionPolicy--Mini" - description: |- The winning retention policy applied to this file version retention. A file version can have multiple retention policies applied. title: File version retention type: object x-box-resource-id: file_version_retention x-box-tag: file_version_retentions FileVersionRetentions: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/FileVersionRetention" type: array description: A list of file version retentions. title: File version retentions type: object x-box-resource-id: file_version_retentions x-box-tag: file_version_retentions FileVersions: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/FileVersion" type: array description: A list of file versions title: File versions type: object x-box-resource-id: file_versions x-box-tag: file_versions Files: description: A list of files properties: entries: description: A list of files items: $ref: "#/components/schemas/File" type: array total_count: description: The number of files. example: 1 format: int64 type: integer title: Files type: object x-box-resource-id: files x-box-tag: files FilesUnderRetention: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/File--Mini" type: array description: A list of files under retention. title: Files under retention type: object x-box-resource-id: files_under_retention x-box-tag: retention_policy_assignments Folder: allOf: - $ref: "#/components/schemas/Folder--Mini" - properties: content_created_at: description: |- The date and time at which this folder was originally created. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string content_modified_at: description: The date and time at which this folder was last updated. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string created_at: 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 format: date-time nullable: true type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this folder - nullable: false description: allOf: - description: The optional description of this folder example: Legal contracts for the new ACME deal maxLength: 256 nullable: false type: string - nullable: false folder_upload_email: nullable: true properties: access: 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. enum: - open - collaborators example: open nullable: false type: string email: description: The optional upload email address for this folder. example: upload.Contracts.asd7asd@u.box.com format: email nullable: false type: string type: object 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 item_status: 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 example: active nullable: false type: string modified_at: 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 format: date-time nullable: true type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this folder. - nullable: false owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this folder. - 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 path_collection: allOf: - description: A list of parent folders for an item. properties: entries: description: The parent folders for this item items: $ref: "#/components/schemas/Folder--Mini" nullable: false type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection type: object - description: |- The tree of folders that this folder is contained in, starting at the root. - nullable: false purged_at: description: |- The time at which this folder is expected to be purged from the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string shared_link: allOf: - 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. properties: access: description: |- The access level for this shared link. * `open` - provides access to this item to anyone with this link * `company` - only provides access to this item to people the same company * `collaborators` - only provides access to this item to people who are collaborators on this item If this field is omitted when creating the shared link, the access level will be set to the default access level specified by the enterprise admin. enum: - open - company - collaborators example: open nullable: false type: string download_count: description: The number of times this item has been downloaded. example: 3 nullable: false type: integer download_url: 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 format: url nullable: true type: string x-box-premium-feature: true effective_access: 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 type: string effective_permission: 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 type: string is_password_enabled: description: Defines if the shared link requires a password to access the item. example: true nullable: false type: boolean permissions: 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. properties: can_download: 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`. example: true nullable: false type: boolean can_edit: 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`. example: false nullable: false type: boolean can_preview: 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. example: true nullable: false type: boolean required: - can_download - can_preview - can_edit type: object preview_count: description: The number of times this item has been previewed. example: 3 nullable: false type: integer unshared_at: 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 format: date-time nullable: true type: string 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 format: url nullable: false type: string vanity_name: description: The custom name of a shared link, as used in the `vanity_url` field. example: my_url nullable: true type: string vanity_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/ format: url nullable: true type: string required: - url - accessed - effective_access - effective_permission - is_password_enabled - download_count - preview_count title: Shared link type: object - description: |- The shared link for this folder. This will be `null` if no shared link has been created for this folder. nullable: true size: description: |- The folder size in bytes. Be careful parsing this integer as its value can get very large. example: 629644 format: int64 nullable: false type: integer trashed_at: description: The time at which this folder was put in the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string description: |- A standard representation of a folder, as returned from any folder API endpoints by default required: - size - path_collection - created_by - modified_by - owned_by - item_status - item_collection title: Folder type: object x-box-resource-id: folder x-box-variant: standard Folder--Base: description: |- The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter. properties: etag: 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. example: "1" nullable: true type: string id: 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" nullable: false type: string type: description: "`folder`" enum: - folder example: folder nullable: false type: string required: - id - type title: Folder (Base) type: object x-box-resource-id: folder--base x-box-sanitized: true x-box-tag: folders x-box-variant: base x-box-variants: - base - mini - standard - full Folder--Full: allOf: - $ref: "#/components/schemas/Folder" - properties: allowed_invitee_roles: description: |- A list of the types of roles that user can be invited at when sharing this folder. example: - editor items: enum: - editor - viewer - previewer - uploader - previewer uploader - viewer uploader - co-owner type: string nullable: false type: array allowed_shared_link_access_levels: 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. example: - open items: enum: - open - company - collaborators type: string nullable: false type: array can_non_owners_invite: allOf: - description: |- Specifies if users who are not the owner of the folder can invite new collaborators to the folder. example: true type: boolean - nullable: false can_non_owners_view_collaborators: 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. example: true type: boolean classification: allOf: - description: The classification applied to an item properties: color: 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. example: "#FF0000" type: string definition: description: An explanation of the meaning of this classification. example: Content that should not be shared outside the company. type: string name: description: The name of the classification example: Top Secret type: string type: object - description: Details about the classification applied to this folder. - nullable: true has_collaborations: description: Specifies if this folder has any other collaborators. example: true nullable: false type: boolean is_accessible_via_shared_link: description: |- Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder. enum: - true - false example: true type: boolean is_collaboration_restricted_to_enterprise: allOf: - description: |- Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. example: true type: boolean - nullable: false is_externally_owned: description: |- Specifies if this folder is owned by a user outside of the authenticated enterprise. example: true nullable: false type: boolean metadata: allOf: - additionalProperties: additionalProperties: $ref: "#/components/schemas/Metadata" 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 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 title: Item metadata instances type: object - 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. permissions: allOf: - allOf: - description: The permissions that the authenticated user has for an item. properties: can_delete: description: Specifies if the current user can delete this item. example: true nullable: false type: boolean can_download: description: Specifies if the current user can download this item. example: true nullable: false type: boolean can_invite_collaborator: 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 type: boolean can_rename: description: Specifies if the user can rename this item. example: true nullable: false type: boolean can_set_share_access: description: |- Specifies if the user can change the access level of an existing shared link on this item. example: true nullable: false type: boolean can_share: description: Specifies if the user can create a shared link for this item. example: true nullable: false type: boolean required: - can_delete - can_download - can_invite_collaborator - can_rename - can_set_share_access - can_share type: object - properties: can_upload: description: Specifies if the user can upload into this folder. example: true nullable: false type: boolean description: The permissions that the authenticated user has for a folder. required: - can_upload type: object - description: |- Describes the permissions that the current user has for this folder - nullable: false sync_state: allOf: - 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 example: synced nullable: false type: string tags: allOf: - 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. example: - approved items: type: string maxItems: 100 minItems: 1 type: array - nullable: false watermark_info: allOf: - description: Details about the watermark applied to this item properties: is_watermarked: description: Specifies if this item has a watermark applied. example: true nullable: false type: boolean type: object - description: Details about the watermark applied to this folder - nullable: false description: |- A full representation of a folder, as can be returned from any folder API endpoints by default title: Folder (Full) type: object x-box-resource-id: folder--full x-box-variant: full Folder--Mini: allOf: - $ref: "#/components/schemas/Folder--Base" - properties: name: description: The name of the folder. example: Contracts nullable: false type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false description: |- A mini representation of a file version, used when nested under another resource. title: Folder (Mini) type: object x-box-resource-id: folder--mini x-box-variant: mini FolderLock: description: |- Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted. properties: created_at: description: When the folder lock object was created. example: 2020-09-14T23:12:53Z format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user or group that created the lock. folder: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: The folder that the lock applies to. id: description: The unique identifier for this folder lock. example: "12345678" type: string lock_type: description: The lock type, always `freeze`. example: freeze type: string locked_operations: description: | The operations that have been locked. Currently the `move` and `delete` operations cannot be locked separately, and both need to be set to `true`. properties: delete: description: Whether deleting the folder is restricted. example: true nullable: false type: boolean move: description: Whether moving the folder is restricted. example: true nullable: false type: boolean required: - move - delete type: object type: description: The object type, always `folder_lock`. example: folder_lock type: string title: Folder Lock type: object x-box-resource-id: folder_lock x-box-tag: folder_locks FolderLocks: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/FolderLock" type: array description: A list of folder locks title: Folder Locks type: object x-box-resource-id: folder_locks x-box-tag: folder_locks Group: allOf: - $ref: "#/components/schemas/Group--Mini" - properties: created_at: description: When the group object was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_at: description: When the group object was last modified example: 2012-12-12T10:53:43-08:00 format: date-time type: string description: |- A standard representation of a group, as returned from any group API endpoints by default title: Group type: object x-box-resource-id: group x-box-variant: standard Group--Base: description: A base representation of a group. properties: id: description: The unique identifier for this object example: "11446498" type: string type: description: "`group`" enum: - group example: group type: string title: Group (Base) type: object x-box-resource-id: group--base x-box-sanitized: true x-box-tag: groups x-box-variant: base x-box-variants: - base - mini - standard - full Group--Full: allOf: - $ref: "#/components/schemas/Group" - properties: description: description: Human readable description of the group. example: Support Group - as imported from Active Directory maxLength: 255 type: string external_sync_identifier: description: |- An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an Active Directory Object ID or a Google Group ID. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems. example: AD:123456 type: string invitability_level: description: |- Specifies who can invite the group to collaborate on items. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group. enum: - admins_only - admins_and_members - all_managed_users example: admins_only type: string member_viewability_level: description: |- Specifies who can view the members of the group (Get Memberships for Group). * `admins_only` - the enterprise admin, co-admins, group's group admin * `admins_and_members` - all admins and group members * `all_managed_users` - all managed users in the enterprise enum: - admins_only - admins_and_members - all_managed_users example: admins_only type: string permissions: allOf: - description: The permissions that the authenticated user has for a group. properties: can_invite_as_collaborator: description: Specifies if the user can invite the group to collaborate on any items. example: true type: boolean type: object - description: |- Describes the permissions that the current user has for this group. provenance: description: |- Keeps track of which external source this group is coming from (e.g. "Active Directory", "Google Groups", "Facebook Groups"). Setting this will also prevent Box users from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups. example: Active Directory maxLength: 255 type: string description: |- Groups contain a set of users, and can be used in place of users in some operations, such as collaborations. title: Group (Full) type: object x-box-resource-id: group--full x-box-variant: full Group--Mini: allOf: - $ref: "#/components/schemas/Group--Base" - properties: group_type: description: The type of the group. enum: - managed_group - all_users_group example: managed_group type: string name: description: The name of the group example: Support type: string description: |- Mini representation of a group, including id and name of group. title: Group (Mini) type: object x-box-resource-id: group--mini x-box-variant: mini GroupMembership: description: |- Membership is used to signify that a user is part of a group. properties: created_at: description: The time this membership was created. example: 2012-12-12T10:53:43-08:00 format: date-time type: string group: allOf: - $ref: "#/components/schemas/Group--Mini" - description: The group that the membership applies to id: description: The unique identifier for this group membership example: "11446498" type: string modified_at: description: The time this membership was last modified. example: 2012-12-12T10:53:43-08:00 format: date-time type: string role: description: The role of the user in the group. enum: - member - admin example: member type: string type: description: "`group_membership`" enum: - group_membership example: group_membership type: string user: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user that the membership applies to title: Group membership type: object x-box-resource-id: group_membership x-box-tag: memberships GroupMemberships: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/GroupMembership" type: array description: A list of group memberships. title: Group memberships type: object x-box-resource-id: group_memberships x-box-tag: memberships Groups: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/Group--Mini" type: array description: A list of groups. title: Groups type: object x-box-resource-id: groups x-box-tag: groups Invite: description: An invite for a user to an enterprise. properties: actionable_by: $ref: "#/components/schemas/User--Mini" created_at: description: When the invite was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string id: description: The unique identifier for this invite example: "11446498" type: string invited_by: $ref: "#/components/schemas/User--Mini" invited_to: description: A representation of a Box enterprise properties: id: description: The unique identifier for this enterprise. example: "11446498" type: string name: description: The name of the enterprise example: Acme Inc. type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string title: Enterprise type: object modified_at: description: When the invite was modified. example: 2012-12-12T10:53:43-08:00 format: date-time type: string status: description: The status of the invite example: pending type: string type: description: "`invite`" enum: - invite example: invite type: string title: Invite type: object x-box-resource-id: invite x-box-tag: invites Items: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: description: The items in this collection. items: oneOf: - $ref: "#/components/schemas/File--Mini" - $ref: "#/components/schemas/Folder--Mini" - $ref: "#/components/schemas/WebLink--Mini" type: array description: |- A list of files, folders, and web links in their mini representation. title: Items type: object x-box-resource-id: items x-box-tag: folders KeywordSkillCard: description: A skill card that contains a set of keywords properties: created_at: description: The optional date and time this card was created at. example: 2018-04-13T13:53:23-07:00 format: date-time type: string entries: description: An list of entries in the metadata card. items: description: An entry in the `entries` attribute of a metadata card properties: text: description: The text of the keyword. example: keyword1 type: string type: object type: array invocation: description: |- The invocation of this service, used to track which instance of a service applied the metadata. properties: id: description: |- A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata. example: image-recognition-service-123 type: string type: description: "`skill_invocation`" enum: - skill_invocation example: skill_invocation type: string required: - type - id type: object skill: description: The service that applied this metadata. properties: id: description: |- A custom identifier that represent the service that applied this metadata. example: image-recognition-service type: string type: description: "`service`" enum: - service example: service type: string required: - type - id type: object skill_card_title: description: The title of the card. properties: code: description: An optional identifier for the title. example: labels type: string message: description: The actual title to show in the UI. example: Labels type: string required: - message type: object skill_card_type: description: "`keyword`" enum: - keyword example: keyword type: string type: description: "`skill_card`" enum: - skill_card example: skill_card type: string required: - type - skill_card_type - skill - invocation - entries title: Keyword Skill Card type: object x-box-resource-id: keyword_skill_card x-box-tag: skills LegalHoldPolicies: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/LegalHoldPolicy" type: array description: A list of legal hold policies. title: Legal hold policies type: object x-box-resource-id: legal_hold_policies x-box-tag: legal_hold_policies LegalHoldPolicy: allOf: - $ref: "#/components/schemas/LegalHoldPolicy--Mini" - properties: assignment_counts: description: Counts of assignments within this a legal hold policy by item type properties: file: description: The number of files this policy is applied to example: 3 format: int64 type: integer file_version: description: The number of file versions this policy is applied to example: 4 format: int64 type: integer folder: description: The number of folders this policy is applied to example: 2 format: int64 type: integer user: description: The number of users this policy is applied to example: 1 format: int64 type: integer type: object created_at: description: When the legal hold policy object was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created the legal hold policy object deleted_at: description: |- When the policy release request was sent. (Because it can take time for a policy to fully delete, this isn't quite the same time that the policy is fully deleted). If `null`, the policy was not deleted. example: 2012-12-12T10:53:43-08:00 format: date-time type: string description: description: |- Description of the legal hold policy. Optional property with a 500 character limit. example: Postman created policy maxLength: 500 type: string filter_ended_at: description: |- User-specified, optional date filter applies to Custodian assignments only example: 2012-12-12T10:53:43-08:00 format: date-time type: string filter_started_at: description: |- User-specified, optional date filter applies to Custodian assignments only example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_at: description: |- When the legal hold policy object was modified. Does not update when assignments are added or removed. example: 2012-12-12T10:53:43-08:00 format: date-time type: string policy_name: description: Name of the legal hold policy. example: Policy 4 maxLength: 254 type: string release_notes: description: Optional notes about why the policy was created. example: Example maxLength: 500 type: string status: description: |- * 'active' - the policy is not in a transition state * 'applying' - that the policy is in the process of being applied * 'releasing' - that the process is in the process of being released * 'released' - the policy is no longer active enum: - active - applying - releasing - released example: active type: string description: |- Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates. title: Legal hold policy type: object x-box-resource-id: legal_hold_policy x-box-variant: standard LegalHoldPolicy--Mini: description: A mini legal hold policy properties: id: description: The unique identifier for this legal hold policy example: "11446498" type: string type: description: "`legal_hold_policy`" enum: - legal_hold_policy example: legal_hold_policy type: string title: Legal hold policy (Mini) type: object x-box-resource-id: legal_hold_policy--mini x-box-tag: legal_hold_policies x-box-variant: mini x-box-variants: - mini - standard LegalHoldPolicyAssignment: allOf: - $ref: "#/components/schemas/LegalHoldPolicyAssignment--Base" - properties: assigned_at: description: |- When the legal hold policy assignment object was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string assigned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: |- The user who created the legal hold policy assignment assigned_to: allOf: - oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - $ref: "#/components/schemas/WebLink" - description: |- The item that the the legal hold policy is assigned to. Includes type and ID. deleted_at: description: |- When the assignment release request was sent. (Because it can take time for an assignment to fully delete, this isn't quite the same time that the assignment is fully deleted). If null, Assignment was not deleted. example: 2012-12-12T10:53:43-08:00 format: date-time type: string legal_hold_policy: allOf: - $ref: "#/components/schemas/LegalHoldPolicy--Mini" - description: |- The policy that the legal hold policy assignment is part of description: |- Legal Hold Assignments are used to assign Legal Hold Policies to Users, Folders, Files, or File Versions. Creating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity. title: Legal hold policy assignment type: object x-box-resource-id: legal_hold_policy_assignment x-box-tag: legal_hold_policy_assignments LegalHoldPolicyAssignment--Base: description: |- Legal Hold Assignments are used to assign Legal Hold Policies to Users, Folders, Files, or File Versions. Creating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity. properties: id: description: The unique identifier for this legal hold assignment example: "11446498" type: string type: description: "`legal_hold_policy_assignment`" enum: - legal_hold_policy_assignment example: legal_hold_policy_assignment type: string title: Legal hold policy assignment (Base) type: object x-box-resource-id: legal_hold_policy_assignment--base x-box-sanitized: true x-box-tag: legal_hold_policy_assignments x-box-variant: base x-box-variants: - base - standard LegalHoldPolicyAssignments: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/LegalHoldPolicyAssignment--Base" type: array description: A list of legal hold policies assignments. title: Legal hold policy assignments type: object x-box-resource-id: legal_hold_policy_assignments x-box-tag: legal_hold_policy_assignments Metadata: allOf: - $ref: "#/components/schemas/Metadata--Base" description: |- An instance of a metadata template, which has been applied to a file or folder. title: Metadata instance type: object x-box-resource-id: metadata x-box-tag: file_metadata x-box-variant: standard Metadata--Base: description: The base representation of a metadata instance. properties: $parent: 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}`. example: folder_59449484661, type: string $scope: 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. example: enterprise_27335 type: string $template: description: The name of the template example: marketingCollateral type: string $version: description: |- The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified. example: 1 type: integer title: Metadata instance (Base) type: object x-box-resource-id: metadata--base x-box-sanitized: true x-box-tag: file_metadata x-box-variant: base x-box-variants: - base - standard - full Metadata--Full: allOf: - $ref: "#/components/schemas/Metadata" - properties: $canEdit: description: Whether the user can edit this metadata instance. example: true type: boolean $id: description: A UUID to identify the metadata instance. example: 01234500-12f1-1234-aa12-b1d234cb567e format: uuid maxLength: 36 type: string $type: description: |- A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application. example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0 type: string $typeVersion: description: |- The last-known version of the template of the object. This is an internal system property and should not be used by a client application. example: 2 type: integer - additionalProperties: example: Aaron Levie x-box-example-key: name description: |- An instance of a metadata template, which has been applied to a file or folder. title: Metadata instance (Full) type: object x-box-resource-id: metadata--full x-box-variant: full MetadataCascadePolicies: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/MetadataCascadePolicy" type: array description: A list of metadata cascade policies. title: Metadata cascade policies type: object x-box-resource-id: metadata_cascade_policies x-box-tag: metadata_cascade_policies MetadataCascadePolicy: description: |- A metadata cascade policy automatically applies a metadata template instance to all the files and folders within the targeted folder. properties: id: description: The ID of the metadata cascade policy object example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7 type: string owner_enterprise: description: The enterprise that owns this policy. properties: id: description: The ID of the enterprise that owns the policy. example: "690678" type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string type: object parent: description: Represent the folder the policy is applied to. properties: id: description: The ID of the folder the policy is applied to. example: "1234567" type: string type: description: "`folder`" enum: - folder example: folder type: string type: object scope: description: |- The scope of the of the template that is cascaded down to the folder's children. enum: - global - enterprise_* example: global type: string templateKey: description: |- The key of the template that is cascaded down to the folder's children. 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 example: productInfo type: string type: description: "`metadata_cascade_policy`" enum: - metadata_cascade_policy example: metadata_cascade_policy type: string title: Metadata cascade policy type: object x-box-resource-id: metadata_cascade_policy x-box-tag: metadata_cascade_policies MetadataFieldFilterDateRange: additionalProperties: description: Match a `date` metadata field to a range of values. example: gt: 2016-08-01T00:00:00Z lt: 2017-08-01T00:00:00Z properties: 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. example: 2016-08-01T00:00:00Z format: date-time type: string 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. example: 2017-08-01T00:00:00Z format: date-time type: string type: object x-box-example-key: expirationDate description: |- Specifies which `date` field on the template to filter the search results by, specifying a range of dates that can match. example: expirationDate: gt: 2016-08-01T00:00:00Z lt: 2017-08-01T00:00:00Z title: Metadata field filter (date range) type: object x-box-resource-id: metadata_field_filter_date_range MetadataFieldFilterFloat: additionalProperties: description: |- A mapping between a metadata `float` field key and the value to match search results on. example: 10000 type: number x-box-example-key: contractValue description: |- Specifies which `float` field on the template to filter the search results by. example: contractValue: 10000 title: Metadata field filter (float) type: object x-box-resource-id: metadata_field_filter_float MetadataFieldFilterFloatRange: additionalProperties: 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 properties: 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. example: 100000 type: number 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. example: 200000 type: number type: object x-box-example-key: value 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 title: Metadata field filter (float range) type: object x-box-resource-id: metadata_field_filter_float_range MetadataFieldFilterMultiSelect: additionalProperties: 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 type: array x-box-example-key: category 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 title: Metadata field filter (multi-select) type: object x-box-resource-id: metadata_field_filter_multi_select MetadataFieldFilterString: additionalProperties: description: |- A mapping between a metadata `string` field key and the value to match search results on. example: online type: string x-box-example-key: category description: |- Specifies which text field on the template to filter the search results by. example: category: online title: Metadata field filter (string) type: object x-box-resource-id: metadata_field_filter_string MetadataFilter: description: A metadata template to filter the search results by. properties: 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 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. enum: - global - enterprise - enterprise_{enterprise_id} example: enterprise type: string 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 example: contract type: string title: Metadata filter type: object x-box-resource-id: metadata_filter x-box-tag: search MetadataQuery: description: |- Create a search using SQL-like syntax to return items that match specific metadata. properties: ancestor_folder_id: 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" type: string fields: 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 items: type: string type: array from: 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 type: string limit: default: 100 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. example: 50 maximum: 100 minimum: 0 type: integer marker: description: Marker to use for requesting the next page. example: AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff type: string order_by: 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: description: |- An object representing one of the metadata template fields to sort the metadata query results by. properties: direction: description: |- The direction to order by, either ascending or descending. The `ordering` direction must be the same for each item in the array. enum: - ASC - DESC - asc - desc example: asc type: string field_key: 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 type: string type: object type: array query: 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 type: string query_params: additionalProperties: 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" type: string x-box-example-key: amount 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" type: object required: - from - ancestor_folder_id title: Metadata query search request type: object MetadataQueryIndex: description: A metadata query index properties: fields: description: A list of template fields which make up the index. items: allOf: - properties: key: description: The metadata template field key. example: vendor name type: string sort_direction: description: The sort direction of the field. enum: - asc - desc example: asc type: string description: The field which makes up the index. type: object type: array id: description: The ID of the metadata query index. example: "-9876" type: string status: description: The status of the metadata query index enum: - building - active - disabled example: active nullable: false type: string type: description: Value is always `metadata_query_index` example: metadata_query_index nullable: false type: string required: - type - status title: Metadata query index type: object x-box-resource-id: metadata_query_index x-box-tag: search MetadataQueryIndices: description: A collection of metadata query indices. properties: entries: description: A collection of metadata query indices. items: $ref: "#/components/schemas/MetadataQueryIndex" type: array limit: default: 100 description: The limit that was used for this request. example: 100 format: int64 type: integer 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 title: Metadata query indices type: object x-box-resource-id: metadata_query_indices x-box-tag: search MetadataQueryResults: 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. items: oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" type: array x-box-resource-variant: 1 limit: default: 100 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: 100 format: int64 type: integer 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 title: Metadata query search results type: object x-box-resource-id: metadata_query_results x-box-tag: search MetadataTemplate: description: A template for metadata that can be applied to files and folders properties: copyInstanceOnItemCopy: description: Whether or not to include the metadata when a file or folder is copied. example: true type: boolean displayName: description: |- The display name of the template. This can be seen in the Box web app and mobile apps. example: Product Info maxLength: 4096 type: string fields: description: |- An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list. items: allOf: - description: |- A field within a metadata template. Fields can be a basic text, date, or number field, or a list of options. properties: description: description: A description of the field. This is not shown to the user. example: The category maxLength: 4096 type: string displayName: description: |- The display name of the field as it is shown to the user in the web and mobile apps. example: Category maxLength: 4096 type: string hidden: description: |- Whether this field is hidden in the UI for the user and can only be set through the API instead. example: true type: boolean key: description: |- A unique identifier for the field. The identifier must be unique within the template to which it belongs. example: category maxLength: 256 type: string options: description: |- A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types. items: description: |- An option for a Metadata Template Field. Options only need to be provided for fields of type `enum` and `multiSelect`. Options represent the value(s) a user can select for the field either through the UI or through the API. properties: key: description: |- The text value of the option. This represents both the display name of the option and the internal key used when updating templates. example: Category 1 type: string required: - key title: Metadata Option (Write) type: object type: array type: description: |- The type of field. The basic fields are a `string` field for text, a `float` field for numbers, and a `date` fields to present the user with a date-time picker. Additionally, metadata templates support an `enum` field for a basic list of items, and ` multiSelect` field for a similar list of items where the user can select more than one value. enum: - string - float - date - enum - multiSelect example: string type: string required: - type - key - displayName title: Metadata Field (Write) type: object - properties: id: description: The unique ID of the metadata template field. example: 822227e0-47a5-921b-88a8-494760b2e6d2 type: string options: description: |- A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types. items: allOf: - description: |- An option for a Metadata Template Field. Options only need to be provided for fields of type `enum` and `multiSelect`. Options represent the value(s) a user can select for the field either through the UI or through the API. properties: key: description: |- The text value of the option. This represents both the display name of the option and the internal key used when updating templates. example: Category 1 type: string required: - key title: Metadata Option (Write) type: object - properties: id: description: The internal unique identifier of the the option. example: 45dc2849-a4a7-40a9-a751-4a699a589190 type: string description: |- An option for a Metadata Template Field. Options are only present for fields of type `enum` and `multiSelect`. Options represent the value(s) a user can select for the field either through the UI or through the API. type: object type: array description: |- A field within a metadata template. Fields can be a basic text, date, or number field, or a list of options. type: object type: array hidden: description: |- Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API. example: true type: boolean id: description: The ID of the metadata template. example: 58063d82-4128-7b43-bba9-92f706befcdf type: string scope: description: |- The scope of the metadata template can either be `global` or `enterprise_*`. The `global` scope is used for templates that are available to any Box enterprise. The `enterprise_*` scope represents templates that have been created within a specific enterprise, where `*` will be the ID of that enterprise. example: enterprise_123456 type: string templateKey: description: |- A unique identifier for the template. This identifier is unique across the `scope` of the enterprise to which the metadata template is being applied, yet is not necessarily unique across different enterprises. example: productInfo maxLength: 64 pattern: ^[a-zA-Z_][-a-zA-Z0-9_]*$ type: string type: description: "`metadata_template`" enum: - metadata_template example: metadata_template nullable: false type: string required: - type title: Metadata template type: object x-box-resource-id: metadata_template x-box-tag: metadata_templates MetadataTemplates: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/MetadataTemplate" type: array description: A list of metadata templates title: Metadata templates type: object x-box-resource-id: metadata_templates x-box-tag: metadata_templates Metadatas: description: A list of metadata instances that have been applied to a file or folder. properties: entries: description: A list of metadata instances, as applied to this file or folder. items: $ref: "#/components/schemas/Metadata" type: array limit: description: The limit that was used for this page of results. example: 100 type: integer title: Metadata instances type: object x-box-resource-id: metadatas x-box-tag: file_metadata OAuth2Error: description: An OAuth 2.0 error properties: error: description: The type of the error returned. example: invalid_client type: string error_description: description: The type of the error returned. example: The client credentials are not valid type: string title: OAuth 2.0 error type: object x-box-resource-id: oauth2_error x-box-tag: authorization PostOAuth2Revoke: description: A request to revoke an OAuth 2.0 token properties: client_id: description: |- The Client ID of the application requesting to revoke the access token. example: ly1nj6n11vionaie65emwzk575hnnmrk type: string client_secret: description: |- The client secret of the application requesting to revoke an access token. example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1 type: string token: description: The access token to revoke. example: n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW format: token type: string required: - grant_type title: Token revocation request type: object PostOAuth2Token: description: A request for a new OAuth 2.0 token properties: actor_token: description: |- The token used to create an annotator token. This is a JWT assertion. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string actor_token_type: description: |- The type of `actor_token` passed in. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. enum: - urn:ietf:params:oauth:token-type:id_token example: urn:ietf:params:oauth:token-type:id_token format: urn type: string assertion: description: |- A JWT assertion for which to request a new access token. Used in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. example: xxxxx.yyyyy.zzzzz format: jwt type: string box_shared_link: description: |- Full URL of the shared link on the file or folder that the token should be generated for. example: https://cloud.box.com/s/123456 format: url type: string box_subject_id: description: |- Used in combination with `client_credentials` as the `grant_type`. Value is determined by `box_subject_type`. If `user` use user ID and if `enterprise` use enterprise ID. example: "123456789" type: string box_subject_type: description: Used in combination with `client_credentials` as the `grant_type`. enum: - enterprise - user example: enterprise type: string client_id: description: |- The Client ID of the application requesting an access token. Used in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. example: ly1nj6n11vionaie65emwzk575hnnmrk type: string client_secret: description: |- The client secret of the application requesting an access token. Used in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1 type: string code: description: |- The client-side authorization code passed to your application by Box in the browser redirect after the user has successfully granted your application permission to make API calls on their behalf. Used in combination with `authorization_code` as the `grant_type`. example: n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW format: token type: string grant_type: description: |- The type of request being made, either using a client-side obtained authorization code, a refresh token, a JWT assertion, client credentials grant or another access token for the purpose of downscoping a token. enum: - authorization_code - refresh_token - client_credentials - urn:ietf:params:oauth:grant-type:jwt-bearer - urn:ietf:params:oauth:grant-type:token-exchange example: authorization_code format: urn type: string refresh_token: description: |- A refresh token used to get a new access token with. Used in combination with `refresh_token` as the `grant_type`. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string resource: description: Full URL for the file that the token should be generated for. example: https://api.box.com/2.0/files/123456 format: url type: string scope: description: |- The space-delimited list of scopes that you want apply to the new access token. The `subject_token` will need to have all of these scopes or the call will error with **401 Unauthorized**. example: item_upload item_preview base_explorer format: space_delimited_list type: string subject_token: description: |- The token to exchange for a downscoped token. This can be a regular access token, a JWT assertion, or an app token. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string subject_token_type: description: |- The type of `subject_token` passed in. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. enum: - urn:ietf:params:oauth:token-type:access_token example: urn:ietf:params:oauth:token-type:access_token type: string required: - grant_type title: Token request type: object PostOAuth2Token--RefreshAccessToken: description: |- A request to refresh an Access Token. Use this API to refresh an expired Access Token using a valid Refresh Token. properties: client_id: description: The client ID of the application requesting to refresh the token. example: ly1nj6n11vionaie65emwzk575hnnmrk type: string client_secret: description: The client secret of the application requesting to refresh the token. example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1 type: string grant_type: description: The type of request being made, in this case a refresh request. enum: - refresh_token example: refresh_token format: urn type: string refresh_token: description: The refresh token to refresh. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string required: - grant_type - client_id - client_secret - refresh_token title: Refresh access token type: object RealtimeServer: description: |- A real-time server that can be used for long polling user events properties: max_retries: description: |- The maximum number of retries this server will allow before a new long poll should be started by getting a [new list of server](#options-events). example: 10 type: integer retry_timeout: description: |- The maximum number of seconds without a response after which you should retry the long poll connection. This helps to overcome network issues where the long poll looks to be working but no packages are coming through. example: 610 type: integer ttl: description: The time in minutes for which this server is available example: 10 type: integer type: description: "`realtime_server`" example: realtime_server type: string url: description: The URL for the server. example: http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all type: string title: Real-time server type: object x-box-resource-id: realtime_server RealtimeServers: description: |- A list of real-time servers that can be used for long-polling. properties: chunk_size: description: The number of items in this response. example: 1 format: int64 type: integer entries: items: $ref: "#/components/schemas/RealtimeServer" type: array title: Real-time servers type: object x-box-resource-id: realtime_servers x-box-tag: events RecentItem: description: A recent item accessed by a user. properties: interacted_at: description: The time of the most recent interaction. example: 2018-04-13T13:53:23-07:00 format: date-time type: string interaction_shared_link: description: |- If the item was accessed through a shared link it will appear here, otherwise this will be null. example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg type: string interaction_type: description: |- The most recent type of access the user performed on the item. enum: - item_preview - item_upload - item_comment - item_open - item_modify example: item_preview type: string item: allOf: - oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - $ref: "#/components/schemas/WebLink" - description: The item that was recently accessed. type: description: "`recent_item`" example: recent_item type: string title: Recent item type: object x-box-resource-id: recent_item x-box-tag: recent_items RecentItems: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/RecentItem" type: array description: A list of recent items. title: Recent items type: object x-box-resource-id: recent_items RetentionPolicies: allOf: - properties: entries: description: A list in which each entry represents a retention policy object. items: $ref: "#/components/schemas/RetentionPolicy--Mini" type: array - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string type: object description: A list of retention policies. title: Retention policies type: object x-box-resource-id: retention_policies x-box-tag: retention_policies RetentionPolicy: allOf: - $ref: "#/components/schemas/RetentionPolicy--Mini" - properties: are_owners_notified: description: |- Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. example: false type: boolean assignment_counts: description: Counts the retention policy assignments for each item type. properties: enterprise: description: The number of enterprise assignments this policy has. The maximum value is 1. example: 1 format: int64 type: integer folder: description: The number of folder assignments this policy has. example: 1 format: int64 type: integer metadata_template: description: The number of metadata template assignments this policy has. example: 1 format: int64 type: integer type: object can_owner_extend_retention: description: |- Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. example: false type: boolean created_at: description: When the retention policy object was created. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: |- A mini user object representing the user that created the retention policy. custom_notification_recipients: description: A list of users notified when the retention policy duration is about to end. items: $ref: "#/components/schemas/User--Mini" type: array description: description: The additional text description of the retention policy. example: Policy to retain all reports for at least one month type: string modified_at: description: When the retention policy object was last modified. example: 2012-12-12T10:53:43-08:00 format: date-time type: string policy_type: description: |- The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown. enum: - finite - indefinite example: finite type: string retention_type: description: |- Specifies the retention type: * `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. * `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. enum: - modifiable - non-modifiable example: non-modifiable type: string status: description: |- The status of the retention policy. The status of a policy will be `active`, unless explicitly retired by an administrator, in which case the status will be `retired`. Once a policy has been retired, it cannot become active again. enum: - active - retired example: active type: string description: |- A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders, metadata templates, or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console. title: Retention policy type: object x-box-resource-id: retention_policy x-box-tag: retention_policies x-box-variant: standard RetentionPolicy--Base: description: A base representation of a retention policy. properties: id: description: The unique identifier that represents a retention policy. example: "12345" nullable: false type: string type: description: "`retention_policy`" enum: - retention_policy example: retention_policy nullable: false type: string required: - id - type title: Retention policy (Base) type: object x-box-resource-id: retention_policy--base x-box-tag: retention_policies x-box-variant: base x-box-variants: - base - mini - standard RetentionPolicy--Mini: allOf: - $ref: "#/components/schemas/RetentionPolicy--Base" - properties: disposition_action: description: |- The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. enum: - permanently_delete - remove_retention example: permanently_delete type: string policy_name: description: The name given to the retention policy. example: Some Policy Name type: string retention_length: description: |- The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. example: "365" format: int32 minimum: 1 type: string description: |- A mini representation of a retention policy, used when nested within another resource. title: Retention policy (Mini) type: object x-box-resource-id: retention_policy--mini x-box-variant: mini RetentionPolicyAssignment: description: |- A retention assignment represents a rule specifying the files a retention policy retains. Assignments can retain files based on their folder or metadata, or hold all files in the enterprise. properties: assigned_at: description: |- When the retention policy assignment object was created. example: 2012-12-12T10:53:43-08:00 format: date-time type: string assigned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: |- A mini user object representing the user that created the retention policy assignment. assigned_to: description: |- The `type` and `id` of the content that is under retention. The `type` can either be `folder` `enterprise`, or `metadata_template`. properties: id: description: |- The ID of the folder, enterprise, or metadata template the policy is assigned to. example: a983f69f-e85f-4ph4-9f46-4afdf9c1af65 type: string type: description: The type of resource the policy is assigned to. enum: - folder - enterprise - metadata_template example: metadata_template type: string type: object filter_fields: description: |- An array of field objects. Values are only returned if the `assigned_to` type is `metadata_template`. Otherwise, the array is blank. items: nullable: true properties: field: description: The metadata attribute key id. example: a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4 nullable: true type: string value: description: |- The metadata attribute field id. For value, only enum and multiselect types are supported. example: 0c27b756-0p87-4fe0-a43a-59fb661ccc4e nullable: true type: string type: object nullable: true type: array id: description: The unique identifier for a retention policy assignment. example: "11446498" type: string retention_policy: allOf: - $ref: "#/components/schemas/RetentionPolicy--Mini" - description: |- A mini representation of a retention policy object that has been assigned to the content. start_date_field: description: |- The date the retention policy assignment begins. If the `assigned_to` type is `metadata_template`, this field can be a date field's metadata attribute key id. example: upload_date type: string type: description: "`retention_policy_assignment`" enum: - retention_policy_assignment example: retention_policy_assignment type: string title: Retention policy assignment type: object x-box-resource-id: retention_policy_assignment x-box-tag: retention_policy_assignments RetentionPolicyAssignment--Base: description: A base representation of a retention policy assignment. properties: id: description: The unique identifier that represents a file version. example: "12345" nullable: false type: string type: description: "`retention_policy_assignment`" enum: - retention_policy_assignment example: retention_policy_assignment nullable: false type: string required: - id - type title: Retention policy assignment (Base) type: object x-box-resource-id: retention_policy_assignment--base x-box-tag: retention_policy_assignments x-box-variant: base x-box-variants: - base - standard RetentionPolicyAssignments: allOf: - properties: entries: items: $ref: "#/components/schemas/RetentionPolicyAssignment--Base" type: array - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string type: object description: A list of retention policy assignments. title: Retention policy assignments type: object x-box-resource-id: retention_policy_assignments x-box-tag: retention_policy_assignments SearchResultWithSharedLink: 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 format: url type: string item: allOf: - oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - $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 title: Search Result (including Shared Link) type: object x-box-resource-id: search_result_with_shared_link x-box-tag: search SearchResults: allOf: - properties: 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 format: int64 type: integer 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 format: int64 type: integer 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 format: int64 type: integer type: object - properties: entries: description: The search results for the query provided. items: oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - $ref: "#/components/schemas/WebLink" type: array description: A list of files, folders and web links that matched the search query. title: Search Results type: object x-box-resource-id: search_results x-box-tag: search SearchResultsWithSharedLinks: allOf: - properties: 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 format: int64 type: integer 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 format: int64 type: integer 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 format: int64 type: integer type: object - properties: 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. items: $ref: "#/components/schemas/SearchResultWithSharedLink" type: array 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`. title: Search Results (including Shared Links) type: object x-box-resource-id: search_results_with_shared_links x-box-tag: search SessionTerminationMessage: description: |- A message informing about the termination job status properties: message: description: The unique identifier for the termination job status example: Request is successful, please check the admin events for the status of the job type: string title: Session termination message type: object x-box-resource-id: session_termination x-box-tag: session_termination ShieldInformationBarrier: description: |- A standard representation of a shield information barrier object properties: created_at: description: |- ISO date time string when this shield information barrier object was created. example: 2020-06-26T18:44:45.869Z format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who created this shield information barrier. enabled_at: description: ISO date time string when this shield information barrier was enabled. example: 2020-07-26T18:44:45.869Z format: date-time type: string enabled_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user that enabled this shield information barrier. enterprise: allOf: - $ref: "#/components/schemas/Enterprise--Base" - description: The `type` and `id` of enterprise this barrier is under. id: description: The unique identifier for the shield information barrier example: "11446498" type: string status: description: Status of the shield information barrier enum: - draft - pending - disabled - enabled - invalid example: draft type: string type: description: The type of the shield information barrier enum: - shield_information_barrier example: shield_information_barrier type: string updated_at: description: ISO date time string when this shield information barrier was updated. example: 2020-07-26T18:44:45.869Z format: date-time type: string updated_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user that updated this shield information barrier. title: Shield information barrier type: object x-box-resource-id: shield_information_barrier x-box-tag: shield_information_barriers x-box-variant: standard x-box-variants: - base - standard ShieldInformationBarrier--Base: description: |- A base representation of a shield information barrier object properties: id: description: The unique identifier for the shield information barrier example: "11446498" type: string type: description: The type of the shield information barrier enum: - shield_information_barrier example: shield_information_barrier type: string title: Shield information barrier (Base) type: object x-box-resource-id: shield_information_barrier--base x-box-tag: shield_information_barriers x-box-variant: base x-box-variants: - base - standard ShieldInformationBarrierReference: description: A shield information barrier reference for requests and responses properties: shield_information_barrier: $ref: "#/components/schemas/ShieldInformationBarrier--Base" title: Shield information barrier reference type: object x-box-resource-id: shield_information_barrier_reference x-box-tag: shield_information_barrier_reports ShieldInformationBarrierReport: allOf: - $ref: "#/components/schemas/ShieldInformationBarrierReport--Base" - properties: created_at: description: |- ISO date time string when this shield information barrier report object was created. example: 2020-06-26T18:44:45.869Z format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who created this shield information barrier report. details: allOf: - $ref: "#/components/schemas/ShieldInformationBarrierReportDetails" shield_information_barrier: allOf: - $ref: "#/components/schemas/ShieldInformationBarrierReference" status: description: Status of the shield information report enum: - pending - error - done - cancelled example: pending type: string updated_at: description: |- ISO date time string when this shield information barrier report was updated. example: 2020-07-26T18:44:45.869Z format: date-time type: string description: |- A standard representation of a shield information barrier report object title: Shield information barrier report type: object x-box-resource-id: shield_information_barrier_report x-box-tag: shield_information_barrier_reports x-box-variant: standard x-box-variants: - base - standard ShieldInformationBarrierReport--Base: description: |- A base representation of a shield information barrier report object properties: id: description: The unique identifier for the shield information barrier report example: "11446498" type: string type: description: The type of the shield information barrier report enum: - shield_information_barrier_report example: shield_information_barrier_report type: string title: Shield information barrier report (Base) type: object x-box-resource-id: shield_information_barrier_report--base x-box-tag: shield_information_barrier_reports x-box-variant: base x-box-variants: - base - standard ShieldInformationBarrierReportDetails: description: |- Indicates which folder the report file is located and any errors when generating the report. properties: details: properties: folder_id: description: Folder ID for locating this report example: "124235" type: string type: object title: Shield information barrier report details type: object x-box-resource-id: shield_information_barrier_report_details x-box-tag: shield_information_barrier_reports ShieldInformationBarrierSegment: description: A shield information barrier segment object properties: created_at: description: |- ISO date time string when this shield information barrier object was created. example: 2020-06-26T18:44:45.869Z format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who created this shield information barrier segment. description: description: Description of the shield information barrier segment example: |- 'Corporate division that engages in advisory_based financial transactions on behalf of individuals, corporations, and governments.' type: string id: description: The unique identifier for the shield information barrier segment example: "11446498" type: string name: description: Name of the shield information barrier segment example: Investment Banking type: string shield_information_barrier: $ref: "#/components/schemas/ShieldInformationBarrier--Base" type: description: The type of the shield information barrier segment enum: - shield_information_barrier_segment example: shield_information_barrier_segment type: string updated_at: description: |- ISO date time string when this shield information barrier segment was updated. example: 2020-07-26T18:44:45.869Z format: date-time type: string updated_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user that updated this shield information barrier segment. title: Shield information barrier segment type: object x-box-resource-id: shield_information_barrier_segment x-box-tag: shield_information_barrier_segments ShieldInformationBarrierSegmentMember: allOf: - $ref: "#/components/schemas/ShieldInformationBarrierSegmentMember--Mini" - properties: created_at: description: |- ISO date time string when this shield information barrier object was created. example: 2020-06-26T18:44:45.869Z format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who created this shield information barrier segment member. shield_information_barrier: $ref: "#/components/schemas/ShieldInformationBarrier--Base" shield_information_barrier_segment: description: |- The `type` and `id` of the requested shield information barrier segment. properties: id: description: |- The ID reference of the requesting shield information barrier segment. example: "432554" type: string type: description: The type of the shield information barrier segment enum: - shield_information_barrier_segment example: shield_information_barrier_segment type: string type: object updated_at: description: |- ISO date time string when this shield information barrier segment Member was updated. example: 2020-07-26T18:44:45.869Z format: date-time type: string updated_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user that updated this shield information barrier segment Member. user: allOf: - $ref: "#/components/schemas/User--Base" - description: The `type` and `id` of the requested shield information barrier segment member. description: |- A standard representation of a shield information barrier segment member object title: Shield information barrier segment member type: object x-box-resource-id: shield_information_barrier_segment_member x-box-tag: shield_information_barrier_segment_members x-box-variant: standard x-box-variants: - base - mini - standard ShieldInformationBarrierSegmentMember--Base: description: |- A base representation of a shield information barrier segment member object properties: id: description: |- The unique identifier for the shield information barrier segment member example: "11446498" type: string type: description: The type of the shield information barrier segment member enum: - shield_information_barrier_segment_member example: shield_information_barrier_segment_member type: string title: Shield information barrier segment member (Base) type: object x-box-resource-id: shield_information_barrier_segment_member--base x-box-tag: shield_information_barrier_segment_members x-box-variant: base x-box-variants: - base - mini - standard ShieldInformationBarrierSegmentMember--Mini: allOf: - $ref: "#/components/schemas/ShieldInformationBarrierSegmentMember--Base" - properties: user: allOf: - $ref: "#/components/schemas/User--Base" - description: The `type` and `id` of the requested shield information barrier segment member. description: |- A mini representation of a shield information barrier segment member object title: Shield information barrier segment member (Mini) type: object x-box-resource-id: shield_information_barrier_segment_member--mini x-box-tag: shield_information_barrier_segment_members x-box-variant: mini x-box-variants: - base - mini - standard ShieldInformationBarrierSegmentRestriction: allOf: - $ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Mini" - properties: created_at: description: |- ISO date time string when this shield information barrier Segment Restriction object was created. example: 2020-06-26T18:44:45.869Z format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who created this shield information barrier segment Restriction. shield_information_barrier: $ref: "#/components/schemas/ShieldInformationBarrier--Base" updated_at: description: |- ISO date time string when this shield information barrier segment Restriction was updated. example: 2020-07-26T18:44:45.869Z format: date-time type: string updated_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user that updated this shield information barrier segment Restriction. description: |- A standard representation of a segment restriction of a shield information barrier object required: - shield_information_barrier_segment - restricted_segment title: Shield information barrier segment restriction type: object x-box-resource-id: shield_information_barrier_segment_restriction x-box-tag: shield_information_barrier_segment_restrictions x-box-variant: standard x-box-variants: - base - mini - standard ShieldInformationBarrierSegmentRestriction--Base: description: |- A base representation of a segment restriction object for the shield information barrier properties: id: description: |- The unique identifier for the shield information barrier segment restriction. example: "11446498" type: string type: description: Shield information barrier segment restriction enum: - shield_information_barrier_segment_restriction example: shield_information_barrier_segment_restriction type: string required: - shield_information_barrier_segment - restricted_segment title: Shield information barrier segment restriction (Base) type: object x-box-resource-id: shield_information_barrier_segment_restriction--base x-box-tag: shield_information_barrier_segment_restrictions x-box-variant: base x-box-variants: - base - mini - standard ShieldInformationBarrierSegmentRestriction--Mini: allOf: - $ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Base" - properties: restricted_segment: description: |- The `type` and `id` of the restricted shield information barrier segment. properties: id: description: |- The ID reference of the restricted shield information barrier segment. example: "1910967" type: string type: description: The type of the shield information segment enum: - shield_information_barrier_segment example: shield_information_barrier_segment type: string type: object shield_information_barrier_segment: description: |- The `type` and `id` of the requested shield information barrier segment. properties: id: description: |- The ID reference of the requesting shield information barrier segment. example: "1910967" type: string type: description: The type of the shield information barrier segment enum: - shield_information_barrier_segment example: shield_information_barrier_segment type: string type: object description: |- A mini representation of a segment restriction object for the shield information barrier required: - shield_information_barrier_segment - restricted_segment title: Shield information barrier segment restriction (Mini) type: object x-box-resource-id: shield_information_barrier_segment_restriction--mini x-box-tag: shield_information_barrier_segment_restrictions x-box-variant: mini x-box-variants: - base - mini - standard SignRequest: allOf: - $ref: "#/components/schemas/SignRequest--Base" - properties: auto_expire_at: description: Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned. example: 2021-04-26T08:12:13.982Z format: date-time nullable: true type: string id: description: Sign request ID example: "12345" type: string prepare_url: description: |- This URL is returned if `is_document_preparation_needed` is set to `true` in the request. It is used to prepare the sign request via UI. The sign request is not sent until preparation is complete. example: https://prepareurl.com nullable: true type: string sign_files: description: |- List of files that will be signed, which are copies of the original source files. A new version of these files are created as signers sign and can be downloaded at any point in the signing process. properties: files: items: $ref: "#/components/schemas/File--Mini" type: array is_ready_for_download: description: |- Indicates whether the `sign_files` documents are processing and the PDFs may be out of date. A change to any document requires processing on all `sign_files`. We recommended waiting until processing is finished (and this value is true) before downloading the PDFs. example: true type: boolean type: object signature_color: description: Force a specific color for the signature (blue, black, or red). example: blue nullable: true type: string signers: description: Array of signers for the sign request items: $ref: "#/components/schemas/SignRequestSigner" type: array signing_log: allOf: - $ref: "#/components/schemas/File--Mini" - description: |- Reference to a file that holds a log of all signer activity for the request source_files: description: List of files to create a signing document from. Only the ID and type fields are required for each file. The array will be empty if the `source_files` are deleted. items: $ref: "#/components/schemas/File--Mini" type: array status: description: Describes the status of the sign request enum: - converting - created - sent - viewed - signed - cancelled - declined - error_converting - error_sending - expired example: converting type: string type: description: object type enum: - sign-request example: sign-request type: string description: A Sign Request Object title: Sign Request type: object x-box-resource-id: sign_request x-box-tag: sign_requests SignRequest--Base: description: A request to create a sign request object properties: are_reminders_enabled: description: Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers. example: true type: boolean are_text_signatures_enabled: default: true description: Disables the usage of signatures generated by typing (text). example: true type: boolean days_valid: description: Number of days after which this request will automatically expire if not completed. example: 2 maximum: 730 minimum: 0 nullable: true type: integer declined_redirect_url: description: The uri that a signer will be redirected to after declining to sign a document. example: https://declined-redirect.com nullable: true type: string email_message: description: Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used. example: Hello! Please sign the document below nullable: true type: string email_subject: description: Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used. example: Sign Request from Acme nullable: true type: string external_id: description: This can be used to reference an ID in an external system that the sign request is related to. example: "123" nullable: true type: string is_document_preparation_needed: description: Indicates if the sender should receive a `prepare_url` in the response to complete document preparation via UI. example: true type: boolean is_phone_verification_required_to_view: description: Forces signers to verify a text message prior to viewing the document. You must specify the phone number of signers to have this setting apply to them. example: true nullable: true type: boolean name: description: Name of the sign request. example: name type: string parent_folder: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: |- The destination folder to place final, signed document and signing log. Only `ID` and `type` fields are required. The root folder, folder ID `0`, cannot be used. prefill_tags: description: When a document contains sign related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag. items: $ref: "#/components/schemas/SignRequestPrefillTag" type: array redirect_url: description: When specified, signature request will be redirected to this url when a document is signed. example: https://www.example.com nullable: true type: string required: - source_files - parent_folder title: Create a sign request type: object x-box-resource-id: sign_request--base x-box-tag: sign_requests SignRequestCreateRequest: allOf: - $ref: "#/components/schemas/SignRequest--Base" - properties: signature_color: description: Force a specific signature color (blue, black, or red). enum: - blue - black - red example: blue nullable: true type: string signers: description: |- Array of signers for the sign request. 35 is the max number of signers permitted. items: $ref: "#/components/schemas/SignRequestCreateSigner" type: array source_files: description: |- List of files to create a signing document from. This is currently limited to 10 files. Only the ID and type fields are required for each file. The array will be empty if the `source_files` are deleted. items: $ref: "#/components/schemas/File--Mini" maximum: 10 minimum: 1 type: array description: A request to create a sign request object required: - signers title: Create a sign request type: object SignRequestCreateSigner: description: The schema for a Signer in a POST Sign Request request body properties: declined_redirect_url: description: |- The URL that a signer will be redirect to after declining to sign a document. Defining this URL overrides default or global declined redirect URL settings for a specific signer. example: https://declined-example.com nullable: true type: string email: description: Email address of the signer example: example@gmail.com type: string embed_url_external_user_id: description: |- User ID for the signer in an external application responsible for authentication when accessing the embed URL. example: "1234" type: string is_in_person: description: |- Used in combination with an embed URL for a sender. After the sender signs, they are redirected to the next `in_person` signer. example: true type: boolean login_required: description: |- If set to true, signer will need to login to a Box account before signing the request. If the signer does not have an existing account, they will have an option to create a free Box account. example: true nullable: true type: boolean order: description: Order of the signer example: 2 minimum: 0 type: integer password: description: |- If set, the signer is required to enter the password before they are able to sign a document. This field is write only. example: SecretPassword123 type: string writeOnly: true redirect_url: description: |- The URL that a signer will be redirected to after signing a document. Defining this URL overrides default or global redirect URL settings for a specific signer. If no declined redirect URL is specified, this URL will be used for decline actions as well. example: https://example.com nullable: true type: string role: default: signer description: |- Defines the role of the signer in the sign request. A `signer` must sign the document and an `approver` must approve the document. A `final_copy_reader` only receives the final signed document and signing log. enum: - signer - approver - final_copy_reader example: signer type: string verification_phone_number: description: |- If set, this phone number is be used to verify the signer via two factor authentication before they are able to sign the document. example: "6314578901" type: string required: - email title: Signer fields for Create Sign Request type: object SignRequestPrefillTag: description: |- Prefill tags are used to prefill placeholders with signer input data. Only one value field can be included. properties: checkbox_value: description: Checkbox prefill value example: true type: boolean date_value: description: Date prefill value example: 2021-04-26T08:12:13.982Z format: date-time type: string document_tag_id: description: This references the ID of a specific tag contained in a file of the sign request. example: "1234" type: string text_value: description: Text prefill value example: text type: string title: Sign Request Prefill Tag type: object SignRequestSigner: allOf: - $ref: "#/components/schemas/SignRequestCreateSigner" - properties: embed_url: description: URL to direct a signer to for signing example: https://example.com readOnly: true type: string has_viewed_document: description: Set to `true` if the signer views the document example: true readOnly: true type: boolean inputs: items: $ref: "#/components/schemas/SignRequestSignerInput" readOnly: true type: array signer_decision: description: Final decision made by the signer properties: finalized_at: description: Date and Time that the decision was made example: 2021-04-26T08:12:13.982Z format: date-time type: string type: description: Type of decision made by the signer enum: - signed - declined example: signed type: string type: object description: The schema for a Signer in a GET Sign Request request body required: - email title: Signer fields for GET Sign Request response type: object SignRequestSignerInput: allOf: - $ref: "#/components/schemas/SignRequestPrefillTag" - properties: content_type: description: Content type of input enum: - initial - stamp - signature - company - title - email - full_name - first_name - last_name - text - date - checkbox - attachment example: signature type: string page_index: description: Index of page that the input is on example: 4 type: integer type: description: Type of input enum: - signature - date - text - checkbox example: text type: string description: Input created by a Signer on a Sign Request required: - page_index title: Sign Request Signer Input type: object SignRequests: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/SignRequest" type: array description: |- A standard representation of a sign request, as returned from any Box Sign API endpoints by default. title: Sign Requests type: object x-box-resource-id: sign_requests x-box-tag: sign_requests SkillCardsMetadata: description: The metadata assigned to a using for Box skills. properties: $canEdit: description: Whether the user can edit this metadata example: true type: boolean $id: description: A UUID to identify the metadata object example: 01234500-12f1-1234-aa12-b1d234cb567e format: uuid maxLength: 36 type: string $parent: description: An ID for the parent folder example: folder_59449484661, type: string $scope: description: |- An ID for the scope in which this template has been applied example: enterprise_27335 type: string $template: description: The name of the template example: properties type: string $type: description: |- A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application. example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0 type: string $typeVersion: description: |- The last-known version of the template of the object. This is an internal system property and should not be used by a client application. example: 2 type: integer $version: description: |- The version of the metadata object. Starts at 0 and increases every time a user-defined property is modified. example: 1 type: integer cards: description: A list of Box Skill cards that have been applied to this file. items: oneOf: - $ref: "#/components/schemas/KeywordSkillCard" - $ref: "#/components/schemas/TimelineSkillCard" - $ref: "#/components/schemas/TranscriptSkillCard" - $ref: "#/components/schemas/StatusSkillCard" type: array title: Skills metadata instance type: object x-box-resource-id: skill_cards_metadata x-box-tag: skills SkillInvocation: description: |- The payload of a Box skill as sent to a skill's `invocation_url`. properties: created_at: description: The time this invocation was created. example: 2012-12-12T10:53:43-08:00 format: date-time type: string enterprise: allOf: - description: A representation of a Box enterprise properties: id: description: The unique identifier for this enterprise. example: "11446498" type: string name: description: The name of the enterprise example: Acme Inc. type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string title: Enterprise type: object - description: The enterprise that this invocation was triggered for event: allOf: - $ref: "#/components/schemas/Event" - description: The event that triggered this invocation id: description: Unique identifier for the invocation request. example: fd1d2e53-35f5-41fb-9c25-4ba326daf2f9_341016304 type: string skill: allOf: - description: An object representing a skill properties: api_key: description: The client ID of the application example: hxel2s12wd2h9r8ne103c4gjbqefofih type: string id: description: The unique identifier for this skill example: "11446498" type: string name: description: The name of the skill example: Hello World Skill type: string type: description: "`skill`" enum: - skill example: skill type: string title: Skill type: object - description: The skill that triggered this invocation source: allOf: - oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - description: The item that caused the invocation to trigger status: description: The details status of this event. properties: additional_info: description: Additional status information. example: Example type: string error_code: description: Error code information, if error occurred. example: "400" type: string message: description: Status information example: Example type: string state: description: |- The state of this event. * `invoked` - Triggered the skill with event details to start applying skill on the file. * `processing` - Currently processing. * `success` - Completed processing with a success. * `transient_failure` - Encountered an issue which can be retried. * `permanent_failure` - Encountered a permanent issue and retry would not help. enum: - invoked - processing - success - transient_failure - permanent_failure example: invoked type: string type: object token: description: The read-only and read-write access tokens for this item properties: read: description: The basics of an access token properties: access_token: description: The requested access token. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string expires_in: description: The time in seconds in seconds by which this token will expire. example: 3600 format: int64 type: integer restricted_to: 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. example: '[{"scope":"gcm"}, {"scope":"item_upload","object_id":933941692081,"object_type":"file"}, {"scope":"manage_skill_invocations"}]' type: string token_type: description: The type of access token returned. enum: - bearer example: bearer type: string type: object write: description: The basics of an access token properties: access_token: description: The requested access token. example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ format: token type: string expires_in: description: The time in seconds in seconds by which this token will expire. example: 3600 format: int64 type: integer restricted_to: 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. example: '[{"scope":"gcm"}, {"scope":"item_upload","object_id":933941692081,"object_type":"file"}, {"scope":"manage_skill_invocations"}]' type: string token_type: description: The type of access token returned. enum: - bearer example: bearer type: string type: object type: object trigger: description: Action that triggered the invocation example: FILE_CONTENT type: string type: description: "`skill_invocation`" enum: - skill_invocation example: skill_invocation type: string title: Skill webhook payload type: object x-box-resource-id: skill_invocation x-box-tag: skills StatusSkillCard: description: A Box Skill metadata card that puts a status message in the metadata sidebar. properties: created_at: description: The optional date and time this card was created at. example: 2018-04-13T13:53:23-07:00 format: date-time type: string invocation: description: |- The invocation of this service, used to track which instance of a service applied the metadata. properties: id: description: |- A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata. example: image-recognition-service-123 type: string type: description: "`skill_invocation`" enum: - skill_invocation example: skill_invocation type: string required: - type - id type: object skill: description: The service that applied this metadata. properties: id: description: |- A custom identifier that represent the service that applied this metadata. example: image-recognition-service type: string type: description: "`service`" enum: - service example: service type: string required: - type - id type: object skill_card_title: description: The title of the card. properties: code: description: An optional identifier for the title. example: status type: string message: description: The actual title to show in the UI. example: Status type: string required: - message type: object skill_card_type: description: "`status`" enum: - status example: status type: string status: description: Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file. properties: code: description: |- A code for the status of this Skill invocation. By default each of these will have their own accompanied messages. These can be adjusted by setting the `message` value on this object. enum: - invoked - processing - success - transient_failure - permanent_failure example: success type: string message: description: |- A custom message that can be provided with this status. This will be shown in the web app to the end user. example: We're preparing to process your file. Please hold on! type: string required: - code type: object type: description: "`skill_card`" enum: - skill_card example: skill_card type: string required: - type - skill_card_type - skill - invocation - status title: Status Skill Card type: object x-box-resource-id: status_skill_card x-box-tag: skills StoragePolicies: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/StoragePolicy" type: array description: A list of storage policies. title: Storage policies type: object x-box-resource-id: storage_policies x-box-tag: storage_policies StoragePolicy: allOf: - $ref: "#/components/schemas/StoragePolicy--Mini" - properties: name: description: A descriptive name of the region example: Montreal / Dublin type: string description: The Storage Policy object describes the storage zone. title: Storage policy type: object x-box-resource-id: storage_policy x-box-variant: standard StoragePolicy--Mini: description: A mini description of a Storage Policy object properties: id: description: The unique identifier for this storage policy example: "11446498" type: string type: description: "`storage_policy`" enum: - storage_policy example: storage_policy type: string title: Storage policy (Mini) type: object x-box-resource-id: storage_policy--mini x-box-tag: storage_policies x-box-variant: mini x-box-variants: - standard - mini StoragePolicyAssignment: description: The assignment of a storage policy to a user or enterprise properties: assigned_to: allOf: - description: The bare basic reference for an object properties: id: description: The unique identifier for this object example: "11446498" type: string type: description: The type for this object example: file type: string title: Reference type: object - description: The enterprise or use the policy is assigned to storage_policy: allOf: - $ref: "#/components/schemas/StoragePolicy--Mini" - description: The assigned storage policy title: Storage policy assignment type: object x-box-resource-id: storage_policy_assignment x-box-tag: storage_policy_assignments StoragePolicyAssignments: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/StoragePolicyAssignment" type: array description: A list of storage policy assignments. title: Storage policy assignments type: object x-box-resource-id: storage_policy_assignments x-box-tag: storage_policy_assignments Task: description: |- A task allows for file-centric workflows within Box. Users can create tasks on files and assign them to other users for them to complete the tasks. properties: action: description: |- The type of task the task assignee will be prompted to perform. enum: - review - complete example: review type: string completion_rule: description: |- Defines which assignees need to complete this task before the task is considered completed. * `all_assignees` requires all assignees to review or approve the the task in order for it to be considered completed. * `any_assignee` accepts any one assignee to review or approve the the task in order for it to be considered completed. enum: - all_assignees - any_assignee example: all_assignees type: string created_at: description: When the task object was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created the task due_at: description: When the task is due example: 2012-12-12T10:53:43-08:00 format: date-time type: string id: description: The unique identifier for this task example: "11446498" type: string is_completed: description: Whether the task has been completed example: true type: boolean item: allOf: - $ref: "#/components/schemas/File--Mini" - description: The file associated with the task message: description: A message that will be included with the task example: Legal review type: string task_assignment_collection: allOf: - $ref: "#/components/schemas/TaskAssignments" - description: |- A collection of task assignment objects associated with the task type: description: "`task`" enum: - task example: task type: string title: Task type: object x-box-resource-id: task x-box-tag: tasks TaskAssignment: description: A task assignment defines which task is assigned to which user to complete. properties: assigned_at: description: The date at which this task was assigned to the user. example: 2012-12-12T10:53:43-08:00 format: date-time type: string assigned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who assigned this task. assigned_to: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user that the task has been assigned to. completed_at: description: |- The date at which this task assignment was completed. This will be `null` if the task is not completed yet. example: 2012-12-12T10:53:43-08:00 format: date-time type: string id: description: The unique identifier for this task assignment example: "11446498" type: string item: allOf: - $ref: "#/components/schemas/File--Mini" - description: The file that the task has been assigned to. message: description: |- A message that will is included with the task assignment. This is visible to the assigned user in the web and mobile UI. example: Please review type: string reminded_at: description: |- The date at which the assigned user was reminded of this task assignment. example: 2012-12-12T10:53:43-08:00 format: date-time type: string resolution_state: description: |- The current state of the assignment. The available states depend on the `action` value of the task object. enum: - completed - incomplete - approved - rejected example: incomplete type: string type: description: "`task_assignment`" enum: - task_assignment example: task_assignment type: string title: Task assignment type: object x-box-resource-id: task_assignment x-box-tag: task_assignments TaskAssignments: description: A list of task assignments properties: entries: items: $ref: "#/components/schemas/TaskAssignment" type: array total_count: description: The total number of items in this collection. example: 100 format: int64 type: integer title: Task assignments type: object x-box-resource-id: task_assignments x-box-tag: task_assignments Tasks: description: A list of tasks properties: entries: items: $ref: "#/components/schemas/Task" type: array 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`. example: 5000 format: int64 type: integer title: Tasks type: object x-box-resource-id: tasks x-box-tag: tasks TermsOfService: allOf: - $ref: "#/components/schemas/TermsOfService--Base" - properties: created_at: description: When the legal item was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string enterprise: allOf: - description: A representation of a Box enterprise properties: id: description: The unique identifier for this enterprise. example: "11446498" type: string name: description: The name of the enterprise example: Acme Inc. type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string title: Enterprise type: object - description: The enterprise these terms apply to modified_at: description: When the legal item was modified. example: 2012-12-12T10:53:43-08:00 format: date-time type: string status: description: Whether these terms are enabled or not enum: - enabled - disabled example: enabled type: string text: description: |- The text for your terms and conditions. This text could be empty if the `status` is set to `disabled`. example: By using this service, you agree to ... type: string tos_type: description: Whether to apply these terms to managed users or external users enum: - managed - external example: managed type: string description: |- The root-level record that is supposed to represent a single Terms of Service. title: Terms of service type: object x-box-resource-id: terms_of_service x-box-variant: standard TermsOfService--Base: description: |- The root-level record that is supposed to represent a single Terms of Service. properties: id: description: The unique identifier for this terms of service. example: "11446498" type: string type: description: "`terms_of_service`" enum: - terms_of_service example: terms_of_service type: string title: Terms of service (Base) type: object x-box-resource-id: terms_of_service--base x-box-tag: terms_of_services x-box-variant: base x-box-variants: - base - standard TermsOfServiceUserStatus: description: The association between a Terms of Service and a user properties: created_at: description: When the legal item was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string id: description: The unique identifier for this terms of service user status example: "11446498" type: string is_accepted: description: If the user has accepted the terms of services example: true type: boolean modified_at: description: When the legal item was modified. example: 2012-12-12T10:53:43-08:00 format: date-time type: string tos: allOf: - $ref: "#/components/schemas/TermsOfService--Base" - description: The terms of service type: description: "`terms_of_service_user_status`" enum: - terms_of_service_user_status example: terms_of_service_user_status type: string user: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user title: Terms of service user status type: object x-box-resource-id: terms_of_service_user_status x-box-tag: terms_of_service_user_statuses TermsOfServiceUserStatuses: description: A list of terms of service user statuses properties: entries: items: $ref: "#/components/schemas/TermsOfServiceUserStatus" type: array total_count: description: The total number of objects. example: 2 format: int64 type: integer title: Terms of service user statuses type: object x-box-resource-id: terms_of_services_user_statuses x-box-tag: terms_of_service_user_statuses TermsOfServices: description: A list of terms of services properties: entries: items: $ref: "#/components/schemas/TermsOfService" type: array total_count: description: The total number of objects. example: 2 format: int64 type: integer title: Terms of services type: object x-box-resource-id: terms_of_services x-box-tag: terms_of_services TimelineSkillCard: description: |- A Box Skill metadata card that places a list of images on a timeline. properties: created_at: description: The optional date and time this card was created at. example: 2018-04-13T13:53:23-07:00 format: date-time type: string duration: description: An total duration in seconds of the timeline. example: 1000 type: integer entries: description: A list of entries on the timeline. items: description: An single item that's placed on multiple items on the timeline. properties: appears: description: |- Defines a list of timestamps for when this item should appear on the timeline. items: description: The timestamp for an entry. properties: end: description: |- The time in seconds when an entry should stop appearing on a timeline. example: 20 type: integer start: description: |- The time in seconds when an entry should start appearing on a timeline. example: 1 type: integer type: object required: - start - end type: array image_url: description: |- The image to show on a for an entry that appears on a timeline. This image URL is required for every entry. The image will be shown in a list of items (for example faces), and clicking the image will show the user where that entry appears during the duration of this entry. example: https://example.com/image1.jpg type: string text: description: |- The text of the entry. This would be the display name for an item being placed on the timeline, for example the name of the person who was detected in a video. example: John type: string type: object type: array invocation: description: |- The invocation of this service, used to track which instance of a service applied the metadata. properties: id: description: |- A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata. example: image-recognition-service-123 type: string type: description: "`skill_invocation`" enum: - skill_invocation example: skill_invocation type: string required: - type - id type: object skill: description: The service that applied this metadata. properties: id: description: |- A custom identifier that represent the service that applied this metadata. example: image-recognition-service type: string type: description: "`service`" enum: - service example: service type: string required: - type - id type: object skill_card_title: description: The title of the card. properties: code: description: An optional identifier for the title. example: Faces type: string message: description: The actual title to show in the UI. example: Faces type: string required: - message type: object skill_card_type: description: "`timeline`" enum: - timeline example: timeline type: string type: description: "`skill_card`" enum: - skill_card example: skill_card type: string required: - type - skill_card_type - skill - invocation - entries title: Timeline Skill Card type: object x-box-resource-id: timeline_skill_card x-box-tag: skills TrackingCode: description: |- Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. properties: name: description: |- The name of the tracking code, which must be preconfigured in the Admin Console example: department type: string type: description: "`tracking_code`" enum: - tracking_code example: tracking_code type: string value: description: The value of the tracking code example: Sales type: string title: Tracking code type: object TranscriptSkillCard: description: A Box Skill metadata card that adds a transcript to a file. properties: created_at: description: The optional date and time this card was created at. example: 2018-04-13T13:53:23-07:00 format: date-time type: string duration: description: |- An optional total duration in seconds. Used with a `skill_card_type` of `transcript` or `timeline`. example: 1000 type: integer entries: description: |- An list of entries for the card. This represents the individual entries of the transcription. items: description: An entry in the `entries` attribute of a metadata card properties: appears: description: |- Defines when a transcribed bit of text appears. This only includes a start time and no end time. items: description: The timestamp for an entry. properties: start: description: |- The time in seconds when an entry should start appearing on a timeline. example: 1 type: integer type: object required: - start type: array text: description: |- The text of the entry. This would be the transcribed text assigned to the entry on the timeline. example: Hi, and welcome to this video... type: string type: object type: array invocation: description: |- The invocation of this service, used to track which instance of a service applied the metadata. properties: id: description: |- A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata. example: transciption-service-123 type: string type: description: "`skill_invocation`" enum: - skill_invocation example: skill_invocation type: string required: - type - id type: object skill: description: The service that applied this metadata. properties: id: description: |- A custom identifier that represent the service that applied this metadata. example: transciption-service type: string type: description: "`service`" enum: - service example: service type: string required: - type - id type: object skill_card_title: description: The title of the card. properties: code: description: An optional identifier for the title. example: my_transcripts type: string message: description: The actual title to show in the UI. example: My Transcripts type: string required: - message type: object skill_card_type: description: "`transcript`" enum: - transcript example: transcript type: string type: description: "`skill_card`" enum: - skill_card example: skill_card type: string required: - type - skill_card_type - skill - invocation - entries title: Transcript Skill Card type: object x-box-resource-id: transcript_skill_card x-box-tag: skills TrashFile: description: Represents a trashed file. properties: content_created_at: 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 format: date-time nullable: true type: string content_modified_at: 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 format: date-time nullable: true type: string created_at: description: The date and time when the file was created on Box. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: false type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this file description: description: The optional description of this file example: Contract for Q1 renewal maxLength: 256 nullable: false type: string etag: 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. example: "1" nullable: true type: string file_version: allOf: - $ref: "#/components/schemas/FileVersion--Mini" - description: The information about the current version of the file. id: 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: "123456789" nullable: false type: string item_status: 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 example: trashed nullable: false type: string modified_at: description: The date and time when the file was last updated on Box. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: false type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this file - nullable: false name: description: The name of the file example: Contract.pdf type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this file - nullable: false parent: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: The folder that this file is located within. - nullable: true path_collection: allOf: - description: A list of parent folders for an item in the trash. properties: entries: description: Array of folders for this item's path collection items: description: The parent folder for this item properties: etag: description: This field is null for the Trash folder example: null nullable: true type: string id: description: The unique identifier that represent a folder. example: "123456789" type: string name: description: The name of the Trash folder. example: Trash nullable: false type: string sequence_id: description: This field is null for the Trash folder example: null nullable: true type: string type: description: "`folder`" enum: - folder example: folder type: string type: object type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection (Trash) type: object - description: |- The tree of folders that this file is contained in, starting at the root. - nullable: false purged_at: description: |- The time at which this file is expected to be purged from the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false sha1: description: |- The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37 format: digest nullable: false type: string shared_link: description: |- The shared link for this file. This will be `null` if a file has been trashed, since the link will no longer be active. example: null nullable: true type: string size: description: |- The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. example: 629644 nullable: false type: integer trashed_at: description: The time at which this file was put in the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string type: description: "`file`" enum: - file example: file nullable: false type: string required: - id - type - sequence_id - sha1 - description - size - path_collection - created_at - modified_at - modified_by - owned_by - item_status title: Trashed File type: object x-box-resource-id: trash_file x-box-tag: trashed_files TrashFileRestored: description: Represents a file restored from the trash. properties: content_created_at: 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 format: date-time nullable: true type: string content_modified_at: 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 format: date-time nullable: true type: string created_at: description: The date and time when the file was created on Box. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: false type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this file description: description: The optional description of this file example: Contract for Q1 renewal maxLength: 256 nullable: false type: string etag: 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. example: "1" nullable: true type: string file_version: allOf: - $ref: "#/components/schemas/FileVersion--Mini" - description: The information about the current version of the file. id: 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: "123456789" nullable: false type: string item_status: 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 example: active nullable: false type: string modified_at: description: The date and time when the file was last updated on Box. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: false type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this file - nullable: false name: description: The name of the file example: Contract.pdf type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this file - nullable: false parent: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: The folder that this file is located within. - nullable: true path_collection: allOf: - description: A list of parent folders for an item. properties: entries: description: The parent folders for this item items: $ref: "#/components/schemas/Folder--Mini" nullable: false type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection type: object - description: |- The tree of folders that this file is contained in, starting at the root. - nullable: false purged_at: description: |- The time at which this file is expected to be purged from the trash - becomes `null` after restore. example: null nullable: true type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false sha1: description: |- The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37 format: digest nullable: false type: string shared_link: description: |- The shared link for this file. This will be `null` if a file had been trashed, even though the original shared link does become active again. example: null nullable: true type: string size: description: |- The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. example: 629644 nullable: false type: integer trashed_at: description: |- The time at which this file was put in the trash - becomes `null` after restore. example: null nullable: true type: string type: description: "`file`" enum: - file example: file nullable: false type: string required: - id - type - sequence_id - sha1 - description - size - path_collection - created_at - modified_at - modified_by - owned_by - item_status title: Trashed File (Restored) type: object x-box-resource-id: trash_file_restored x-box-tag: trashed_files TrashFolder: description: Represents a trashed folder. properties: content_created_at: description: |- The date and time at which this folder was originally created. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string content_modified_at: description: The date and time at which this folder was last updated. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string created_at: 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 format: date-time nullable: true type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this folder - nullable: false description: allOf: - description: The optional description of this folder example: Legal contracts for the new ACME deal maxLength: 256 nullable: false type: string - nullable: false etag: 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. example: "1" nullable: true type: string folder_upload_email: description: |- The folder upload email for this folder. This will be `null` if a folder has been trashed, since the upload will no longer work. example: null nullable: true type: string id: 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: "123456789" nullable: false type: string item_status: 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 example: trashed nullable: false type: string modified_at: 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 format: date-time nullable: true type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this folder. - nullable: false name: description: The name of the folder. example: Contracts nullable: false type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this folder. - 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 path_collection: allOf: - description: A list of parent folders for an item in the trash. properties: entries: description: Array of folders for this item's path collection items: description: The parent folder for this item properties: etag: description: This field is null for the Trash folder example: null nullable: true type: string id: description: The unique identifier that represent a folder. example: "123456789" type: string name: description: The name of the Trash folder. example: Trash nullable: false type: string sequence_id: description: This field is null for the Trash folder example: null nullable: true type: string type: description: "`folder`" enum: - folder example: folder type: string type: object type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection (Trash) type: object - description: |- The tree of folders that this file is contained in, starting at the root. - nullable: false purged_at: description: |- The time at which this folder is expected to be purged from the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false shared_link: description: |- The shared link for this folder. This will be `null` if a folder has been trashed, since the link will no longer be active. example: null nullable: true type: string size: description: |- The folder size in bytes. Be careful parsing this integer as its value can get very large. example: 629644 format: int64 nullable: false type: integer trashed_at: description: The time at which this folder was put in the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string type: description: "`folder`" enum: - folder example: folder nullable: false type: string required: - id - type - name - description - size - path_collection - created_by - modified_by - owned_by - item_status title: Trashed Folder type: object x-box-resource-id: trash_folder x-box-tag: trashed_folders TrashFolderRestored: description: Represents a folder restored from the trash. properties: content_created_at: description: |- The date and time at which this folder was originally created. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string content_modified_at: description: The date and time at which this folder was last updated. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string created_at: 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 format: date-time nullable: true type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this folder - nullable: false description: allOf: - description: The optional description of this folder example: Legal contracts for the new ACME deal maxLength: 256 nullable: false type: string - nullable: false etag: 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. example: "1" nullable: true type: string folder_upload_email: description: |- The folder upload email for this folder. This will be `null` if a folder has been trashed, even though the original upload email does become active again. example: null nullable: true type: string id: 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: "123456789" nullable: false type: string item_status: 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 example: active nullable: false type: string modified_at: 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 format: date-time nullable: true type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this folder. - nullable: false name: description: The name of the folder. example: Contracts nullable: false type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this folder. - 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 path_collection: allOf: - description: A list of parent folders for an item. properties: entries: description: The parent folders for this item items: $ref: "#/components/schemas/Folder--Mini" nullable: false type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection type: object - description: |- The tree of folders that this file is contained in, starting at the root. - nullable: false purged_at: description: |- The time at which this folder is expected to be purged from the trash - becomes `null` after restore. example: null nullable: true type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false shared_link: description: |- The shared link for this file. This will be `null` if a folder had been trashed, even though the original shared link does become active again. example: null nullable: true type: string size: description: |- The folder size in bytes. Be careful parsing this integer as its value can get very large. example: 629644 format: int64 nullable: false type: integer trashed_at: description: |- The time at which this folder was put in the trash - becomes `null` after restore. example: null nullable: true type: string type: description: "`folder`" enum: - folder example: folder nullable: false type: string title: Trashed Folder (Restored) type: object x-box-resource-id: trash_folder_restored x-box-tag: trashed_folders TrashWebLink: description: Represents a trashed web link. properties: created_at: description: When this file was created on Box’s servers. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this web link description: description: |- The description accompanying the web link. This is visible within the Box web application. example: Example page type: string etag: description: |- The entity tag of this web link. Used with `If-Match` headers. example: "1" type: string id: description: The unique identifier for this web link example: "11446498" type: string item_status: 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 enum: - active - trashed - deleted example: trashed type: string modified_at: description: |- When this file was last updated on the Box servers. example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this web link name: description: The name of the web link example: My Bookmark type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this web link parent: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: The parent object the web link belongs to path_collection: allOf: - description: A list of parent folders for an item in the trash. properties: entries: description: Array of folders for this item's path collection items: description: The parent folder for this item properties: etag: description: This field is null for the Trash folder example: null nullable: true type: string id: description: The unique identifier that represent a folder. example: "123456789" type: string name: description: The name of the Trash folder. example: Trash nullable: false type: string sequence_id: description: This field is null for the Trash folder example: null nullable: true type: string type: description: "`folder`" enum: - folder example: folder type: string type: object type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection (Trash) type: object - description: |- The tree of folders that this web link is contained in, starting at the root. - nullable: false purged_at: description: When this file will be permanently deleted. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false shared_link: description: |- The shared link for this bookmark. This will be `null` if a bookmark has been trashed, since the link will no longer be active. example: null nullable: true type: string trashed_at: description: When this file was last moved to the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string type: description: "`web_link`" enum: - web_link example: web_link type: string url: description: The URL this web link points to example: https://www.example.com/example/1234 type: string title: Trashed Web Link type: object x-box-resource-id: trash_web_link x-box-tag: trashed_web_links TrashWebLinkRestored: description: Represents a web link restored from the trash. properties: created_at: description: When this file was created on Box’s servers. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this web link description: description: |- The description accompanying the web link. This is visible within the Box web application. example: Example page type: string etag: description: |- The entity tag of this web link. Used with `If-Match` headers. example: "1" type: string id: description: The unique identifier for this web link example: "11446498" type: string item_status: 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 enum: - active - trashed - deleted example: trashed type: string modified_at: description: |- When this file was last updated on the Box servers. example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who last modified this web link name: description: The name of the web link example: My Bookmark type: string owned_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who owns this web link parent: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: The parent object the web link belongs to path_collection: allOf: - description: A list of parent folders for an item. properties: entries: description: The parent folders for this item items: $ref: "#/components/schemas/Folder--Mini" nullable: false type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection type: object - description: |- The tree of folders that this web link is contained in, starting at the root. - nullable: false purged_at: description: |- The time at which this bookmark will be permanently deleted - becomes `null` after restore. example: null nullable: true type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false shared_link: description: |- The shared link for this bookmark. This will be `null` if a bookmark had been trashed, even though the original shared link does become active again. example: null nullable: true type: string trashed_at: description: |- The time at which this bookmark was put in the trash - becomes `null` after restore. example: null nullable: true type: string type: description: "`web_link`" enum: - web_link example: web_link type: string url: description: The URL this web link points to example: https://www.example.com/example/1234 type: string required: - sequence_id - path_collection title: Trashed Web Link (Restored) type: object x-box-resource-id: trash_web_link_restored x-box-tag: trashed_web_links UploadPart: allOf: - $ref: "#/components/schemas/UploadPart--Mini" - properties: sha1: description: The SHA1 hash of the chunk. example: 134b65991ed521fcfe4724b7d814ab8ded5185dc type: string description: |- The representation of an upload session chunk. title: Upload part type: object x-box-resource-id: upload_part x-box-variant: standard UploadPart--Mini: description: |- The basic representation of an upload session chunk. properties: offset: description: |- The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file. example: 16777216 format: int64 type: integer part_id: description: The unique ID of the chunk. example: 6F2D3486 type: string size: description: The size of the chunk in bytes. example: 3222784 format: int64 type: integer title: Upload part (Mini) type: object x-box-resource-id: upload_part--mini x-box-tag: chunked_uploads x-box-variant: mini x-box-variants: - mini - standard UploadParts: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/UploadPart" type: array description: |- A list of uploaded chunks for an upload session. title: Upload parts type: object x-box-resource-id: upload_parts x-box-tag: chunked_uploads UploadSession: description: An upload session for chunk uploading a file. properties: id: description: The unique identifier for this session example: F971964745A5CD0C001BBE4E58196BFD type: string num_parts_processed: description: |- The number of parts that have been uploaded and processed by the server. This starts at `0`. When committing a file files, inspecting this property can provide insight if all parts have been uploaded correctly. example: 455 format: int32 type: integer part_size: description: |- The size in bytes that must be used for all parts of of the upload. Only the last part is allowed to be of a smaller size. example: 1024 format: int64 type: integer session_endpoints: allOf: - description: A list of endpoints for a chunked upload session. properties: abort: description: The URL for used to abort the session. example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD type: string commit: description: The URL used to commit the file example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit type: string list_parts: description: The URL users to list all parts. example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts type: string log_event: description: The URL used to get the upload log from. example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log type: string status: description: The URL used to get the status of the upload. example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD type: string upload_part: description: The URL to upload parts to example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD type: string title: Session endpoints type: object - description: A list of endpoints for this session. session_expires_at: description: The date and time when this session expires. example: 2012-12-12T10:53:43-08:00 format: date-time type: string total_parts: description: |- The total number of parts expected in this upload session, as determined by the file size and part size. example: 1000 format: int32 type: integer type: description: "`upload_session`" enum: - upload_session example: upload_session type: string title: Upload session type: object x-box-resource-id: upload_session x-box-tag: chunked_uploads UploadUrl: description: The details for the upload session for the file. properties: upload_token: description: An optional access token to use to upload the file example: Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP type: string upload_url: description: |- A URL for an upload session that can be used to upload the file. example: https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234 type: string title: Upload URL type: object x-box-resource-id: upload_url x-box-tag: uploads UploadedPart: description: |- A chunk of a file uploaded as part of an upload session, as returned by some endpoints. properties: part: $ref: "#/components/schemas/UploadPart" title: Uploaded part type: object x-box-resource-id: uploaded_part x-box-tag: chunked_uploads User: allOf: - $ref: "#/components/schemas/User--Mini" - properties: address: description: The user’s address example: 900 Jefferson Ave, Redwood City, CA 94063 maxLength: 255 type: string avatar_url: description: URL of the user’s avatar image example: https://www.box.com/api/avatar/large/181216415 type: string created_at: description: When the user object was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string job_title: description: The user’s job title example: CEO maxLength: 100 type: string language: description: |- The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. example: en type: string max_upload_size: description: The maximum individual file size in bytes the user can have example: 2147483648 format: int64 type: integer modified_at: description: When the user object was last modified example: 2012-12-12T10:53:43-08:00 format: date-time type: string notification_email: description: |- An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. nullable: true properties: email: description: The email address to send the notifications to. example: notifications@example.com type: string is_confirmed: description: Specifies if this email address has been confirmed. example: true type: boolean type: object phone: description: The user’s phone number example: "6509241374" maxLength: 100 type: string space_amount: description: The user’s total available space amount in bytes example: 11345156112 format: int64 type: integer space_used: description: The amount of space in use by the user example: 1237009912 format: int64 type: integer status: description: The user's account status enum: - active - inactive - cannot_delete_edit - cannot_delete_edit_upload example: active type: string timezone: description: The user's timezone example: Africa/Bujumbura format: timezone type: string description: |- A standard representation of a user, as returned from any user API endpoints by default title: User type: object x-box-resource-id: user x-box-variant: standard User--Base: description: |- A mini representation of a user, used when nested within another resource. properties: id: description: The unique identifier for this user example: "11446498" type: string type: description: "`user`" enum: - user example: user nullable: false type: string required: - type title: User (Base) type: object x-box-resource-id: user--base x-box-tag: users x-box-variant: base x-box-variants: - base - mini - standard - full User--Collaborations: allOf: - $ref: "#/components/schemas/User--Base" - properties: login: description: The primary email address of this user. If the collaboration status is `pending`, an empty string is returned. example: ceo@example.com format: email nullable: false type: string name: description: The display name of this user. If the collaboration status is `pending`, an empty string is returned. example: Aaron Levie maxLength: 50 nullable: false type: string description: |- A mini representation of a user, can be returned only when the status is `pending`. required: - name - login title: User (Collaborations) type: object x-box-resource-id: user_collaborations x-box-variant: collaborations User--Full: allOf: - $ref: "#/components/schemas/User" - properties: can_see_managed_users: description: Whether the user can see other enterprise users in their contact list example: true type: boolean enterprise: allOf: - description: A representation of a Box enterprise properties: id: description: The unique identifier for this enterprise. example: "11446498" type: string name: description: The name of the enterprise example: Acme Inc. type: string type: description: "`enterprise`" enum: - enterprise example: enterprise type: string title: Enterprise type: object - description: Representation of the user’s enterprise external_app_user_id: description: |- An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. example: my-user-1234 type: string hostname: description: |- The root (protocol, subdomain, domain) of any links that need to be generated for the user example: https://example.app.box.com/ type: string is_exempt_from_device_limits: description: Whether to exempt the user from Enterprise device limits example: true type: boolean is_exempt_from_login_verification: description: Whether the user must use two-factor authentication example: true type: boolean is_external_collab_restricted: description: |- Whether the user is allowed to collaborate with users outside their enterprise example: true type: boolean is_platform_access_only: description: Whether the user is an App User example: true type: boolean is_sync_enabled: description: Whether the user can use Box Sync example: true type: boolean my_tags: description: |- Tags for all files and folders owned by the user. Values returned will only contain tags that were set by the requester. example: - important items: type: string type: array role: description: The user’s enterprise role enum: - admin - coadmin - user example: admin type: string tracking_codes: description: |- Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. items: $ref: "#/components/schemas/TrackingCode" type: array description: |- A full representation of a user, as can be returned from any user API endpoint. title: User (Full) type: object x-box-resource-id: user--full x-box-variant: full User--Mini: allOf: - $ref: "#/components/schemas/User--Base" - properties: login: description: The primary email address of this user example: ceo@example.com format: email nullable: false type: string name: description: The display name of this user example: Aaron Levie maxLength: 50 nullable: false type: string description: |- A mini representation of a user, as can be returned when nested within other resources. required: - name - login title: User (Mini) type: object x-box-resource-id: user--mini x-box-variant: mini UserAvatar: description: |- A resource holding URLs to the avatar uploaded to a Box application. properties: pic_urls: description: Represents an object with user avatar URLs. properties: large: description: The location of a large-sized avatar. example: https://app.box.com/index.php?rm=pic_storage_auth&pic=euks pac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw jtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc gSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC ao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r type: string preview: description: The location of the avatar preview. example: https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW k-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ 04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl sSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc 9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g type: string small: description: The location of a small-sized avatar. example: https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw type: string type: object title: User avatar type: object x-box-resource-id: user_avatar x-box-tag: avatars Users: allOf: - description: The part of an API response that describes pagination properties: 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 format: int64 type: integer 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 format: int64 type: integer 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. items: description: The order in which a pagination is ordered properties: by: description: The field to order by example: type type: string direction: description: The direction to order by, either ascending or descending enum: - ASC - DESC example: ASC type: string type: object type: array 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 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/User" type: array description: A list of users. title: Users type: object x-box-resource-id: users x-box-tag: users Watermark: description: |- A watermark is a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over a file's content properties: watermark: properties: created_at: description: When this watermark was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_at: description: When this task was modified example: 2012-12-12T10:53:43-08:00 format: date-time type: string type: object title: Watermark type: object x-box-resource-id: watermark x-box-tag: file_watermarks WebLink: allOf: - $ref: "#/components/schemas/WebLink--Mini" - properties: created_at: description: When this file was created on Box’s servers. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created this web link description: description: |- The description accompanying the web link. This is visible within the Box web application. example: Example page type: string item_status: 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 enum: - active - trashed - deleted example: active type: string modified_at: description: |- When this file was last updated on the Box servers. example: 2012-12-12T10:53:43-08:00 format: date-time type: string 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 parent: allOf: - $ref: "#/components/schemas/Folder--Mini" - description: The parent object the web link belongs to path_collection: allOf: - description: A list of parent folders for an item. properties: entries: description: The parent folders for this item items: $ref: "#/components/schemas/Folder--Mini" nullable: false type: array total_count: description: The number of folders in this list. example: 1 format: int64 nullable: false type: integer required: - total_count - entries title: Path collection type: object - description: |- The tree of folders that this web link is contained in, starting at the root. - nullable: false purged_at: description: When this file will be permanently deleted. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string shared_link: allOf: - 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. properties: access: description: |- The access level for this shared link. * `open` - provides access to this item to anyone with this link * `company` - only provides access to this item to people the same company * `collaborators` - only provides access to this item to people who are collaborators on this item If this field is omitted when creating the shared link, the access level will be set to the default access level specified by the enterprise admin. enum: - open - company - collaborators example: open nullable: false type: string download_count: description: The number of times this item has been downloaded. example: 3 nullable: false type: integer download_url: 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 format: url nullable: true type: string x-box-premium-feature: true effective_access: 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 type: string effective_permission: 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 type: string is_password_enabled: description: Defines if the shared link requires a password to access the item. example: true nullable: false type: boolean permissions: 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. properties: can_download: 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`. example: true nullable: false type: boolean can_edit: 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`. example: false nullable: false type: boolean can_preview: 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. example: true nullable: false type: boolean required: - can_download - can_preview - can_edit type: object preview_count: description: The number of times this item has been previewed. example: 3 nullable: false type: integer unshared_at: 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 format: date-time nullable: true type: string 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 format: url nullable: false type: string vanity_name: description: The custom name of a shared link, as used in the `vanity_url` field. example: my_url nullable: true type: string vanity_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/ format: url nullable: true type: string required: - url - accessed - effective_access - effective_permission - is_password_enabled - download_count - preview_count title: Shared link type: object - description: |- The shared link object for this item. Will be `null` if no shared link has been created. - nullable: true trashed_at: description: When this file was moved to the trash. example: 2012-12-12T10:53:43-08:00 format: date-time nullable: true type: string 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. title: Web link type: object x-box-resource-id: web_link x-box-variant: standard WebLink--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. properties: etag: description: |- The entity tag of this web link. Used with `If-Match` headers. example: "1" type: string id: description: The unique identifier for this web link example: "11446498" type: string type: description: "`web_link`" enum: - web_link example: web_link type: string required: - id - type title: Web link (Base) type: object x-box-resource-id: web_link--base x-box-tag: web_links x-box-variant: base x-box-variants: - base - mini - standard WebLink--Mini: allOf: - $ref: "#/components/schemas/WebLink--Base" - properties: name: description: The name of the web link example: My Bookmark type: string sequence_id: allOf: - 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. example: "3" nullable: false type: string - nullable: false url: description: The URL this web link points to example: https://www.example.com/example/1234 type: string 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. title: Web link (Mini) type: object x-box-resource-id: web_link--mini x-box-variant: mini Webhook: allOf: - $ref: "#/components/schemas/Webhook--Mini" - properties: address: description: The URL that is notified by this webhook example: https://example.com/webhooks type: string created_at: description: |- A timestamp identifying the time that the webhook was created. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user who created the webhook triggers: description: |- An array of event names that this webhook is to be triggered for example: - FILE.UPLOADED items: description: The event name that triggered this webhook enum: - FILE.UPLOADED - FILE.PREVIEWED - FILE.DOWNLOADED - FILE.TRASHED - FILE.DELETED - FILE.RESTORED - FILE.COPIED - FILE.MOVED - FILE.LOCKED - FILE.UNLOCKED - FILE.RENAMED - COMMENT.CREATED - COMMENT.UPDATED - COMMENT.DELETED - TASK_ASSIGNMENT.CREATED - TASK_ASSIGNMENT.UPDATED - METADATA_INSTANCE.CREATED - METADATA_INSTANCE.UPDATED - METADATA_INSTANCE.DELETED - FOLDER.CREATED - FOLDER.RENAMED - FOLDER.DOWNLOADED - FOLDER.RESTORED - FOLDER.DELETED - FOLDER.COPIED - FOLDER.MOVED - FOLDER.TRASHED - WEBHOOK.DELETED - COLLABORATION.CREATED - COLLABORATION.ACCEPTED - COLLABORATION.REJECTED - COLLABORATION.REMOVED - COLLABORATION.UPDATED - SHARED_LINK.DELETED - SHARED_LINK.CREATED - SHARED_LINK.UPDATED - SIGN_REQUEST.COMPLETED - SIGN_REQUEST.DECLINED - SIGN_REQUEST.EXPIRED example: FILE.UPLOADED title: Webhook Trigger type: string type: array description: Represents a configured webhook. title: Webhook type: object x-box-resource-id: webhook x-box-tag: webhooks x-box-variant: standard Webhook--Mini: description: Represents a configured webhook. properties: id: description: The unique identifier for this webhook. example: "11446498" type: string target: description: The item that will trigger the webhook properties: id: description: The ID of the item to trigger a webhook example: "1231232" type: string type: description: The type of item to trigger a webhook enum: - file - folder example: file type: string type: object type: description: "`webhook`" enum: - webhook example: webhook type: string title: Webhook (Mini) type: object x-box-resource-id: webhook--mini x-box-tag: webhooks x-box-variant: mini x-box-variants: - mini - standard WebhookInvocation: description: The event that is sent to a webhook address when an event happens. properties: created_at: description: |- A timestamp identifying the time that the webhook event was triggered. example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Mini" - description: The user that triggered this event id: description: The unique identifier for this webhook invocation example: "11446498" type: string source: allOf: - oneOf: - $ref: "#/components/schemas/File" - $ref: "#/components/schemas/Folder" - description: The item that caused the event to trigger trigger: allOf: - description: The event name that triggered this webhook enum: - FILE.UPLOADED - FILE.PREVIEWED - FILE.DOWNLOADED - FILE.TRASHED - FILE.DELETED - FILE.RESTORED - FILE.COPIED - FILE.MOVED - FILE.LOCKED - FILE.UNLOCKED - FILE.RENAMED - COMMENT.CREATED - COMMENT.UPDATED - COMMENT.DELETED - TASK_ASSIGNMENT.CREATED - TASK_ASSIGNMENT.UPDATED - METADATA_INSTANCE.CREATED - METADATA_INSTANCE.UPDATED - METADATA_INSTANCE.DELETED - FOLDER.CREATED - FOLDER.RENAMED - FOLDER.DOWNLOADED - FOLDER.RESTORED - FOLDER.DELETED - FOLDER.COPIED - FOLDER.MOVED - FOLDER.TRASHED - WEBHOOK.DELETED - COLLABORATION.CREATED - COLLABORATION.ACCEPTED - COLLABORATION.REJECTED - COLLABORATION.REMOVED - COLLABORATION.UPDATED - SHARED_LINK.DELETED - SHARED_LINK.CREATED - SHARED_LINK.UPDATED - SIGN_REQUEST.COMPLETED - SIGN_REQUEST.DECLINED - SIGN_REQUEST.EXPIRED example: FILE.UPLOADED title: Webhook Trigger type: string - description: The event name that triggered this webhook type: description: "`webhook_event`" enum: - webhook_event example: webhook_event type: string webhook: allOf: - $ref: "#/components/schemas/Webhook" - description: The webhook object that triggered this event title: Webhook (V2) payload type: object x-box-resource-id: webhook_invocation x-box-tag: webhooks Webhooks: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/Webhook--Mini" type: array description: A list of webhooks. title: Webhooks type: object x-box-resource-id: webhooks x-box-tag: webhooks Workflow: allOf: - $ref: "#/components/schemas/Workflow--Mini" - properties: flows: description: A list of flows assigned to a workflow. items: description: |- A step in a Box Relay Workflow. Each flow contains a `Trigger` and a collection of Outcomes to perform once the conditions of a `Trigger` are met properties: created_at: description: When this flow was created example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who created this flow id: description: The identifier of the flow example: "12345" type: string outcomes: allOf: - items: description: List of outcomes to perform once the conditions of trigger are met. properties: action_type: allOf: - description: The type of outcome enum: - add_metadata - assign_task - copy_file - copy_folder - create_folder - delete_file - delete_folder - lock_file - move_file - move_folder - remove_watermark_file - rename_folder - restore_folder - share_file - share_folder - unlock_file - upload_file - wait_for_task - watermark_file - go_back_to_step - apply_file_classification - apply_folder_classification - send_notification example: assign_task title: Action Type type: string - description: The type of outcome id: description: The identifier of the outcome example: "12345" type: string if_rejected: description: |- If `action_type` is `assign_task` and the task is rejected, returns a list of outcomes to complete items: properties: action_type: allOf: - description: The type of outcome enum: - add_metadata - assign_task - copy_file - copy_folder - create_folder - delete_file - delete_folder - lock_file - move_file - move_folder - remove_watermark_file - rename_folder - restore_folder - share_file - share_folder - unlock_file - upload_file - wait_for_task - watermark_file - go_back_to_step - apply_file_classification - apply_folder_classification - send_notification example: assign_task title: Action Type type: string - description: The type of outcome id: description: The identifier of the outcome example: "12345" type: string name: description: The name of the outcome example: Approval Rejection Outcome type: string type: description: The outcomes resource type enum: - outcome example: outcome type: string type: object type: array name: description: The name of the outcome example: Task Approval Outcome type: string type: description: The outcomes resource type enum: - outcome example: outcome type: string type: object type: array - description: Actions that are completed once the flow is triggered trigger: allOf: - properties: scope: description: List of trigger scopes items: description: Object that describes where and how a Trigger condition is met properties: object: description: The object the `ref` points to properties: id: description: The id of the object example: "12345" type: string type: description: The type of the object enum: - folder example: folder type: string type: object ref: description: Indicates the path of the condition value to check example: /event/source/parameters/folder type: string type: description: The trigger scope's resource type enum: - trigger_scope example: trigger_scope type: string type: object type: array trigger_type: description: The type of trigger selected for this flow enum: - WORKFLOW_MANUAL_START example: WORKFLOW_MANUAL_START type: string type: description: The trigger's resource type enum: - trigger example: trigger type: string type: object - description: Trigger that initiates flow type: description: The flow's resource type enum: - flow example: flow type: string type: object type: array description: |- Box Relay Workflows are objects that represent a named collection of flows. Your application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource. title: Workflow type: object x-box-resource-id: workflow x-box-variant: standard Workflow--Full: allOf: - $ref: "#/components/schemas/Workflow" - properties: created_at: description: The date and time when the workflow was created on Box example: 2012-12-12T10:53:43-08:00 format: date-time type: string created_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who created this workflow modified_at: description: The date and time when the workflow was last updated on Box example: 2012-12-12T10:53:43-08:00 format: date-time type: string modified_by: allOf: - $ref: "#/components/schemas/User--Base" - description: The user who last modified this workflow description: |- Box Relay Workflows are objects that represent a named collection of flows. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource. title: Workflow (Full) type: object x-box-resource-id: workflow--full x-box-variant: full Workflow--Mini: description: |- Box Relay Workflows are objects that represent a named collection of flows. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource. properties: description: description: The description for a workflow. example: This workflow sets off a new hire approval flow type: string id: description: The unique identifier for the workflow example: "11446498" type: string is_enabled: description: Specifies if this workflow is enabled example: true type: boolean name: description: The name of the workflow example: New Hire Workflow type: string type: description: "`workflow`" enum: - workflow example: workflow type: string title: Workflow (Mini) type: object x-box-resource-id: workflow--mini x-box-tag: workflows x-box-variant: mini x-box-variants: - mini - standard - full Workflows: allOf: - description: |- The part of an API response that describes marker based pagination properties: 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 format: int64 type: integer next_marker: description: The marker for the start of the next page of results. example: 3000 format: int64 type: integer prev_marker: description: The marker for the start of the previous page of results. example: 1000 format: int64 type: integer type: object - properties: entries: items: $ref: "#/components/schemas/Workflow" type: array description: |- A list of workflows. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource. title: Workflows type: object x-box-resource-id: workflows x-box-tag: workflows ZipDownload: description: |- Represents a successful request to create a `zip` archive of a list of files and folders. example: download_url: https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content expires_at: 2020-07-22T11:26:08Z name_conflicts: - - download_name: 3aa6a7.pdf id: "12345" original_name: Report.pdf type: file - download_name: 5d53f2.pdf id: "34325" original_name: Report.pdf type: file status_url: https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status properties: download_url: description: |- The URL that can be used to download the `zip` archive. A `Get` request to this URL will start streaming the items requested. By default, this URL is only valid for a few seconds, until the `expires_at` time, unless a download is started after which it is valid for the duration of the download. It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is. example: https://dl.boxcloud.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/content type: string expires_at: description: |- The time and date when this archive will expire. After this time the `status_url` and `download_url` will return an error. By default, these URLs are only valid for a few seconds, unless a download is started after which the `download_url` is valid for the duration of the download, and the `status_url` is valid for 12 hours from the start of the download. example: 2019-08-29T23:59:00-07:00 format: date-time type: string name_conflicts: description: |- A list of conflicts that occurred when trying to create the archive. This would occur when multiple items have been requested with the same name. To solve these conflicts, the API will automatically rename an item and return a mapping between the original item's name and its new name. For every conflict, both files will be renamed and therefore this list will always be a multiple of 2. items: description: |- An individual conflict that occurred when trying to create the archive. This includes an array of 2 objects, each containing the original name and the renamed filename of a file or folder for which the names conflicted. items: description: A file or folder for which a conflict was encountered, This object provides the type and identifier of the original item, as well as a mapping between its original name and it's new name as it will appear in the archive. properties: download_name: description: |- The new name of this item as it will appear in the downloaded `zip` archive. example: 3aa6a7.pdf type: string id: description: The identifier of the item example: "12345" type: string original_name: description: The original name of this item example: Report.pdf type: string type: description: The type of this item enum: - file - folder example: file type: string type: object type: array type: array status_url: description: |- The URL that can be used to get the status of the `zip` archive being downloaded. A `Get` request to this URL will return the number of files in the archive as well as the number of items already downloaded or skipped. By default, this URL is only valid for a few seconds, until the `expires_at` time, unless a download is started after which the URL is valid for 12 hours from the start of the download. It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is. example: https://api.box.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/status type: string title: Zip download type: object x-box-reference-category: zip_downloads x-box-resource-id: zip_download x-box-tag: zip_downloads ZipDownloadRequest: description: A request to create a `zip` archive to download properties: download_file_name: description: |- The optional name of the `zip` archive. This name will be appended by the `.zip` file extension, for example `January Financials.zip`. example: January Financials type: string items: description: |- A list of items to add to the `zip` archive. These can be folders or files. items: description: An item to add to the `zip` archive. This can be a file or a folder. properties: id: description: |- The identifier of the item to add to the archive. When this item is a folder then this can not be the root folder with ID `0`. example: "12345" type: string type: description: The type of the item to add to the archive. enum: - file - folder. example: file type: string required: - type - id type: object type: array required: - items title: Create a `zip` archive type: object ZipDownloadStatus: description: The status of a `zip` archive being downloaded. properties: downloaded_file_count: description: The number of files that have already been downloaded. example: 10 minimum: 0 type: integer skipped_file_count: description: |- The number of files that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded. example: 5 minimum: 0 type: integer skipped_folder_count: description: |- The number of folders that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded. example: 5 minimum: 0 type: integer state: default: in_progress description: The state of the archive being downloaded. enum: - in_progress - failed - success example: success type: string total_file_count: description: The total number of files in the archive. example: 20 maximum: 10000 minimum: 0 type: integer title: Zip download status type: object x-box-reference-category: zip_downloads x-box-resource-id: zip_download_status x-box-tag: zip_downloads securitySchemes: OAuth2Security: flows: authorizationCode: authorizationUrl: https://account.box.com/api/oauth2/authorize scopes: manage_app_users: Provision and manage app users manage_data_retention: Manage data retention polices manage_enterprise_properties: Manage enterprise properties manage_groups: Manage an enterprise's groups manage_legal_hold: Manage Legal Holds manage_managed_users: Provision and manage managed users manage_webhook: Create webhooks programmatically through the API root_readonly: Read all files and folders stored in Box root_readwrite: Read and write all files and folders stored in Box tokenUrl: https://api.box.com/oauth2/token type: oauth2