{ "openapi": "3.0.2", "info": { "title": "Box Platform API", "description": "[Box Platform](https://developer.box.com) 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.", "termsOfService": "https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9", "contact": { "name": "Box, Inc", "url": "https://developer.box.com", "email": "devrel@box.com" }, "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "2024.0", "x-box-commit-hash": "8dd502b50d" }, "servers": [ { "url": "https://api.box.com/2.0", "description": "Box Platform API server." } ], "paths": { "/authorize": { "get": { "operationId": "get_authorize", "summary": "Authorize user", "description": "Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf.\n\nThis 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.", "parameters": [ { "name": "response_type", "in": "query", "description": "The type of response we'd like to receive.", "required": true, "schema": { "type": "string", "format": "token", "enum": [ "code" ] }, "example": "code" }, { "name": "client_id", "in": "query", "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.", "required": true, "schema": { "type": "string" }, "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, { "name": "redirect_uri", "in": "query", "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.", "required": false, "schema": { "type": "string", "format": "url" }, "example": "http://example.com/auth/callback" }, { "name": "state", "in": "query", "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.", "required": false, "schema": { "type": "string" }, "example": "my_state" }, { "name": "scope", "in": "query", "description": "A space-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.", "required": false, "schema": { "type": "string" }, "example": "admin_readwrite" } ], "responses": { "200": { "description": "Does not return any data, but rather should be used in the browser.", "content": { "text/html": { "schema": { "type": "string", "format": "html" } } } }, "default": { "description": "Does not return any data, but rather should be used in the browser.", "content": { "text/html": { "schema": { "type": "string", "format": "html" } } } } }, "x-box-tag": "authorization", "security": [], "servers": [ { "url": "https://account.box.com/api/oauth2", "description": "Server for client-side authentication." } ], "tags": [ "Authorization" ], "x-codeSamples": [ { "lang": "curl", "label": "Authorize user", "source": "curl -i -X GET \"https://account.box.com/api/oauth2/authorize?response_type=code&client_id=ly1nj6n11vionaie65emwzk575hnnmrk&redirect_uri=http://example.com/auth/callback\"" }, { "lang": "dotnet", "label": "Authorize user", "source": "using Box.Sdk.Gen;\n\nvar config = new OAuthConfig(clientId: \"YOUR_CLIENT_ID\", clientSecret: \"YOUR_CLIENT_SECRET\");\nvar auth = new BoxOAuth(config: config);\n\n// the URL to redirect the user to\nvar authorizeUrl = auth.GetAuthorizeUrl();" }, { "lang": "swift", "label": "Authorize user", "source": "do {\n // Initialize configuration with required clientId and clientSecret\n let config = OAuthConfig(clientId: \"<>\", clientSecret: \"<>\")\n // Initialize BoxOAuth with configuration\n let oauth = BoxOAuth(config: config)\n // Run login flow which opens a secure web view,\n // where users enter their login credentials to obtain an authorization code,\n // which is then exchanged for an access token.\n try await oauth.runLoginFlow(options: .init(), context: self)\n // Initialize BoxClient with already authorized OAuth\n let client = BoxClient(auth: oauth)\n\n // Use client to make API calls\n let folder = try await client.folders.getFolderById(folderId: \"<>\")\n} catch {\n print(\"An error occurred: \\(error)\")\n}" }, { "lang": "java", "label": "Authorize user", "source": "OAuthConfig oauthConfig = new OAuthConfig(\"CLIENT_ID\", \"CLIENT_SECRET\");\nBoxOAuth oauth = new BoxOAuth(oauthConfig);\nString authorizationUrl = oauth.getAuthorizeUrl();" }, { "lang": "node", "label": "Authorize user", "source": "import { BoxOAuth, OAuthConfig } from 'box-node-sdk/box';\n\nconst config = new OAuthConfig({\n clientId: 'OAUTH_CLIENT_ID',\n clientSecret: 'OAUTH_CLIENT_SECRET',\n});\nconst oauth = new BoxOAuth({ config: config });\n\n// the URL to redirect the user to\nvar authorize_url = oauth.getAuthorizeUrl();" }, { "lang": "python", "label": "Authorize user", "source": "from box_sdk_gen import BoxOAuth, OAuthConfig\n\nauth = BoxOAuth(\n OAuthConfig(client_id=\"YOUR_CLIENT_ID\", client_secret=\"YOUR_CLIENT_SECRET\")\n)\nauth_url = auth.get_authorize_url()" } ] } }, "/oauth2/token": { "post": { "operationId": "post_oauth2_token", "summary": "Request access token", "description": "Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion.\n\nAn 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](/reference/get-authorize) endpoint and Box will send you an authorization code.\n\nYou 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.", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PostOAuth2Token" } } } }, "responses": { "200": { "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 `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } } }, "400": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } }, "default": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } } }, "x-box-tag": "authorization", "security": [], "servers": [ { "url": "https://api.box.com", "description": "Server for server-side authentication." } ], "tags": [ "Authorization" ], "x-codeSamples": [ { "lang": "curl", "label": "Request access token", "source": "curl -i -X POST \"https://api.box.com/oauth2/token\" \\\n -H \"content-type: application/x-www-form-urlencoded\" \\\n -d \"client_id=[CLIENT_ID]\" \\\n -d \"client_secret=[CLIENT_SECRET]\" \\\n -d \"code=[CODE]\" \\\n -d \"grant_type=authorization_code\"" }, { "lang": "dotnet", "label": "Request access token", "source": "await auth.RetrieveTokenAsync();" }, { "lang": "swift", "label": "Request access token", "source": "try await auth.retrieveToken();" }, { "lang": "java", "label": "Request access token", "source": "auth.retrieveToken();" }, { "lang": "node", "label": "Request access token", "source": "await auth.retrieveToken();" }, { "lang": "python", "label": "Request access token", "source": "auth.retrieve_token()" } ] } }, "/oauth2/token#refresh": { "post": { "operationId": "post_oauth2_token#refresh", "summary": "Refresh access token", "description": "Refresh an Access Token using its client ID, secret, and refresh token.", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PostOAuth2Token--RefreshAccessToken" } } } }, "responses": { "200": { "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 `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } } }, "400": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } }, "default": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } } }, "x-box-tag": "authorization", "security": [], "servers": [ { "url": "https://api.box.com", "description": "Server for server-side authentication." } ], "tags": [ "Authorization" ], "x-box-is-variation": true, "x-codeSamples": [ { "lang": "curl", "label": "Refresh access token", "source": "curl -i -X POST \"https://api.box.com/oauth2/token\" \\\n -H \"content-type: application/x-www-form-urlencoded\" \\\n -d \"client_id=[CLIENT_ID]\" \\\n -d \"client_secret=[CLIENT_SECRET]\" \\\n -d \"refresh_token=[REFRESH_TOKEN]\" \\\n -d \"grant_type=refresh_token\"" }, { "lang": "dotnet", "label": "Refresh access token", "source": "await auth.RefreshTokenAsync();" }, { "lang": "swift", "label": "Refresh access token", "source": "try await auth.refreshToken();" }, { "lang": "java", "label": "Refresh access token", "source": "auth.refreshToken();" }, { "lang": "node", "label": "Refresh access token", "source": "await auth.refreshToken();" }, { "lang": "python", "label": "Refresh access token", "source": "auth.refresh_token()" } ] } }, "/oauth2/revoke": { "post": { "operationId": "post_oauth2_revoke", "summary": "Revoke access token", "description": "Revoke an active Access Token, effectively logging a user out that has been previously authenticated.", "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": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } }, "default": { "description": "An authentication error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2Error" } } } } }, "x-box-tag": "authorization", "security": [], "servers": [ { "url": "https://api.box.com", "description": "Server for server-side authentication." } ], "tags": [ "Authorization" ], "x-codeSamples": [ { "lang": "curl", "label": "Revoke access token", "source": "curl -i -X POST \"https://api.box.com/oauth2/revoke\" \\\n -H \"content-type: application/x-www-form-urlencoded\" \\\n -d \"client_id=[CLIENT_ID]\" \\\n -d \"client_secret=[CLIENT_SECRET]\" \\\n -d \"token=[ACCESS_TOKEN]\"" }, { "lang": "dotnet", "label": "Revoke access token", "source": "await auth.RevokeTokenAsync();" }, { "lang": "swift", "label": "Revoke access token", "source": "try await auth.revokeToken()" }, { "lang": "java", "label": "Revoke access token", "source": "auth.revokeToken();\n// client's tokens have been revoked" }, { "lang": "node", "label": "Revoke access token", "source": "await auth.revokeTokens();\n// client's tokens have been revoked" }, { "lang": "python", "label": "Revoke access token", "source": "client.auth.revoke_token()" } ] } }, "/files/{file_id}": { "get": { "operationId": "get_files_id", "summary": "Get file information", "description": "Retrieves the details about a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.\n\nAdditionally 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 `?fields=metadata.enterprise_12345.contractTemplate`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "if-none-match", "in": "header", "description": "Ensures an item is only returned if it has changed.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "boxapi", "in": "header", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been explicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files or folders nested within the item.", "required": false, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" }, { "name": "x-rep-hints", "in": "header", "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.\n\nThe general format for these representations is `X-Rep-Hints: [...]` where `[...]` is one or many hints in the format `[fileType?query]`.\n\nFor example, to request a `png` representation in `32x32` as well as `64x64` pixel dimensions provide the following hints.\n\n`x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]`\n\nAdditionally, a `text` representation is available for all document file types in Box using the `[extracted_text]` representation.\n\n`x-rep-hints: [extracted_text]`.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "[pdf]" } ], "responses": { "200": { "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "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": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "415": { "description": "Returns an error if an action is performed on a file with an incorrect media type.\n\n- `unsupported_media_type` when requesting an `expiring_embed_link` for a file that is not supported by Box Embed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "files", "tags": [ "Files" ], "x-codeSamples": [ { "lang": "curl", "label": "Get file information", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get file information", "source": "await client.Files.GetFileByIdAsync(fileId: uploadedFile.Id, queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {\"is_externally_owned\",\"has_collaborations\"}) });" }, { "lang": "swift", "label": "Get file information", "source": "try await client.files.getFileById(fileId: uploadedFile.id, queryParams: GetFileByIdQueryParams(fields: [\"is_externally_owned\", \"has_collaborations\"]))" }, { "lang": "java", "label": "Get file information", "source": "client.getFiles().getFileById(uploadedFile.getId(), new GetFileByIdQueryParams.Builder().fields(Arrays.asList(\"is_externally_owned\", \"has_collaborations\")).build())" }, { "lang": "node", "label": "Get file information", "source": "await client.files.getFileById(uploadedFile.id, {\n queryParams: {\n fields: ['is_externally_owned', 'has_collaborations'],\n } satisfies GetFileByIdQueryParams,\n} satisfies GetFileByIdOptionalsInput);" }, { "lang": "python", "label": "Get file information", "source": "client.files.get_file_by_id(\n uploaded_file.id, fields=[\"is_externally_owned\", \"has_collaborations\"]\n)" } ] }, "post": { "operationId": "post_files_id", "summary": "Restore file", "description": "Restores a file that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the file to in case the original folder has been deleted.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the file.", "type": "string", "example": "Restored.docx" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item.", "properties": { "id": { "description": "The ID of parent item.", "type": "string", "example": "123" } } }, { "description": "Specifies an optional ID of a folder to restore the file to when the original folder no longer exists.\n\nPlease 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." } ] } } } } } }, "responses": { "201": { "description": "Returns a file object when the file has been restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFileRestored" } } } }, "403": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the file is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there is an file with the same name in the folder the file is being restored to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_files", "tags": [ "Trashed files" ], "x-codeSamples": [ { "lang": "curl", "label": "Restore file", "source": "curl -i -X POST \"https://api.box.com/2.0/files/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Restore file", "source": "await client.TrashedFiles.RestoreFileFromTrashAsync(fileId: file.Id);" }, { "lang": "swift", "label": "Restore file", "source": "try await client.trashedFiles.restoreFileFromTrash(fileId: file.id)" }, { "lang": "java", "label": "Restore file", "source": "client.getTrashedFiles().restoreFileFromTrash(file.getId())" }, { "lang": "node", "label": "Restore file", "source": "await client.trashedFiles.restoreFileFromTrash(file.id);" }, { "lang": "python", "label": "Restore file", "source": "client.trashed_files.restore_file_from_trash(file.id)" } ] }, "put": { "operationId": "put_files_id", "summary": "Update file", "description": "Updates a file. This can be used to rename or move a file, create a shared link, or lock a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional different name for the file. This can be used to rename the file.\n\nFile names must be unique within their parent folder. The name check is case-insensitive, so a file named `New File` cannot be created in a parent folder that already contains a folder named `new file`.", "type": "string", "example": "NewFile.txt" }, "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.", "type": "string", "example": "The latest reports. Automatically updated", "maxLength": 256 }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item.", "properties": { "id": { "description": "The ID of parent item.", "type": "string", "example": "123" }, "user_id": { "description": "The input for `user_id` is optional. Moving to non-root folder is not allowed when `user_id` is present. Parent folder id should be zero when `user_id` is provided.", "type": "string", "example": "12346930" } } }, { "description": "An optional new parent folder for the file. This can be used to move the file to a new folder." } ] }, "shared_link": { "allOf": [ { "description": "Defines a shared link for an item. Set this to `null` to remove the shared link.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link" }, "unshared_at": { "description": "The timestamp at which this shared link will expire. This field can only be set by users with paid accounts.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true } } } } }, { "description": "Defines a shared link for a file. Set this to `null` to remove the shared link." } ], "nullable": true }, "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.\n\nSet this to `null` to remove the lock.", "type": "object", "nullable": true, "properties": { "access": { "description": "The type of this object.", "type": "string", "example": "lock", "enum": [ "lock" ] }, "expires_at": { "description": "Defines the time at which the lock expires.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "is_download_prevented": { "description": "Defines if the file can be downloaded while it is locked.", "type": "boolean", "example": true } }, "required": [ "type" ] }, "disposition_at": { "description": "The retention expiration timestamp for the given file. This date cannot be shortened once set on a file.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "description": "Defines who can download a file.", "type": "object", "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.\n\nThis 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.", "type": "string", "example": "open", "enum": [ "open", "company" ] } } }, "collections": { "description": "An array of collections to make this file a member of. Currently we only support the `favorites` collection.\n\nTo get the ID for a collection, use the [List all collections][1] endpoint.\n\nPassing an empty array `[]` or `null` will remove the file from all collections.\n\n[1]: /reference/get-collections", "type": "array", "items": { "title": "Reference", "description": "The bare basic reference for an object.", "type": "object", "properties": { "id": { "description": "The unique identifier for this object.", "type": "string", "example": "11446498" }, "type": { "description": "The type for this object.", "type": "string", "example": "file" } } }, "nullable": true }, "tags": { "description": "The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags, modify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000 unique tags per enterprise.", "type": "array", "items": { "type": "string" }, "example": [ "approved" ], "maxItems": 100, "minItems": 1 } } } } } }, "responses": { "200": { "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "400": { "description": "Returned when the new retention time > maximum retention length.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.\n\n- `access_denied_insufficient_permissions` returned when the authenticated user does not have access to the destination folder to move the file to.\n- Returned when retention time is shorter or equal to current retention timestamp.\n- Returned when a `file_id` that is not under retention is entered.\n- Returned when a file that is retained but the disposition action is set to `remove_retention`\n- `forbidden_by_policy` is returned if copying a folder is forbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "files", "tags": [ "Files" ], "x-codeSamples": [ { "lang": "curl", "label": "Update file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/12345\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"New name\"\n }'" }, { "lang": "dotnet", "label": "Update file", "source": "await client.Files.UpdateFileByIdAsync(fileId: fileToUpdate.Id, requestBody: new UpdateFileByIdRequestBody() { Name = updatedName, Description = \"Updated description\" });" }, { "lang": "swift", "label": "Update file", "source": "try await client.files.updateFileById(fileId: fileToUpdate.id, requestBody: UpdateFileByIdRequestBody(name: updatedName, description: \"Updated description\"))" }, { "lang": "java", "label": "Update file", "source": "client.getFiles().updateFileById(fileToUpdate.getId(), new UpdateFileByIdRequestBody.Builder().name(updatedName).description(\"Updated description\").build())" }, { "lang": "node", "label": "Update file", "source": "await client.files.updateFileById(fileToUpdate.id, {\n requestBody: {\n name: updatedName,\n description: 'Updated description',\n } satisfies UpdateFileByIdRequestBody,\n} satisfies UpdateFileByIdOptionalsInput);" }, { "lang": "python", "label": "Update file", "source": "client.files.update_file_by_id(\n file_to_update.id, name=updated_name, description=\"Updated description\"\n)" } ] }, "delete": { "operationId": "delete_files_id", "summary": "Delete file", "description": "Deletes a file, either permanently or by moving it to the trash.\n\nThe enterprise settings determine whether the item will be permanently deleted from Box or moved to the trash.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" } ], "responses": { "204": { "description": "Returns an empty response when the file has been successfully deleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found or has already been deleted, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "files", "tags": [ "Files" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete file", "source": "curl -i -X DELETE \"https://api.box.com/2.0/files/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete file", "source": "await client.Files.DeleteFileByIdAsync(fileId: thumbnailFile.Id);" }, { "lang": "swift", "label": "Delete file", "source": "try await client.files.deleteFileById(fileId: thumbnailFile.id)" }, { "lang": "java", "label": "Delete file", "source": "client.getFiles().deleteFileById(thumbnailFile.getId())" }, { "lang": "node", "label": "Delete file", "source": "await client.files.deleteFileById(thumbnailFile.id);" }, { "lang": "python", "label": "Delete file", "source": "client.files.delete_file_by_id(thumbnail_file.id)" } ] } }, "/files/{file_id}/app_item_associations": { "get": { "operationId": "get_files_id_app_item_associations", "summary": "List file app item associations", "description": "**This is a beta feature, which means that its availability might be limited.** Returns all app items the file is associated with. This includes app items associated with ancestors of the file. Assuming the context user has access to the file, the type/ids are revealed even if the context user does not have **View** permission on the app item.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "application_type", "in": "query", "description": "If given, only return app items for this application type.", "required": false, "schema": { "type": "string", "nullable": false }, "example": "hubs" } ], "responses": { "200": { "description": "Returns a collection of app item objects. If there are no app items on this file, an empty collection will be returned. This list includes app items on ancestors of this File.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppItemAssociations" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "app_item_associations", "tags": [ "App item associations" ], "x-codeSamples": [ { "lang": "curl", "label": "List file app item associations", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/app_item_associations\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List file app item associations", "source": "await client.AppItemAssociations.GetFileAppItemAssociationsAsync(fileId: fileId);" }, { "lang": "swift", "label": "List file app item associations", "source": "try await client.appItemAssociations.getFileAppItemAssociations(fileId: fileId)" }, { "lang": "java", "label": "List file app item associations", "source": "client.getAppItemAssociations().getFileAppItemAssociations(fileId)" }, { "lang": "node", "label": "List file app item associations", "source": "await client.appItemAssociations.getFileAppItemAssociations(fileId);" }, { "lang": "python", "label": "List file app item associations", "source": "client.app_item_associations.get_file_app_item_associations(file_id)" } ] } }, "/files/{file_id}/content": { "get": { "operationId": "get_files_id_content", "summary": "Download file", "description": "Returns the contents of a file in binary format.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "range", "in": "header", "description": "The byte range of the content to download.\n\nThe format `bytes={start_byte}-{end_byte}` can be used to specify what section of the file to download.", "required": false, "schema": { "type": "string" }, "example": "bytes=0-1024" }, { "name": "boxapi", "in": "header", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been explicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files or folders nested within the item.", "required": false, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" }, { "name": "version", "in": "query", "description": "The file version to download.", "required": false, "schema": { "type": "string" }, "example": "4" }, { "name": "access_token", "in": "query", "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.", "required": false, "schema": { "type": "string" }, "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" } ], "responses": { "200": { "description": "Returns the requested file if the client has the **follow redirects** setting enabled to automatically follow HTTP `3xx` responses as redirects. If not, the request will return `302` instead. For details, see the [download file guide](/guides/downloads/file#download-url).", "content": { "application/octet-stream": { "schema": { "description": "The binary content of the file.", "type": "string", "format": "binary" } } } }, "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.\n\nThis 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 for download the response will include a `Location` header for the file on `dl.boxcloud.com`.\n\nThe `dl.boxcloud.com` URL is not persistent and clients will need to follow the redirect to actually download the file.", "headers": { "Location": { "description": "A pointer to the download URL.", "schema": { "type": "string", "format": "url" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "downloads", "tags": [ "Downloads" ], "x-codeSamples": [ { "lang": "curl", "label": "Download file", "source": "curl -i -L -X GET \"https://api.box.com/2.0/files/12345/content\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Download file", "source": "await client.Downloads.DownloadFileAsync(fileId: uploadedFile.Id);" }, { "lang": "swift", "label": "Download file", "source": "let downloadsDirectoryURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!\nlet destinationURL = downloadsDirectoryURL.appendingPathComponent(\"file.txt\")\n\nlet url = try await client.downloads.downloadFile(fileId: file.id, downloadDestinationURL: destinationURL)\n\nif let fileContent = try? String(contentsOf: url, encoding: .utf8) {\n print(\"The content of the file: \\(fileContent)\")\n}" }, { "lang": "java", "label": "Download file", "source": "client.getDownloads().downloadFile(uploadedFile.getId())" }, { "lang": "node", "label": "Download file", "source": "const fs = require('fs');\n\nconst fileContent = await client.downloads.downloadFile('123456789');\nconst fileWriteStream = fs.createWriteStream('file.pdf');\nfileContent.pipe(fileWriteStream);" }, { "lang": "python", "label": "Download file", "source": "client.downloads.download_file(uploaded_file.id)" } ] }, "post": { "operationId": "post_files_id_content", "summary": "Upload file version", "description": "Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs.\n\nThe `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.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "content-md5", "in": "header", "description": "An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.", "required": false, "schema": { "type": "string" }, "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "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.\n\n\n\nThe `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.\n\n", "type": "object", "properties": { "name": { "description": "An optional new name for the file. If specified, the file will be renamed when the new version is uploaded.", "type": "string", "example": "Photo 2.0.png" }, "content_modified_at": { "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "required": [ "name" ] }, "file": { "description": "The content of the file to upload to Box.\n\n\n\nThe `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.\n\n", "type": "string", "format": "binary" } }, "required": [ "attributes", "file" ] } } } }, "responses": { "200": { "description": "Returns the new file object in a list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Files" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "uploads", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads." } ], "tags": [ "Uploads" ], "x-codeSamples": [ { "lang": "curl", "label": "Upload file version", "source": "curl -i -X POST \"https://upload.box.com/api/2.0/files/12345/content\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: multipart/form-data\" \\\n -F attributes='{\"name\":\"Contract.pdf\", \"parent\":{\"id\":\"11446498\"}}' \\\n -F file=@" }, { "lang": "dotnet", "label": "Upload file version", "source": "await client.Uploads.UploadFileVersionAsync(fileId: uploadedFile.Id, requestBody: new UploadFileVersionRequestBody(attributes: new UploadFileVersionRequestBodyAttributesField(name: newFileVersionName), file: newFileContentStream));" }, { "lang": "java", "label": "Upload file version", "source": "client.getUploads().uploadFileVersion(uploadedFile.getId(), new UploadFileVersionRequestBody(new UploadFileVersionRequestBodyAttributesField(newFileVersionName), newFileContentStream))" }, { "lang": "node", "label": "Upload file version", "source": "await client.uploads.uploadFileVersion(file.id, {\n attributes: {\n name: file.name!,\n } satisfies UploadFileVersionRequestBodyAttributesField,\n file: generateByteStream(20),\n} satisfies UploadFileVersionRequestBody);" }, { "lang": "python", "label": "Upload file version", "source": "client.uploads.upload_file_version(\n uploaded_file.id,\n UploadFileVersionAttributes(name=new_file_version_name),\n new_file_content_stream,\n)" } ] } }, "/files/content": { "options": { "operationId": "options_files_content", "summary": "Preflight check before upload", "tags": [ "Files" ], "x-box-tag": "uploads", "description": "Performs a check to verify that a file will be accepted by Box before you upload the entire file.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name for the file.", "type": "string", "example": "File.mp4" }, "size": { "description": "The size of the file in bytes.", "type": "integer", "format": "int32", "example": 1024 }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item.", "properties": { "id": { "description": "The ID of parent item.", "type": "string", "example": "123" } } }, { "description": "The parent folder to upload the file to." } ] } } } } } }, "responses": { "200": { "description": "If the check passed, the response will include a session URL that can be used to upload the file to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadUrl" } } } }, "409": { "description": "If the check did not pass, the response will include some details on why it did not pass.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Preflight check before upload", "source": "curl -i -X OPTIONS \"https://api.box.com/2.0/files/content\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\"name\":\"Contract.pdf\", \"parent\":{\"id\":\"11446498\"}}'" }, { "lang": "dotnet", "label": "Preflight check before upload", "source": "await client.Uploads.PreflightFileUploadCheckAsync(requestBody: new PreflightFileUploadCheckRequestBody() { Name = newFileName, Size = 1024 * 1024, Parent = new PreflightFileUploadCheckRequestBodyParentField() { Id = \"0\" } });" }, { "lang": "java", "label": "Preflight check before upload", "source": "client.getUploads().preflightFileUploadCheck(new PreflightFileUploadCheckRequestBody.Builder().name(newFileName).size(1024 * 1024).parent(new PreflightFileUploadCheckRequestBodyParentField.Builder().id(\"0\").build()).build())" }, { "lang": "node", "label": "Preflight check before upload", "source": "await client.uploads.preflightFileUploadCheck({\n name: newFileName,\n size: 1024 * 1024,\n parent: { id: '0' } satisfies PreflightFileUploadCheckRequestBodyParentField,\n} satisfies PreflightFileUploadCheckRequestBody);" }, { "lang": "python", "label": "Preflight check before upload", "source": "client.uploads.preflight_file_upload_check(\n name=new_file_name, size=1024 * 1024, parent=PreflightFileUploadCheckParent(id=\"0\")\n)" } ] }, "post": { "operationId": "post_files_content", "summary": "Upload file", "description": "Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs.\n\nThe `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.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "content-md5", "in": "header", "description": "An optional header containing the SHA1 hash of the file to ensure that the file was not corrupted in transit.", "required": false, "schema": { "type": "string" }, "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "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.\n\n\n\nThe `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.\n\n", "type": "object", "properties": { "name": { "description": "The name of the file.\n\nFile names must be unique within their parent folder. The name check is case-insensitive, so a file named `New File` cannot be created in a parent folder that already contains a folder named `new file`.", "type": "string", "example": "Photo.png" }, "parent": { "description": "The parent folder to upload the file to.", "type": "object", "properties": { "id": { "description": "The id of the parent folder. Use `0` for the user's root folder.", "type": "string", "example": "124132" } }, "required": [ "id" ] }, "content_created_at": { "description": "Defines the time the file was originally created at.\n\nIf not set, the upload time will be used.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "content_modified_at": { "description": "Defines the time the file was last modified at.\n\nIf not set, the upload time will be used.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "required": [ "name", "parent" ] }, "file": { "description": "The content of the file to upload to Box.\n\n\n\nThe `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.\n\n", "type": "string", "format": "binary" } }, "required": [ "attributes", "file" ] } } } }, "responses": { "201": { "description": "Returns the new file object in a list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Files" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `bad_request` when a parameter is missing or incorrect.\n- `item_name_too_long` when the folder name is too long.\n- `item_name_invalid` when the folder name contains non-valid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the parent folder does not exist or if the user is not authorized to access the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the file already exists, or the account has run out of disk space.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "uploads", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads." } ], "tags": [ "Uploads" ], "x-codeSamples": [ { "lang": "curl", "label": "Upload file", "source": "curl -i -X POST \"https://upload.box.com/api/2.0/files/content\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: multipart/form-data\" \\\n -F attributes='{\"name\":\"Contract.pdf\", \"parent\":{\"id\":\"11446498\"}}' \\\n -F file=@" }, { "lang": "dotnet", "label": "Upload file", "source": "await client.Uploads.UploadFileAsync(requestBody: new UploadFileRequestBody(attributes: new UploadFileRequestBodyAttributesField(name: newFileName, parent: new UploadFileRequestBodyAttributesParentField(id: \"0\")), file: fileContentStream));" }, { "lang": "swift", "label": "Upload file", "source": "// Create InputStream for a file based on URL\nguard let fileStream = InputStream(url: URL(string: \"\")!) else {\n fatalError(\"Could not read a file\")\n}\n\n// Create a request body with the required parameters\nlet requestBody = UploadFileRequestBody(\n attributes: UploadFileRequestBodyAttributesField(\n name: \"filename.txt\",\n parent: UploadFileRequestBodyAttributesParentField(id: \"0\")\n ),\n file: fileStream\n)\n\n// Call uploadFile method\nlet files = try await client.uploads.uploadFile(requestBody: requestBody)\n\n// Print some data from the reponse\nif let file = files.entries?[0] {\n print(\"File uploaded with id \\(file.id), name \\(file.name!)\")\n}" }, { "lang": "java", "label": "Upload file", "source": "client.getUploads().uploadFile(new UploadFileRequestBody(new UploadFileRequestBodyAttributesField(newFileName, new UploadFileRequestBodyAttributesParentField(\"0\")), fileContentStream))" }, { "lang": "node", "label": "Upload file", "source": "const fs = require('fs');\n\nconst attrs = { name: 'filename.txt', parent: { id: '0' } };\nconst body = {\n attributes: attrs,\n file: fs.createReadStream('filename.txt'),\n};\nconst files = await client.uploads.uploadFile(body);\nconst file = files.entries[0];\nconsole.log(`File uploaded with id ${file.id}, name ${file.name}`);" }, { "lang": "python", "label": "Upload file", "source": "client.uploads.upload_file(\n UploadFileAttributes(\n name=new_file_name, parent=UploadFileAttributesParentField(id=\"0\")\n ),\n file_content_stream,\n)" } ] } }, "/files/upload_sessions": { "post": { "operationId": "post_files_upload_sessions", "summary": "Create upload session", "description": "Creates an upload session for a new file.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "description": "The ID of the folder to upload the new file to.", "type": "string", "example": "0" }, "file_size": { "description": "The total number of bytes of the file to be uploaded.", "type": "integer", "format": "int64", "example": 104857600 }, "file_name": { "description": "The name of new file.", "type": "string", "example": "Project.mov" } }, "required": [ "folder_id", "file_size", "file_name" ] } } } }, "responses": { "201": { "description": "Returns a new upload session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `missing_destination`: No `folder_id` was provided.\n- `invalid_folder_id`: `folder_id` is not valid.\n- `item_name_invalid`: `file_name` is not valid.\n- `missing_file_size`: `file_size` was not provided.\n- `invalid_file_size`: `file_size` was not a valid number.\n- `file_size_too_small`: `file_size` is below minimum file size for uploads via this API.\n- `missing_file_name`: `file_name` was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the operation is not allowed for some reason.\n\n- `storage_limit_exceeded`: Account storage limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the parent folder could not be found, or the authenticated user does not have access to it.\n\n- `invalid_parameter`: The `folder_id` value represents a folder that the user does not have access to, or does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the file already exists, or the account has run out of disk space.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads." } ], "tags": [ "Uploads (Chunked)" ], "x-codeSamples": [ { "lang": "curl", "label": "Create upload session", "source": "curl -i -X POST \"https://upload.box.com/api/2.0/files/upload_sessions\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"folder_id\": \"0\",\n \"file_size\": 104857600,\n \"file_name\": \"Contract.pdf\"\n }'" }, { "lang": "dotnet", "label": "Create upload session", "source": "await client.ChunkedUploads.CreateFileUploadSessionAsync(requestBody: new CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: (long)(fileSize), folderId: parentFolderId));" }, { "lang": "swift", "label": "Create upload session", "source": "try await client.chunkedUploads.createFileUploadSession(requestBody: CreateFileUploadSessionRequestBody(fileName: fileName, fileSize: Int64(fileSize), folderId: parentFolderId))" }, { "lang": "java", "label": "Create upload session", "source": "client.getChunkedUploads().createFileUploadSession(new CreateFileUploadSessionRequestBody(parentFolderId, fileSize, fileName))" }, { "lang": "node", "label": "Create upload session", "source": "await client.chunkedUploads.createFileUploadSession({\n fileName: fileName,\n fileSize: fileSize,\n folderId: parentFolderId,\n} satisfies CreateFileUploadSessionRequestBody);" }, { "lang": "python", "label": "Create upload session", "source": "client.chunked_uploads.create_file_upload_session(\n parent_folder_id, file_size, file_name\n)" } ] } }, "/files/{file_id}/upload_sessions": { "post": { "operationId": "post_files_id_upload_sessions", "summary": "Create upload session for existing file", "description": "Creates an upload session for an existing file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "file_size": { "description": "The total number of bytes of the file to be uploaded.", "type": "integer", "format": "int64", "example": 104857600 }, "file_name": { "description": "The optional new name of new file.", "type": "string", "example": "Project.mov" } }, "required": [ "file_size" ] } } } }, "responses": { "201": { "description": "Returns a new upload session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "409": { "description": "Returns an error if the file already exists, or if the account has run out of disk space.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://upload.box.com/api/2.0", "description": "Server for file uploads." } ], "tags": [ "Uploads (Chunked)" ], "x-codeSamples": [ { "lang": "curl", "label": "Create upload session for existing file", "source": "curl -i -X POST \"https://upload.box.com/api/2.0/files/12345/upload_sessions\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"file_size\": 104857600\n }'" } ] } }, "/files/upload_sessions/{upload_session_id}": { "get": { "operationId": "get_files_upload_sessions_id", "summary": "Get upload session", "description": "Return information about an upload session.\n\nThe actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) endpoint.", "parameters": [ { "name": "upload_session_id", "in": "path", "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" }, "example": "D5E3F7A" } ], "responses": { "200": { "description": "Returns an upload session object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://{box-upload-server}/api/2.0", "description": "Server for file uploads.", "variables": { "box-upload-server": { "description": "The server for the upload session.", "default": "upload.box.com" } } } ], "tags": [ "Uploads (Chunked)" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Get upload session", "source": "curl -i -X GET \"https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get upload session", "source": "await client.ChunkedUploads.GetFileUploadSessionByIdAsync(uploadSessionId: uploadSessionId);" }, { "lang": "swift", "label": "Get upload session", "source": "try await client.chunkedUploads.getFileUploadSessionById(uploadSessionId: uploadSessionId)" }, { "lang": "java", "label": "Get upload session", "source": "client.getChunkedUploads().getFileUploadSessionById(uploadSessionId)" }, { "lang": "node", "label": "Get upload session", "source": "await client.chunkedUploads.getFileUploadSessionById(uploadSessionId);" }, { "lang": "python", "label": "Get upload session", "source": "client.chunked_uploads.get_file_upload_session_by_id(upload_session_id)" } ] }, "put": { "operationId": "put_files_upload_sessions_id", "summary": "Upload part of file", "description": "Uploads a chunk of a file for an upload session.\n\nThe actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", "in": "path", "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" }, "example": "D5E3F7A" }, { "name": "digest", "in": "header", "description": "The [RFC3230][1] message digest of the chunk uploaded.\n\nOnly SHA1 is supported. The SHA1 digest must be base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`.\n\nTo get the value for the `SHA` digest, use the openSSL command to encode the file part: `openssl sha1 -binary | base64`.\n\n[1]: https://tools.ietf.org/html/rfc3230", "required": true, "schema": { "type": "string" }, "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" }, { "name": "content-range", "in": "header", "description": "The byte range of the chunk.\n\nMust 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.\n\nWhen providing the value for `content-range`, remember that:\n\n- The lower bound of each part's byte range must be a multiple of the part size.\n- The higher bound must be a multiple of the part size - 1.", "required": true, "schema": { "type": "string" }, "example": "bytes 8388608-16777215/445856194" } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "description": "The binary content of the file.", "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Chunk has been uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedPart" } } } }, "409": { "description": "Returns an error if the chunk conflicts with another chunk previously uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error if a precondition was not met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "416": { "description": "Returns an error if the content range does not match a specified range for the session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://{box-upload-server}/api/2.0", "description": "Server for file uploads.", "variables": { "box-upload-server": { "description": "The server for the upload session.", "default": "upload.box.com" } } } ], "tags": [ "Uploads (Chunked)" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Upload part of file", "source": "curl -i -X PUT \"https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD\" \\\n -H \"authorization: Bearer \" \\\n -H \"digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=\" \\\n -H \"content-range: bytes 8388608-16777215/445856194\" \\\n -H \"content-type: application/octet-stream\" \\\n --data-binary @" }, { "lang": "dotnet", "label": "Upload part of file", "source": "await client.ChunkedUploads.UploadFilePartAsync(uploadSessionId: acc.UploadSessionId, requestBody: Utils.GenerateByteStreamFromBuffer(buffer: chunkBuffer), headers: new UploadFilePartHeaders(digest: digest, contentRange: contentRange));" }, { "lang": "swift", "label": "Upload part of file", "source": "try await client.chunkedUploads.uploadFilePart(uploadSessionId: acc.uploadSessionId, requestBody: Utils.generateByteStreamFromBuffer(buffer: chunkBuffer), headers: UploadFilePartHeaders(digest: digest, contentRange: contentRange))" }, { "lang": "java", "label": "Upload part of file", "source": "client.getChunkedUploads().uploadFilePart(acc.getUploadSessionId(), generateByteStreamFromBuffer(chunkBuffer), new UploadFilePartHeaders(digest, contentRange))" }, { "lang": "node", "label": "Upload part of file", "source": "await client.chunkedUploads.uploadFilePart(\n acc.uploadSessionId,\n generateByteStreamFromBuffer(chunkBuffer),\n {\n digest: digest,\n contentRange: contentRange,\n } satisfies UploadFilePartHeadersInput,\n);" }, { "lang": "python", "label": "Upload part of file", "source": "client.chunked_uploads.upload_file_part(\n acc.upload_session_id,\n generate_byte_stream_from_buffer(chunk_buffer),\n digest,\n content_range,\n)" } ] }, "delete": { "operationId": "delete_files_upload_sessions_id", "summary": "Remove upload session", "description": "Abort an upload session and discard all data uploaded.\n\nThis cannot be reversed.\n\nThe actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", "in": "path", "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" }, "example": "D5E3F7A" } ], "responses": { "204": { "description": "A blank response is returned if the session was successfully aborted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://{box-upload-server}/api/2.0", "description": "Server for file uploads.", "variables": { "box-upload-server": { "description": "The server for the upload session.", "default": "upload.box.com" } } } ], "tags": [ "Uploads (Chunked)" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Remove upload session", "source": "curl -i -X DELETE \"https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove upload session", "source": "await client.ChunkedUploads.DeleteFileUploadSessionByIdAsync(uploadSessionId: uploadSessionId);" }, { "lang": "swift", "label": "Remove upload session", "source": "try await client.chunkedUploads.deleteFileUploadSessionById(uploadSessionId: uploadSessionId)" }, { "lang": "java", "label": "Remove upload session", "source": "client.getChunkedUploads().deleteFileUploadSessionById(uploadSessionId)" }, { "lang": "node", "label": "Remove upload session", "source": "await client.chunkedUploads.deleteFileUploadSessionById(uploadSessionId);" }, { "lang": "python", "label": "Remove upload session", "source": "client.chunked_uploads.delete_file_upload_session_by_id(upload_session_id)" } ] } }, "/files/upload_sessions/{upload_session_id}/parts": { "get": { "operationId": "get_files_upload_sessions_id_parts", "summary": "List parts", "description": "Return a list of the chunks uploaded to the upload session so far.\n\nThe actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", "in": "path", "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" }, "example": "D5E3F7A" }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of parts that have been uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadParts" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://{box-upload-server}/api/2.0", "description": "Server for file uploads.", "variables": { "box-upload-server": { "description": "The server for the upload session.", "default": "upload.box.com" } } } ], "tags": [ "Uploads (Chunked)" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "List parts", "source": "curl -i -X GET \"https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List parts", "source": "await client.ChunkedUploads.GetFileUploadSessionPartsAsync(uploadSessionId: uploadSessionId);" }, { "lang": "swift", "label": "List parts", "source": "try await client.chunkedUploads.getFileUploadSessionParts(uploadSessionId: uploadSessionId)" }, { "lang": "java", "label": "List parts", "source": "client.getChunkedUploads().getFileUploadSessionParts(uploadSessionId)" }, { "lang": "node", "label": "List parts", "source": "await client.chunkedUploads.getFileUploadSessionParts(uploadSessionId);" }, { "lang": "python", "label": "List parts", "source": "client.chunked_uploads.get_file_upload_session_parts(upload_session_id)" } ] } }, "/files/upload_sessions/{upload_session_id}/commit": { "post": { "operationId": "post_files_upload_sessions_id_commit", "summary": "Commit upload session", "description": "Close an upload session and create a file from the uploaded chunks.\n\nThe actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.", "parameters": [ { "name": "upload_session_id", "in": "path", "description": "The ID of the upload session.", "required": true, "schema": { "type": "string" }, "example": "D5E3F7A" }, { "name": "digest", "in": "header", "description": "The [RFC3230][1] message digest of the whole file.\n\nOnly SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as `sha=BASE64_ENCODED_DIGEST`.\n\n[1]: https://tools.ietf.org/html/rfc3230", "required": true, "schema": { "type": "string" }, "example": "sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "if-none-match", "in": "header", "description": "Ensures an item is only returned if it has changed.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "parts": { "description": "The list details for the uploaded parts.", "type": "array", "items": { "$ref": "#/components/schemas/UploadPart" } } }, "required": [ "parts" ] } } } }, "responses": { "201": { "description": "Returns the file object in a list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Files" } } } }, "202": { "description": "Returns when all chunks have been uploaded but not yet processed.\n\nInspect 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": { "description": "Returns an error if there is already a file with the same name in the target folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "description": "Returns an error if the `If-Match` or `If-None-Match` conditions fail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "chunked_uploads", "servers": [ { "url": "https://{box-upload-server}/api/2.0", "description": "Server for file uploads.", "variables": { "box-upload-server": { "description": "The server for the upload session.", "default": "upload.box.com" } } } ], "tags": [ "Uploads (Chunked)" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Commit upload session", "source": "curl -i -X POST \"https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit\" \\\n -H \"authorization: Bearer \" \\\n -H \"digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=\" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"parts\": [\n {\n \"part_id\": \"BFDF5379\",\n \"offset\": 0,\n \"size\": 8388608,\n\t \"sha1\": \"134b65991ed521fcfe4724b7d814ab8ded5185dc\"\n },\n\t\t {\n \"part_id\": \"E8A3ED8E\",\n \"offset\": 8388608,\n \"size\": 1611392,\n\t \"sha1\": \"234b65934ed521fcfe3424b7d814ab8ded5185dc\"\n }\n ],\n \"attributes\": {\n \"content_modified_at\": \"2017-04-08T00:58:08Z\"\n }\n }'" }, { "lang": "dotnet", "label": "Commit upload session", "source": "await client.ChunkedUploads.CreateFileUploadSessionCommitAsync(uploadSessionId: uploadSessionId, requestBody: new CreateFileUploadSessionCommitRequestBody(parts: parts), headers: new CreateFileUploadSessionCommitHeaders(digest: digest));" }, { "lang": "swift", "label": "Commit upload session", "source": "try await client.chunkedUploads.createFileUploadSessionCommit(uploadSessionId: uploadSessionId, requestBody: CreateFileUploadSessionCommitRequestBody(parts: parts), headers: CreateFileUploadSessionCommitHeaders(digest: digest))" }, { "lang": "java", "label": "Commit upload session", "source": "client.getChunkedUploads().createFileUploadSessionCommit(uploadSessionId, new CreateFileUploadSessionCommitRequestBody(parts), new CreateFileUploadSessionCommitHeaders(digest))" }, { "lang": "node", "label": "Commit upload session", "source": "await client.chunkedUploads.createFileUploadSessionCommit(\n uploadSessionId,\n { parts: parts } satisfies CreateFileUploadSessionCommitRequestBody,\n { digest: digest } satisfies CreateFileUploadSessionCommitHeadersInput,\n);" }, { "lang": "python", "label": "Commit upload session", "source": "client.chunked_uploads.create_file_upload_session_commit(\n upload_session_id, parts, digest\n)" } ] } }, "/files/{file_id}/copy": { "post": { "operationId": "post_files_id_copy", "summary": "Copy file", "description": "Creates a copy of a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the copied file.\n\nThere 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.", "type": "string", "example": "FileCopy.txt", "maxLength": 255 }, "version": { "description": "An optional ID of the specific file version to copy.", "type": "string", "example": "0" }, "parent": { "description": "The destination folder to copy the file to.", "type": "object", "properties": { "id": { "description": "The ID of folder to copy the file to.", "type": "string", "example": "0" } }, "required": [ "id" ] } }, "nullable": false, "required": [ "parent" ] } } } }, "responses": { "201": { "description": "Returns a new file object representing the copied file.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "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": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `bad_request` when a parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the right permissions to create the copy a file.\n\n- `forbidden_by_policy`: Returned if copying a file is forbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `not_found` when the authenticated user does not have access to the source file or the destination folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "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.\n\nThe operation can be retried at a later point.\n\n`item_name_in_use` when a folder with the same name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "files", "tags": [ "Files" ], "x-codeSamples": [ { "lang": "curl", "label": "Copy file", "source": "curl -i -X POST \"https://api.box.com/2.0/files/12345/copy\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"parent\": {\n \"id\": \"123\"\n }\n }'" }, { "lang": "dotnet", "label": "Copy file", "source": "await client.Files.CopyFileAsync(fileId: fileOrigin.Id, requestBody: new CopyFileRequestBody(parent: new CopyFileRequestBodyParentField(id: \"0\")) { Name = copiedFileName });" }, { "lang": "swift", "label": "Copy file", "source": "try await client.files.copyFile(fileId: fileOrigin.id, requestBody: CopyFileRequestBody(parent: CopyFileRequestBodyParentField(id: \"0\"), name: copiedFileName))" }, { "lang": "java", "label": "Copy file", "source": "client.getFiles().copyFile(fileOrigin.getId(), new CopyFileRequestBody.Builder(new CopyFileRequestBodyParentField(\"0\")).name(copiedFileName).build())" }, { "lang": "node", "label": "Copy file", "source": "await client.files.copyFile(fileOrigin.id, {\n parent: { id: '0' } satisfies CopyFileRequestBodyParentField,\n name: copiedFileName,\n} satisfies CopyFileRequestBody);" }, { "lang": "python", "label": "Copy file", "source": "client.files.copy_file(file_origin.id, CopyFileParent(id=\"0\"), name=copied_file_name)" } ] } }, "/files/{file_id}/thumbnail.{extension}": { "get": { "operationId": "get_files_id_thumbnail_id", "summary": "Get file thumbnail", "description": "Retrieves a thumbnail, or smaller image representation, of a file.\n\nSizes 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.\n\nThumbnails can be generated for the image and video file formats listed [found on our community site][1].\n\n[1]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "extension", "in": "path", "description": "The file format for the thumbnail.", "required": true, "schema": { "type": "string", "enum": [ "png", "jpg" ] }, "example": "png" }, { "name": "min_height", "in": "query", "description": "The minimum height of the thumbnail.", "schema": { "type": "integer", "maximum": 320, "minimum": 32 }, "example": 32 }, { "name": "min_width", "in": "query", "description": "The minimum width of the thumbnail.", "schema": { "type": "integer", "maximum": 320, "minimum": 32 }, "example": 32 }, { "name": "max_height", "in": "query", "description": "The maximum height of the thumbnail.", "required": false, "schema": { "type": "integer", "maximum": 320, "minimum": 32 }, "example": 320 }, { "name": "max_width", "in": "query", "description": "The maximum width of the thumbnail.", "required": false, "schema": { "type": "integer", "maximum": 320, "minimum": 32 }, "example": 320 } ], "responses": { "200": { "description": "When a thumbnail can be created the thumbnail data will be returned in the body of the response.", "content": { "image/jpg": { "schema": { "description": "The thumbnail.", "type": "string", "format": "binary" } }, "image/png": { "schema": { "description": "The thumbnail.", "type": "string", "format": "binary" } } } }, "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.\n\nThe 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": { "Retry-After": { "description": "The time in seconds after which the thumbnail will be available.\n\nYour application only attempt to get the thumbnail again after this time.", "schema": { "type": "integer", "format": "int64" } }, "Location": { "description": "A pointer to a placeholder graphic that can be used until the thumbnail has been generated.", "schema": { "type": "string", "format": "url" } } } }, "302": { "description": "Returns an error when Box is not able to create a thumbnail for this file type.\n\nInstead, 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": { "type": "string", "format": "url" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file, or for additional reasons.\n\n- `preview_cannot_be_generated` - Box does not support thumbnails for this type of file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "files", "tags": [ "Files" ], "x-codeSamples": [ { "lang": "curl", "label": "Get file thumbnail", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/thumbnail.png\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get file thumbnail", "source": "await client.Files.GetFileThumbnailByIdAsync(fileId: thumbnailFile.Id, extension: GetFileThumbnailByIdExtension.Png);" }, { "lang": "swift", "label": "Get file thumbnail", "source": "try await client.files.getFileThumbnailById(fileId: thumbnailFile.id, extension_: GetFileThumbnailByIdExtension.png, downloadDestinationUrl: destinationPath)" }, { "lang": "java", "label": "Get file thumbnail", "source": "client.getFiles().getFileThumbnailById(thumbnailFile.getId(), GetFileThumbnailByIdExtension.PNG)" }, { "lang": "node", "label": "Get file thumbnail", "source": "await client.files.getFileThumbnailById(\n thumbnailFile.id,\n 'png' as GetFileThumbnailByIdExtension,\n);" }, { "lang": "python", "label": "Get file thumbnail", "source": "client.files.get_file_thumbnail_by_id(\n thumbnail_file.id, GetFileThumbnailByIdExtension.PNG\n)" } ] } }, "/files/{file_id}/collaborations": { "get": { "operationId": "get_files_id_collaborations", "summary": "List file collaborations", "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.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned.\n\nThis list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaborations" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "list_collaborations", "tags": [ "Collaborations (List)" ], "x-codeSamples": [ { "lang": "curl", "label": "List file collaborations", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/collaborations\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List file collaborations", "source": "await client.ListCollaborations.GetFileCollaborationsAsync(fileId: file.Id);" }, { "lang": "swift", "label": "List file collaborations", "source": "try await client.listCollaborations.getFileCollaborations(fileId: file.id)" }, { "lang": "java", "label": "List file collaborations", "source": "client.getListCollaborations().getFileCollaborations(file.getId())" }, { "lang": "node", "label": "List file collaborations", "source": "await client.listCollaborations.getFileCollaborations(file.id);" }, { "lang": "python", "label": "List file collaborations", "source": "client.list_collaborations.get_file_collaborations(file.id)" } ] } }, "/files/{file_id}/comments": { "get": { "operationId": "get_files_id_comments", "summary": "List file comments", "description": "Retrieves a list of comments for a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of comment objects. If there are no comments on this file an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comments" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "comments", "tags": [ "Comments" ], "x-codeSamples": [ { "lang": "curl", "label": "List file comments", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/comments\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List file comments", "source": "await client.Comments.GetFileCommentsAsync(fileId: fileId);" }, { "lang": "swift", "label": "List file comments", "source": "try await client.comments.getFileComments(fileId: fileId)" }, { "lang": "java", "label": "List file comments", "source": "client.getComments().getFileComments(fileId)" }, { "lang": "node", "label": "List file comments", "source": "await client.comments.getFileComments(fileId);" }, { "lang": "python", "label": "List file comments", "source": "client.comments.get_file_comments(file_id)" } ] } }, "/files/{file_id}/tasks": { "get": { "operationId": "get_files_id_tasks", "summary": "List tasks on file", "description": "Retrieves a list of all the tasks for a file. This endpoint does not support pagination.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "Returns a list of tasks on a file.\n\nIf there are no tasks on this file an empty collection is returned instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tasks" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returns an error when the `file_id` was not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error when an attempt was made to retrieve tasks for the file with ID `0`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "tasks", "tags": [ "Tasks" ], "x-codeSamples": [ { "lang": "curl", "label": "List tasks on file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/tasks\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List tasks on file", "source": "await client.Tasks.GetFileTasksAsync(fileId: file.Id);" }, { "lang": "swift", "label": "List tasks on file", "source": "try await client.tasks.getFileTasks(fileId: file.id)" }, { "lang": "java", "label": "List tasks on file", "source": "client.getTasks().getFileTasks(file.getId())" }, { "lang": "node", "label": "List tasks on file", "source": "await client.tasks.getFileTasks(file.id);" }, { "lang": "python", "label": "List tasks on file", "source": "client.tasks.get_file_tasks(file.id)" } ] } }, "/files/{file_id}/trash": { "get": { "operationId": "get_files_id_trash", "summary": "Get trashed file", "description": "Retrieves a file that has been moved to the trash.\n\nPlease 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`](/reference/get-folders-id-trash) API.\n\nTo list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](/reference/get-folders-trash-items/) API.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the file that was trashed, including information about when the it was moved to the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFile" } } } }, "404": { "description": "Returns an error if the file can not be found directly in the trash.\n\nPlease note that a `HTTP 404` is also returned if any of the file's parent folders have been moved to the trash.\n\nIn that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](/reference/get-folders-id-trash) API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_files", "tags": [ "Trashed files" ], "x-codeSamples": [ { "lang": "curl", "label": "Get trashed file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/trash\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get trashed file", "source": "await client.TrashedFiles.GetTrashedFileByIdAsync(fileId: file.Id);" }, { "lang": "swift", "label": "Get trashed file", "source": "try await client.trashedFiles.getTrashedFileById(fileId: file.id)" }, { "lang": "java", "label": "Get trashed file", "source": "client.getTrashedFiles().getTrashedFileById(file.getId())" }, { "lang": "node", "label": "Get trashed file", "source": "await client.trashedFiles.getTrashedFileById(file.id);" }, { "lang": "python", "label": "Get trashed file", "source": "client.trashed_files.get_trashed_file_by_id(file.id)" } ] }, "delete": { "operationId": "delete_files_id_trash", "summary": "Permanently remove file", "description": "Permanently deletes a file that is in the trash. This action cannot be undone.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the file was permanently deleted." }, "404": { "description": "Returns an error if the file is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_files", "tags": [ "Trashed files" ], "x-codeSamples": [ { "lang": "curl", "label": "Permanently remove file", "source": "curl -i -X DELETE \"https://api.box.com/2.0/files/12345/trash\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Permanently remove file", "source": "await client.TrashedFiles.DeleteTrashedFileByIdAsync(fileId: file.Id);" }, { "lang": "swift", "label": "Permanently remove file", "source": "try await client.trashedFiles.deleteTrashedFileById(fileId: file.id)" }, { "lang": "java", "label": "Permanently remove file", "source": "client.getTrashedFiles().deleteTrashedFileById(file.getId())" }, { "lang": "node", "label": "Permanently remove file", "source": "await client.trashedFiles.deleteTrashedFileById(file.id);" }, { "lang": "python", "label": "Permanently remove file", "source": "client.trashed_files.delete_trashed_file_by_id(file.id)" } ] } }, "/files/{file_id}/versions": { "get": { "operationId": "get_files_id_versions", "summary": "List all file versions", "description": "Retrieve a list of the past versions for a file.\n\nVersions 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.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 } ], "responses": { "200": { "description": "Returns an array of past versions for this file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersions" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_versions", "tags": [ "File versions" ], "x-codeSamples": [ { "lang": "curl", "label": "List all file versions", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/versions\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List all file versions", "source": "await client.FileVersions.GetFileVersionsAsync(fileId: file.Id);" }, { "lang": "swift", "label": "List all file versions", "source": "try await client.fileVersions.getFileVersions(fileId: file.id)" }, { "lang": "java", "label": "List all file versions", "source": "client.getFileVersions().getFileVersions(file.getId())" }, { "lang": "node", "label": "List all file versions", "source": "await client.fileVersions.getFileVersions(file.id);" }, { "lang": "python", "label": "List all file versions", "source": "client.file_versions.get_file_versions(file.id)" } ] } }, "/files/{file_id}/versions/{file_version_id}": { "get": { "operationId": "get_files_id_versions_id", "summary": "Get file version", "description": "Retrieve a specific version of a file.\n\nVersions are only tracked for Box users with premium accounts.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "file_version_id", "in": "path", "description": "The ID of the file version.", "required": true, "schema": { "type": "string" }, "example": "1234" } ], "responses": { "200": { "description": "Returns a specific version of a file.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersion--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_versions", "tags": [ "File versions" ], "x-codeSamples": [ { "lang": "curl", "label": "Get file version", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/versions/456456\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get file version", "source": "await client.FileVersions.GetFileVersionByIdAsync(fileId: file.Id, fileVersionId: NullableUtils.Unwrap(fileVersions.Entries)[0].Id);" }, { "lang": "swift", "label": "Get file version", "source": "try await client.fileVersions.getFileVersionById(fileId: file.id, fileVersionId: fileVersions.entries![0].id)" }, { "lang": "java", "label": "Get file version", "source": "client.getFileVersions().getFileVersionById(file.getId(), fileVersions.getEntries().get(0).getId())" }, { "lang": "node", "label": "Get file version", "source": "await client.fileVersions.getFileVersionById(\n file.id,\n fileVersions.entries![0].id,\n);" }, { "lang": "python", "label": "Get file version", "source": "client.file_versions.get_file_version_by_id(file.id, file_versions.entries[0].id)" } ] }, "delete": { "operationId": "delete_files_id_versions_id", "summary": "Remove file version", "description": "Move a file version to the trash.\n\nVersions are only tracked for Box users with premium accounts.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "file_version_id", "in": "path", "description": "The ID of the file version.", "required": true, "schema": { "type": "string" }, "example": "1234" }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" } ], "responses": { "204": { "description": "Returns an empty response when the file has been successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_versions", "tags": [ "File versions" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove file version", "source": "curl -i -X DELETE \"https://api.box.com/2.0/files/12345/versions/456456\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove file version", "source": "await client.FileVersions.DeleteFileVersionByIdAsync(fileId: file.Id, fileVersionId: fileVersion.Id);" }, { "lang": "swift", "label": "Remove file version", "source": "try await client.fileVersions.deleteFileVersionById(fileId: file.id, fileVersionId: fileVersion.id)" }, { "lang": "java", "label": "Remove file version", "source": "client.getFileVersions().deleteFileVersionById(file.getId(), fileVersion.getId())" }, { "lang": "node", "label": "Remove file version", "source": "await client.fileVersions.deleteFileVersionById(file.id, fileVersion.id);" }, { "lang": "python", "label": "Remove file version", "source": "client.file_versions.delete_file_version_by_id(file.id, file_version.id)" } ] }, "put": { "operationId": "put_files_id_versions_id", "summary": "Restore file version", "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.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "file_version_id", "in": "path", "description": "The ID of the file version.", "required": true, "schema": { "type": "string" }, "example": "1234" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The file version to be restored.", "type": "object", "properties": { "trashed_at": { "description": "Set this to `null` to clear the date and restore the file.", "type": "string", "example": null, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a restored file version object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersion--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_versions", "tags": [ "File versions" ], "x-codeSamples": [ { "lang": "curl", "label": "Restore file version", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/12345/versions/456456\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"trashed_at\": null\n }'" }, { "lang": "dotnet", "label": "Restore file version", "source": "await client.FileVersions.UpdateFileVersionByIdAsync(fileId: file.Id, fileVersionId: fileVersion.Id, requestBody: new UpdateFileVersionByIdRequestBody() { TrashedAt = null });" }, { "lang": "java", "label": "Restore file version", "source": "client.getFileVersions().updateFileVersionById(file.getId(), fileVersion.getId(), new UpdateFileVersionByIdRequestBody.Builder().trashedAt(null).build())" }, { "lang": "node", "label": "Restore file version", "source": "await client.fileVersions.updateFileVersionById(file.id, fileVersion.id, {\n requestBody: {\n trashedAt: createNull(),\n } satisfies UpdateFileVersionByIdRequestBody,\n} satisfies UpdateFileVersionByIdOptionalsInput);" }, { "lang": "python", "label": "Restore file version", "source": "client.file_versions.update_file_version_by_id(\n file.id, file_version.id, trashed_at=create_null()\n)" } ] } }, "/files/{file_id}/versions/current": { "post": { "operationId": "post_files_id_versions_current", "summary": "Promote file version", "description": "Promote a specific version of a file.\n\nIf previous versions exist, this method can be used to promote one of the older versions to the top of the version history.\n\nThis 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 same hash digest, `etag`, and name as the original.\n\nOther properties such as comments do not get updated to their former values.\n\nDon't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The file version to promote.", "type": "object", "properties": { "id": { "description": "The file version ID.", "type": "string", "example": "11446498" }, "type": { "description": "The type to promote.", "type": "string", "example": "file_version", "enum": [ "file_version" ] } } } } } }, "responses": { "201": { "description": "Returns a newly created file version object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersion--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_versions", "tags": [ "File versions" ], "x-codeSamples": [ { "lang": "curl", "label": "Promote file version", "source": "curl -i -X POST \"https://api.box.com/2.0/files/12345/versions/current\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"type\": \"file_version\",\n \"id\": \"456456\"\n }'" }, { "lang": "dotnet", "label": "Promote file version", "source": "await client.FileVersions.PromoteFileVersionAsync(fileId: file.Id, requestBody: new PromoteFileVersionRequestBody() { Id = NullableUtils.Unwrap(fileVersions.Entries)[0].Id, Type = PromoteFileVersionRequestBodyTypeField.FileVersion });" }, { "lang": "swift", "label": "Promote file version", "source": "try await client.fileVersions.promoteFileVersion(fileId: file.id, requestBody: PromoteFileVersionRequestBody(id: fileVersions.entries![0].id, type: PromoteFileVersionRequestBodyTypeField.fileVersion))" }, { "lang": "java", "label": "Promote file version", "source": "client.getFileVersions().promoteFileVersion(file.getId(), new PromoteFileVersionRequestBody.Builder().id(fileVersions.getEntries().get(0).getId()).type(PromoteFileVersionRequestBodyTypeField.FILE_VERSION).build())" }, { "lang": "node", "label": "Promote file version", "source": "await client.fileVersions.promoteFileVersion(file.id, {\n requestBody: {\n id: fileVersions.entries![0].id,\n type: 'file_version' as PromoteFileVersionRequestBodyTypeField,\n } satisfies PromoteFileVersionRequestBody,\n} satisfies PromoteFileVersionOptionalsInput);" }, { "lang": "python", "label": "Promote file version", "source": "client.file_versions.promote_file_version(\n file.id, id=file_versions.entries[0].id, type=PromoteFileVersionType.FILE_VERSION\n)" } ] } }, "/files/{file_id}/metadata": { "get": { "operationId": "get_files_id_metadata", "summary": "List metadata instances on file", "description": "Retrieves all metadata for a given file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "view", "in": "query", "description": "Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter.", "required": false, "schema": { "type": "string" }, "example": "hydrated" } ], "responses": { "200": { "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return all of the metadata associated to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadatas" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_metadata", "tags": [ "Metadata instances (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "List metadata instances on file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/metadata\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List metadata instances on file", "source": "await client.FileMetadata.GetFileMetadataAsync(fileId: file.Id);" }, { "lang": "swift", "label": "List metadata instances on file", "source": "try await client.fileMetadata.getFileMetadata(fileId: file.id)" }, { "lang": "java", "label": "List metadata instances on file", "source": "client.getFileMetadata().getFileMetadata(file.getId())" }, { "lang": "node", "label": "List metadata instances on file", "source": "await client.fileMetadata.getFileMetadata(file.id);" }, { "lang": "python", "label": "List metadata instances on file", "source": "client.file_metadata.get_file_metadata(file.id)" } ] } }, "/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { "get": { "operationId": "get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Get classification on file", "description": "Retrieves the classification metadata instance that has been applied to a file.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified was not applied to this file or the user does not have access to the file.\n\n- `instance_not_found` - The metadata template was not applied to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_classifications", "tags": [ "Classifications on files" ], "x-codeSamples": [ { "lang": "curl", "label": "Get classification on file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get classification on file", "source": "await client.FileClassifications.GetClassificationOnFileAsync(fileId: file.Id);" }, { "lang": "swift", "label": "Get classification on file", "source": "try await client.fileClassifications.getClassificationOnFile(fileId: file.id)" }, { "lang": "java", "label": "Get classification on file", "source": "client.getFileClassifications().getClassificationOnFile(file.getId())" }, { "lang": "node", "label": "Get classification on file", "source": "await client.fileClassifications.getClassificationOnFile(file.id);" }, { "lang": "python", "label": "Get classification on file", "source": "client.file_classifications.get_classification_on_file(file.id)" } ] }, "post": { "operationId": "post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to file", "description": "Adds a classification to a file by specifying the label of the classification to add.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Box__Security__Classification__Key": { "description": "The name of the classification to apply to this file.\n\nTo list the available classifications in an enterprise, use the classification API to retrieve the [classification template](/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema) which lists all available classification keys.", "type": "string", "example": "Sensitive" } } } } } }, "responses": { "201": { "description": "Returns the classification template instance that was applied to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file or metadata template was not found.\n\n- `not_found` - The file could not be found, or the user does not have access to the file.\n- `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already present on the file.\n\n- `tuple_already_exists` - An instance of them metadata template already exists on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_classifications", "tags": [ "Classifications on files" ], "x-codeSamples": [ { "lang": "curl", "label": "Add classification to file", "source": "curl -i -X POST \"https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"Box__Security__Classification__Key\": \"Sensitive\"\n\n }'" }, { "lang": "dotnet", "label": "Add classification to file", "source": "await client.FileClassifications.AddClassificationToFileAsync(fileId: file.Id, requestBody: new AddClassificationToFileRequestBody() { BoxSecurityClassificationKey = classification.Key });" }, { "lang": "swift", "label": "Add classification to file", "source": "try await client.fileClassifications.addClassificationToFile(fileId: file.id, requestBody: AddClassificationToFileRequestBody(boxSecurityClassificationKey: classification.key))" }, { "lang": "java", "label": "Add classification to file", "source": "client.getFileClassifications().addClassificationToFile(file.getId(), new AddClassificationToFileRequestBody.Builder().boxSecurityClassificationKey(classification.getKey()).build())" }, { "lang": "node", "label": "Add classification to file", "source": "await client.fileClassifications.addClassificationToFile(file.id, {\n requestBody: {\n boxSecurityClassificationKey: classification.key,\n } satisfies AddClassificationToFileRequestBody,\n} satisfies AddClassificationToFileOptionalsInput);" }, { "lang": "python", "label": "Add classification to file", "source": "client.file_classifications.add_classification_to_file(\n file.id, box_security_classification_key=classification.key\n)" } ] }, "put": { "operationId": "put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on file", "description": "Updates a classification on a file.\n\nThe 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.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A list containing the one change to make, to update the classification label.", "type": "array", "items": { "type": "object", "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.", "required": [ "op", "path", "value" ], "properties": { "op": { "description": "The value will always be `replace`.", "type": "string", "example": "replace", "enum": [ "replace" ] }, "path": { "description": "Defines classifications available in the enterprise.", "type": "string", "example": "/Box__Security__Classification__Key", "enum": [ "/Box__Security__Classification__Key" ] }, "value": { "description": "The name of the classification to apply to this file.\n\nTo list the available classifications in an enterprise, use the classification API to retrieve the [classification template](/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema) which lists all available classification keys.", "type": "string", "example": "Sensitive" } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Returns the updated classification metadata template instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `bad_request` - The request body format is not an array of valid JSON Patch operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_classifications", "tags": [ "Classifications on files" ], "x-codeSamples": [ { "lang": "curl", "label": "Update classification on file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[{\n \"op\": \"replace\",\n \"path\": \"/Box__Security__Classification__Key\",\n \"value\": \"Internal\"\n }]'" }, { "lang": "dotnet", "label": "Update classification on file", "source": "await client.FileClassifications.UpdateClassificationOnFileAsync(fileId: file.Id, requestBody: Array.AsReadOnly(new [] {new UpdateClassificationOnFileRequestBody(value: secondClassification.Key)}));" }, { "lang": "swift", "label": "Update classification on file", "source": "try await client.fileClassifications.updateClassificationOnFile(fileId: file.id, requestBody: [UpdateClassificationOnFileRequestBody(value: secondClassification.key)])" }, { "lang": "java", "label": "Update classification on file", "source": "client.getFileClassifications().updateClassificationOnFile(file.getId(), Arrays.asList(new UpdateClassificationOnFileRequestBody(secondClassification.getKey())))" }, { "lang": "node", "label": "Update classification on file", "source": "await client.fileClassifications.updateClassificationOnFile(file.id, [\n new UpdateClassificationOnFileRequestBody({\n value: secondClassification.key,\n }),\n]);" }, { "lang": "python", "label": "Update classification on file", "source": "client.file_classifications.update_classification_on_file(\n file.id, [UpdateClassificationOnFileRequestBody(value=second_classification.key)]\n)" } ] }, "delete": { "operationId": "delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from file", "description": "Removes any classifications from a file.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the classification is successfully deleted." }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `instance_not_found` - An instance of the classification metadata template with the was not found on this file.\n- `not_found` - The file was not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_classifications", "tags": [ "Classifications on files" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove classification from file", "source": "curl -i -X DELETE \"https://api.box.com/2.0/files/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove classification from file", "source": "await client.FileClassifications.DeleteClassificationFromFileAsync(fileId: file.Id);" }, { "lang": "swift", "label": "Remove classification from file", "source": "try await client.fileClassifications.deleteClassificationFromFile(fileId: file.id)" }, { "lang": "java", "label": "Remove classification from file", "source": "client.getFileClassifications().deleteClassificationFromFile(file.getId())" }, { "lang": "node", "label": "Remove classification from file", "source": "await client.fileClassifications.deleteClassificationFromFile(file.id);" }, { "lang": "python", "label": "Remove classification from file", "source": "client.file_classifications.delete_classification_from_file(file.id)" } ] } }, "/files/{file_id}/metadata/{scope}/{template_key}": { "get": { "operationId": "get_files_id_metadata_id_id", "summary": "Get metadata instance on file", "description": "Retrieves the instance of a metadata template that has been applied to a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" }, { "name": "view", "in": "query", "description": "Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter.", "required": false, "schema": { "type": "string" }, "example": "hydrated" } ], "responses": { "201": { "description": "An instance of the metadata template that includes additional \"key:value\" pairs defined by the user or an application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata--Full" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified was not applied to this file or the user does not have access to the file.\n\n- `instance_not_found` - The metadata template was not applied to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_metadata", "tags": [ "Metadata instances (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata instance on file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata instance on file", "source": "await client.FileMetadata.GetFileMetadataByIdAsync(fileId: file.Id, scope: GetFileMetadataByIdScope.Global, templateKey: \"properties\");" }, { "lang": "swift", "label": "Get metadata instance on file", "source": "try await client.fileMetadata.getFileMetadataById(fileId: file.id, scope: GetFileMetadataByIdScope.global, templateKey: \"properties\")" }, { "lang": "java", "label": "Get metadata instance on file", "source": "client.getFileMetadata().getFileMetadataById(file.getId(), GetFileMetadataByIdScope.GLOBAL, \"properties\")" }, { "lang": "node", "label": "Get metadata instance on file", "source": "await client.fileMetadata.getFileMetadataById(\n file.id,\n 'global' as GetFileMetadataByIdScope,\n 'properties',\n);" }, { "lang": "python", "label": "Get metadata instance on file", "source": "client.file_metadata.get_file_metadata_by_id(\n file.id, GetFileMetadataByIdScope.GLOBAL, \"properties\"\n)" } ] }, "post": { "operationId": "post_files_id_metadata_id_id", "summary": "Create metadata instance on file", "description": "Applies an instance of a metadata template to a file.\n\nIn 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.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "name": "Aaron Levie" }, "additionalProperties": { "allOf": [ {}, { "example": "Aaron Levie" }, { "description": "A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template. For a taxonomy field, the value should be a list of the node identifiers of the selected taxonomy nodes, since taxonomy fields support multi-select. If a single select taxonomy field is being set, the list should contain a single node identifier." } ] }, "x-box-example-key": "name" } } } }, "responses": { "201": { "description": "Returns the instance of the template that was applied to the file, including the data that was applied to the template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata--Full" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataError" } } } }, "404": { "description": "Returns an error when the file or metadata template was not found.\n\n- `not_found` - The file could not be found, or the user does not have access to the file.\n- `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already present on the file.\n\n- `tuple_already_exists` - An instance of the metadata template already exists on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_metadata", "tags": [ "Metadata instances (Files)" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Create metadata instance on file", "source": "curl -i -X POST \"https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"audience\": \"internal\",\n \"documentType\": \"Q1 plans\",\n \"competitiveDocument\": \"no\",\n \"status\": \"active\",\n \"author\": \"Jones\",\n \"currentState\": \"proposal\"\n }'" }, { "lang": "dotnet", "label": "Create metadata instance on file", "source": "await client.FileMetadata.CreateFileMetadataByIdAsync(fileId: file.Id, scope: CreateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary() { { \"name\", \"John\" }, { \"age\", 23 }, { \"birthDate\", \"2001-01-03T02:20:50.520Z\" }, { \"countryCode\", \"US\" }, { \"sports\", Array.AsReadOnly(new [] {\"basketball\",\"tennis\"}) } });" }, { "lang": "swift", "label": "Create metadata instance on file", "source": "try await client.fileMetadata.createFileMetadataById(fileId: file.id, scope: CreateFileMetadataByIdScope.global, templateKey: \"properties\", requestBody: [\"abc\": \"xyz\"])" }, { "lang": "java", "label": "Create metadata instance on file", "source": "client.getFileMetadata().createFileMetadataById(file.getId(), CreateFileMetadataByIdScope.ENTERPRISE, templateKey, mapOf(entryOf(\"name\", \"John\"), entryOf(\"age\", 23), entryOf(\"birthDate\", \"2001-01-03T02:20:50.520Z\"), entryOf(\"countryCode\", \"US\"), entryOf(\"sports\", Arrays.asList(\"basketball\", \"tennis\"))))" }, { "lang": "node", "label": "Create metadata instance on file", "source": "await client.fileMetadata.createFileMetadataById(\n file.id,\n 'enterprise' as CreateFileMetadataByIdScope,\n templateKey,\n {\n ['name']: 'John',\n ['age']: 23,\n ['birthDate']: '2001-01-03T02:20:50.520Z',\n ['countryCode']: 'US',\n ['sports']: ['basketball', 'tennis'],\n },\n);" }, { "lang": "python", "label": "Create metadata instance on file", "source": "client.file_metadata.create_file_metadata_by_id(\n file.id,\n CreateFileMetadataByIdScope.ENTERPRISE,\n template_key,\n {\n \"name\": \"John\",\n \"age\": 23,\n \"birthDate\": \"2001-01-03T02:20:50.520Z\",\n \"countryCode\": \"US\",\n \"sports\": [\"basketball\", \"tennis\"],\n },\n)" } ] }, "put": { "operationId": "put_files_id_metadata_id_id", "summary": "Update metadata instance on file", "description": "Updates a piece of metadata on a file.\n\nThe 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.\n\nThe update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "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.\n\nThe changes are represented as a JSON array of operation objects.", "type": "array", "items": { "title": "A metadata instance update operation", "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a change to make to the metadata instance.", "type": "object", "properties": { "op": { "description": "The type of change to perform on the template. Some of these are hazardous as they will change existing templates.", "type": "string", "example": "add", "enum": [ "add", "replace", "remove", "test", "move", "copy" ] }, "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).\n\nThe 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.", "type": "string", "example": "/currentState" }, "value": { "$ref": "#/components/schemas/MetadataInstanceValue" }, "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).", "type": "string", "example": "/nextState" } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template instance, with the custom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata--Full" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `bad_request` - The request body format is not an array of valid JSON Patch objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_metadata", "tags": [ "Metadata instances (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Update metadata instance on file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[\n {\n \"op\": \"test\",\n \"path\": \"/competitiveDocument\",\n \"value\": \"no\"\n },\n {\n \"op\": \"remove\",\n \"path\": \"/competitiveDocument\"\n },\n {\n \"op\": \"test\",\n \"path\": \"/status\",\n \"value\": \"active\"\n },\n {\n \"op\": \"replace\",\n \"path\": \"/status\",\n \"value\": \"inactive\"\n },\n {\n \"op\": \"test\",\n \"path\": \"/author\",\n \"value\": \"Jones\"\n },\n {\n \"op\": \"copy\",\n \"from\": \"/author\",\n \"path\": \"/editor\"\n },\n {\n \"op\": \"test\",\n \"path\": \"/currentState\",\n \"value\": \"proposal\"\n },\n {\n \"op\": \"move\",\n \"from\": \"/currentState\",\n \"path\": \"/previousState\"\n },\n {\n \"op\": \"add\",\n \"path\": \"/currentState\",\n \"value\": \"reviewed\"\n }\n ]'" }, { "lang": "dotnet", "label": "Update metadata instance on file", "source": "await client.FileMetadata.UpdateFileMetadataByIdAsync(fileId: file.Id, scope: UpdateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = \"/name\", Value = \"Jack\" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = \"/age\", Value = 24L },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = \"/birthDate\", Value = \"2000-01-03T02:20:50.520Z\" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = \"/countryCode\", Value = \"CA\" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = \"/sports\", Value = Array.AsReadOnly(new [] {\"football\"}) }}));" }, { "lang": "java", "label": "Update metadata instance on file", "source": "client.getFileMetadata().updateFileMetadataById(file.getId(), UpdateFileMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path(\"/name\").value(\"Jack\").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path(\"/age\").value(24L).build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path(\"/birthDate\").value(\"2000-01-03T02:20:50.520Z\").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path(\"/countryCode\").value(\"CA\").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path(\"/sports\").value(Arrays.asList(\"football\")).build()))" }, { "lang": "node", "label": "Update metadata instance on file", "source": "await client.fileMetadata.updateFileMetadataById(\n file.id,\n 'enterprise' as UpdateFileMetadataByIdScope,\n templateKey,\n [\n {\n op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,\n path: '/name',\n value: 'Jack',\n } satisfies UpdateFileMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,\n path: '/age',\n value: 24,\n } satisfies UpdateFileMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,\n path: '/birthDate',\n value: '2000-01-03T02:20:50.520Z',\n } satisfies UpdateFileMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,\n path: '/countryCode',\n value: 'CA',\n } satisfies UpdateFileMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,\n path: '/sports',\n value: ['football'],\n } satisfies UpdateFileMetadataByIdRequestBody,\n ],\n);" }, { "lang": "python", "label": "Update metadata instance on file", "source": "client.file_metadata.update_file_metadata_by_id(\n file.id,\n UpdateFileMetadataByIdScope.ENTERPRISE,\n template_key,\n [\n UpdateFileMetadataByIdRequestBody(\n op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/name\",\n value=\"Jack\",\n ),\n UpdateFileMetadataByIdRequestBody(\n op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path=\"/age\", value=24\n ),\n UpdateFileMetadataByIdRequestBody(\n op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/birthDate\",\n value=\"2000-01-03T02:20:50.520Z\",\n ),\n UpdateFileMetadataByIdRequestBody(\n op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/countryCode\",\n value=\"CA\",\n ),\n UpdateFileMetadataByIdRequestBody(\n op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/sports\",\n value=[\"football\"],\n ),\n ],\n)" } ] }, "delete": { "operationId": "delete_files_id_metadata_id_id", "summary": "Remove metadata instance from file", "description": "Deletes a piece of file metadata.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "responses": { "204": { "description": "Returns an empty response when the metadata is successfully deleted." }, "400": { "description": "Returned when the request parameters are not valid. This may happen of the `scope` is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this file.\n- `not_found` - The file was not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_metadata", "tags": [ "Metadata instances (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove metadata instance from file", "source": "curl -i -X DELETE \"https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove metadata instance from file", "source": "await client.FileMetadata.DeleteFileMetadataByIdAsync(fileId: file.Id, scope: DeleteFileMetadataByIdScope.Enterprise, templateKey: templateKey);" }, { "lang": "swift", "label": "Remove metadata instance from file", "source": "try await client.fileMetadata.deleteFileMetadataById(fileId: file.id, scope: DeleteFileMetadataByIdScope.global, templateKey: \"properties\")" }, { "lang": "java", "label": "Remove metadata instance from file", "source": "client.getFileMetadata().deleteFileMetadataById(file.getId(), DeleteFileMetadataByIdScope.ENTERPRISE, templateKey)" }, { "lang": "node", "label": "Remove metadata instance from file", "source": "await client.fileMetadata.deleteFileMetadataById(\n file.id,\n 'enterprise' as DeleteFileMetadataByIdScope,\n templateKey,\n);" }, { "lang": "python", "label": "Remove metadata instance from file", "source": "client.file_metadata.delete_file_metadata_by_id(\n file.id, DeleteFileMetadataByIdScope.ENTERPRISE, template_key\n)" } ] } }, "/files/{file_id}/metadata/global/boxSkillsCards": { "get": { "operationId": "get_files_id_metadata_global_boxSkillsCards", "summary": "List Box Skill cards on file", "description": "List the Box Skills metadata cards that are attached to a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return all of the metadata associated to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCardsMetadata" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "skills", "tags": [ "Skills" ], "x-codeSamples": [ { "lang": "curl", "label": "List Box Skill cards on file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards\" \\\n -H \"authorization: Bearer \"" }, { "lang": "java", "label": "List Box Skill cards on file", "source": "client.getSkills().getBoxSkillCardsOnFile(file.getId())" }, { "lang": "node", "label": "List Box Skill cards on file", "source": "await client.skills.getBoxSkillCardsOnFile(file.id);" }, { "lang": "python", "label": "List Box Skill cards on file", "source": "client.skills.get_box_skill_cards_on_file(file.id)" } ] }, "post": { "operationId": "post_files_id_metadata_global_boxSkillsCards", "summary": "Create Box Skill cards on file", "description": "Applies one or more Box Skills metadata cards to a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cards": { "description": "A list of Box Skill cards to apply to this file.", "type": "array", "items": { "$ref": "#/components/schemas/SkillCard" } } }, "required": [ "cards" ] } } } }, "responses": { "201": { "description": "Returns the instance of the template that was applied to the file, including the data that was applied to the template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCardsMetadata" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file or metadata template was not found.\n\n- `not_found` - The file could not be found, or the user does not have access to the file.\n- `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already present on the file.\n\n- `tuple_already_exists` - An instance of them metadata template already exists on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "skills", "tags": [ "Skills" ], "x-codeSamples": [ { "lang": "curl", "label": "Create Box Skill cards on file", "source": "curl -i -X POST \"https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"cards\": [{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"keyword\",\n \"skill_card_title\": {\n \"code\": \"license-plates\",\n \"message\": \"Licence Plates\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"license-plates-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"license-plates-service-123\"\n },\n \"entries\": [\n { \"text\": \"DD-26-YT\" },\n { \"text\": \"DN86 BOX\" }\n ]\n },{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"transcript\",\n \"skill_card_title\": {\n \"code\": \"video-transcription\",\n \"message\": \"Video Transcription\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"video-transcription-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"video-transcription-service-123\"\n },\n \"duration\": 1000,\n \"entries\": [\n {\n \"text\": \"Hi John, have I told you about Box recently?\",\n \"appears\": [{ \"start\": 0 }]\n },\n {\n \"text\": \"No Aaron, you have not. Tell me more!\",\n \"appears\": [{ \"start\": 5 }]\n }\n ]\n },{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"timeline\",\n \"skill_card_title\": {\n \"code\": \"face-detection\",\n \"message\": \"Faces\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"face-detection-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"face-detection-service-123\"\n },\n \"duration\": 1000,\n \"entries\": [\n {\n \"text\": \"John\",\n \"appears\": [{ \"start\": 0, \"end\": 5 }, { \"start\": 10, \"end\": 15 }],\n \"image_url\": \"https://example.com/john.png\"\n },\n {\n \"text\": \"Aaron\",\n \"appears\": [{ \"start\": 5, \"end\": 10 }],\n \"image_url\": \"https://example.com/aaron.png\"\n }\n ]\n },{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"status\",\n \"skill_card_title\": {\n \"code\": \"hold\",\n \"message\": \"Please hold...\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"face-detection-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"face-detection-service-123\"\n },\n \"status\": {\n \"code\": \"processing\",\n \"message\": \"We are processing this file right now.\"\n }\n }]\n }'" }, { "lang": "java", "label": "Create Box Skill cards on file", "source": "client.getSkills().createBoxSkillCardsOnFile(file.getId(), new CreateBoxSkillCardsOnFileRequestBody(cardsToCreate))" }, { "lang": "node", "label": "Create Box Skill cards on file", "source": "await client.skills.createBoxSkillCardsOnFile(file.id, {\n cards: cardsToCreate,\n} satisfies CreateBoxSkillCardsOnFileRequestBody);" }, { "lang": "python", "label": "Create Box Skill cards on file", "source": "client.skills.create_box_skill_cards_on_file(file.id, cards_to_create)" } ] }, "put": { "operationId": "put_files_id_metadata_global_boxSkillsCards", "summary": "Update Box Skill cards on file", "description": "Updates one or more Box Skills metadata cards to a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "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.\n\nThe changes are represented as a JSON array of operation objects.", "type": "array", "items": { "type": "object", "description": "An operation that replaces an existing card.", "properties": { "op": { "description": "The value will always be `replace`.", "type": "string", "example": "replace", "enum": [ "replace" ] }, "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.", "type": "string", "example": "/cards/0" }, "value": { "allOf": [ { "$ref": "#/components/schemas/SkillCard" }, { "description": "The card to insert into the list of cards at the position defined by `path`." } ] } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template, with the custom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillCardsMetadata" } } } }, "404": { "description": "The requested file could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "skills", "tags": [ "Skills" ], "x-codeSamples": [ { "lang": "curl", "label": "Update Box Skill cards on file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[{\n \"op\": \"replace\",\n \"path\": \"/cards/0\",\n \"value\": {\n \"type\": \"skill_card\",\n \"skill_card_type\": \"keyword\",\n \"skill_card_title\": {\n \"code\": \"license-plates\",\n \"message\": \"Licence Plates\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"license-plates-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"license-plates-service-123\"\n },\n \"entries\": [\n { \"text\": \"DD-26-YT\" },\n { \"text\": \"DN86 BOX\" }\n ]\n }\n }]'" }, { "lang": "java", "label": "Update Box Skill cards on file", "source": "client.getSkills().updateBoxSkillCardsOnFile(file.getId(), Arrays.asList(new UpdateBoxSkillCardsOnFileRequestBody.Builder().op(UpdateBoxSkillCardsOnFileRequestBodyOpField.REPLACE).path(\"/cards/0\").value(cardToUpdate).build()))" }, { "lang": "node", "label": "Update Box Skill cards on file", "source": "await client.skills.updateBoxSkillCardsOnFile(file.id, [\n {\n op: 'replace' as UpdateBoxSkillCardsOnFileRequestBodyOpField,\n path: '/cards/0',\n value: cardToUpdate,\n } satisfies UpdateBoxSkillCardsOnFileRequestBody,\n]);" }, { "lang": "python", "label": "Update Box Skill cards on file", "source": "client.skills.update_box_skill_cards_on_file(\n file.id,\n [\n UpdateBoxSkillCardsOnFileRequestBody(\n op=UpdateBoxSkillCardsOnFileRequestBodyOpField.REPLACE,\n path=\"/cards/0\",\n value=card_to_update,\n )\n ],\n)" } ] }, "delete": { "operationId": "delete_files_id_metadata_global_boxSkillsCards", "summary": "Remove Box Skill cards from file", "description": "Removes any Box Skills cards metadata from a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the cards are successfully deleted." }, "404": { "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.\n\n- `instance_not_found` - An instance of the metadata template for Box Skill cards was not found on this file.\n- `not_found` - The file was not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "skills", "tags": [ "Skills" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove Box Skill cards from file", "source": "curl -i -X DELETE \"https://api.box.com/2.0/files/12345/metadata/global/boxSkillsCards\" \\\n -H \"authorization: Bearer \"" }, { "lang": "java", "label": "Remove Box Skill cards from file", "source": "client.getSkills().deleteBoxSkillCardsFromFile(file.getId())" }, { "lang": "node", "label": "Remove Box Skill cards from file", "source": "await client.skills.deleteBoxSkillCardsFromFile(file.id);" }, { "lang": "python", "label": "Remove Box Skill cards from file", "source": "client.skills.delete_box_skill_cards_from_file(file.id)" } ] } }, "/files/{file_id}/watermark": { "get": { "operationId": "get_files_id_watermark", "summary": "Get watermark on file", "description": "Retrieve the watermark for a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "Returns an object containing information about the watermark associated for to this file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "404": { "description": "Returns an error if the file does not have a watermark applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_watermarks", "tags": [ "Watermarks (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get watermark on file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/12345/watermark\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get watermark on file", "source": "await client.FileWatermarks.GetFileWatermarkAsync(fileId: file.Id);" }, { "lang": "swift", "label": "Get watermark on file", "source": "try await client.fileWatermarks.getFileWatermark(fileId: file.id)" }, { "lang": "java", "label": "Get watermark on file", "source": "client.getFileWatermarks().getFileWatermark(file.getId())" }, { "lang": "node", "label": "Get watermark on file", "source": "await client.fileWatermarks.getFileWatermark(file.id);" }, { "lang": "python", "label": "Get watermark on file", "source": "client.file_watermarks.get_file_watermark(file.id)" } ] }, "put": { "operationId": "put_files_id_watermark", "summary": "Apply watermark to file", "description": "Applies or update a watermark on a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "watermark": { "description": "The watermark to imprint on the file.", "type": "object", "properties": { "imprint": { "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "type": "string", "example": "default", "enum": [ "default" ] } }, "required": [ "imprint" ] } }, "required": [ "watermark" ] } } } }, "responses": { "200": { "description": "Returns an updated watermark if a watermark already existed on this file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "201": { "description": "Returns a new watermark if no watermark existed on this file yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_watermarks", "tags": [ "Watermarks (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Apply watermark to file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/12345/watermark\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"watermark\": {\n \"imprint\": \"default\"\n }\n }'" }, { "lang": "dotnet", "label": "Apply watermark to file", "source": "await client.FileWatermarks.UpdateFileWatermarkAsync(fileId: file.Id, requestBody: new UpdateFileWatermarkRequestBody(watermark: new UpdateFileWatermarkRequestBodyWatermarkField(imprint: UpdateFileWatermarkRequestBodyWatermarkImprintField.Default)));" }, { "lang": "swift", "label": "Apply watermark to file", "source": "try await client.fileWatermarks.updateFileWatermark(fileId: file.id, requestBody: UpdateFileWatermarkRequestBody(watermark: UpdateFileWatermarkRequestBodyWatermarkField(imprint: UpdateFileWatermarkRequestBodyWatermarkImprintField.default_)))" }, { "lang": "java", "label": "Apply watermark to file", "source": "client.getFileWatermarks().updateFileWatermark(file.getId(), new UpdateFileWatermarkRequestBody(new UpdateFileWatermarkRequestBodyWatermarkField.Builder().imprint(UpdateFileWatermarkRequestBodyWatermarkImprintField.DEFAULT).build()))" }, { "lang": "node", "label": "Apply watermark to file", "source": "await client.fileWatermarks.updateFileWatermark(file.id, {\n watermark: new UpdateFileWatermarkRequestBodyWatermarkField({\n imprint: 'default' as UpdateFileWatermarkRequestBodyWatermarkImprintField,\n }),\n} satisfies UpdateFileWatermarkRequestBody);" }, { "lang": "python", "label": "Apply watermark to file", "source": "client.file_watermarks.update_file_watermark(\n file.id,\n UpdateFileWatermarkWatermark(\n imprint=UpdateFileWatermarkWatermarkImprintField.DEFAULT\n ),\n)" } ] }, "delete": { "operationId": "delete_files_id_watermark", "summary": "Remove watermark from file", "description": "Removes the watermark from a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Removes the watermark and returns an empty response." }, "404": { "description": "Returns an error if the file did not have a watermark applied to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_watermarks", "tags": [ "Watermarks (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove watermark from file", "source": "curl -i -X DELETE \"https://api.box.com/2.0/files/12345/watermark\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove watermark from file", "source": "await client.FileWatermarks.DeleteFileWatermarkAsync(fileId: file.Id);" }, { "lang": "swift", "label": "Remove watermark from file", "source": "try await client.fileWatermarks.deleteFileWatermark(fileId: file.id)" }, { "lang": "java", "label": "Remove watermark from file", "source": "client.getFileWatermarks().deleteFileWatermark(file.getId())" }, { "lang": "node", "label": "Remove watermark from file", "source": "await client.fileWatermarks.deleteFileWatermark(file.id);" }, { "lang": "python", "label": "Remove watermark from file", "source": "client.file_watermarks.delete_file_watermark(file.id)" } ] } }, "/file_requests/{file_request_id}": { "get": { "operationId": "get_file_requests_id", "summary": "Get file request", "description": "Retrieves the information about a file request.", "parameters": [ { "name": "file_request_id", "in": "path", "description": "The unique identifier that represent a file request.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "123" } ], "responses": { "200": { "description": "Returns a file request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file request is not found, or the user does not have access to the associated folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_requests", "tags": [ "File requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Get file request", "source": "curl -i -X GET \"https://api.box.com/2.0/file_requests/42037322\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get file request", "source": "await client.FileRequests.GetFileRequestByIdAsync(fileRequestId: fileRequestId);" }, { "lang": "swift", "label": "Get file request", "source": "try await client.fileRequests.getFileRequestById(fileRequestId: fileRequestId)" }, { "lang": "java", "label": "Get file request", "source": "client.getFileRequests().getFileRequestById(fileRequestId)" }, { "lang": "node", "label": "Get file request", "source": "await client.fileRequests.getFileRequestById(fileRequestId);" }, { "lang": "python", "label": "Get file request", "source": "client.file_requests.get_file_request_by_id(file_request_id)" } ] }, "put": { "operationId": "put_file_requests_id", "summary": "Update file request", "description": "Updates a file request. This can be used to activate or deactivate a file request.", "parameters": [ { "name": "file_request_id", "in": "path", "description": "The unique identifier that represent a file request.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "123" }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequestUpdateRequest" } } } }, "responses": { "200": { "description": "Returns the updated file request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.\n\n- `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file request is not found, or the user does not have access to the associated folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_requests", "tags": [ "File requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Update file request", "source": "curl -i -X PUT \"https://api.box.com/2.0/file_requests/42037322\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"title\": \"Please upload required documents\",\n \"description\": \"Please upload required documents\",\n \"status\": \"active\",\n \"is_email_required\": true,\n \"is_description_required\": false\n }'" }, { "lang": "dotnet", "label": "Update file request", "source": "await client.FileRequests.UpdateFileRequestByIdAsync(fileRequestId: copiedFileRequest.Id, requestBody: new FileRequestUpdateRequest() { Title = \"updated title\", Description = \"updated description\" });" }, { "lang": "swift", "label": "Update file request", "source": "try await client.fileRequests.updateFileRequestById(fileRequestId: copiedFileRequest.id, requestBody: FileRequestUpdateRequest(title: \"updated title\", description: \"updated description\"))" }, { "lang": "java", "label": "Update file request", "source": "client.getFileRequests().updateFileRequestById(copiedFileRequest.getId(), new FileRequestUpdateRequest.Builder().title(\"updated title\").description(\"updated description\").build())" }, { "lang": "node", "label": "Update file request", "source": "await client.fileRequests.updateFileRequestById(copiedFileRequest.id, {\n title: 'updated title',\n description: 'updated description',\n} satisfies FileRequestUpdateRequest);" }, { "lang": "python", "label": "Update file request", "source": "client.file_requests.update_file_request_by_id(\n copied_file_request.id, title=\"updated title\", description=\"updated description\"\n)" } ] }, "delete": { "operationId": "delete_file_requests_id", "summary": "Delete file request", "description": "Deletes a file request permanently.", "parameters": [ { "name": "file_request_id", "in": "path", "description": "The unique identifier that represent a file request.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "123" } ], "responses": { "204": { "description": "Returns an empty response when the file request has been successfully deleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_requests", "tags": [ "File requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete file request", "source": "curl -i -X DELETE \"https://api.box.com/2.0/file_requests/42037322\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete file request", "source": "await client.FileRequests.DeleteFileRequestByIdAsync(fileRequestId: updatedFileRequest.Id);" }, { "lang": "swift", "label": "Delete file request", "source": "try await client.fileRequests.deleteFileRequestById(fileRequestId: updatedFileRequest.id)" }, { "lang": "java", "label": "Delete file request", "source": "client.getFileRequests().deleteFileRequestById(updatedFileRequest.getId())" }, { "lang": "node", "label": "Delete file request", "source": "await client.fileRequests.deleteFileRequestById(updatedFileRequest.id);" }, { "lang": "python", "label": "Delete file request", "source": "client.file_requests.delete_file_request_by_id(updated_file_request.id)" } ] } }, "/file_requests/{file_request_id}/copy": { "post": { "operationId": "post_file_requests_id_copy", "summary": "Copy file request", "description": "Copies an existing file request that is already present on one folder, and applies it to another folder.", "parameters": [ { "name": "file_request_id", "in": "path", "description": "The unique identifier that represent a file request.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "123" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequestCopyRequest" } } } }, "responses": { "200": { "description": "Returns updated file request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileRequest" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.\n\n- `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file request is not found, or the user does not have access to the associated folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_requests", "tags": [ "File requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Copy file request", "source": "curl -i -X POST \"https://api.box.com/2.0/file_requests/42037322/copy\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"title\": \"Please upload required documents\",\n \"description\": \"Please upload required documents\",\n \"status\": \"active\",\n \"is_email_required\": true,\n \"is_description_required\": false,\n \"folder\": {\n \"id\": \"2233212\",\n \"type\": \"folder\"\n }\n }'" }, { "lang": "dotnet", "label": "Copy file request", "source": "await client.FileRequests.CreateFileRequestCopyAsync(fileRequestId: fileRequestId, requestBody: new FileRequestCopyRequest(folder: new FileRequestCopyRequestFolderField(id: fileRequest.Folder.Id) { Type = FileRequestCopyRequestFolderTypeField.Folder }));" }, { "lang": "swift", "label": "Copy file request", "source": "try await client.fileRequests.createFileRequestCopy(fileRequestId: fileRequestId, requestBody: FileRequestCopyRequest(folder: FileRequestCopyRequestFolderField(id: fileRequest.folder.id, type: FileRequestCopyRequestFolderTypeField.folder)))" }, { "lang": "java", "label": "Copy file request", "source": "client.getFileRequests().createFileRequestCopy(fileRequestId, new FileRequestCopyRequest(new FileRequestCopyRequestFolderField.Builder(fileRequest.getFolder().getId()).type(FileRequestCopyRequestFolderTypeField.FOLDER).build()))" }, { "lang": "node", "label": "Copy file request", "source": "await client.fileRequests.createFileRequestCopy(fileRequestId, {\n folder: {\n id: fileRequest.folder.id,\n type: 'folder' as FileRequestCopyRequestFolderTypeField,\n } satisfies FileRequestCopyRequestFolderField,\n} satisfies FileRequestCopyRequest);" }, { "lang": "python", "label": "Copy file request", "source": "client.file_requests.create_file_request_copy(\n file_request_id,\n CreateFileRequestCopyFolder(\n id=file_request.folder.id, type=CreateFileRequestCopyFolderTypeField.FOLDER\n ),\n)" } ] } }, "/folders/{folder_id}": { "get": { "operationId": "get_folders_id", "summary": "Get folder information", "description": "Retrieves details for a folder, including the first 100 entries in the folder.\n\nPassing `sort`, `direction`, `offset`, and `limit` parameters in query allows you to manage the list of returned [folder items](/reference/resources/folder--full#param-item-collection).\n\nTo fetch more items within the folder, use the [Get items in a folder](/reference/get-folders-id-items) endpoint.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.\n\nAdditionally 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 `?fields=metadata.enterprise_12345.contractTemplate`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "if-none-match", "in": "header", "description": "Ensures an item is only returned if it has changed.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "boxapi", "in": "header", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been explicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files or folders nested within the item.", "required": false, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" }, { "name": "sort", "in": "query", "description": "Defines the **second** attribute by which items are sorted.\n\nThe folder type affects the way the items are sorted:\n\n- **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links.\n\n- **Root folder**: This parameter is not supported for marker-based pagination on the root folder\n\n(the folder with an `id` of `0`).\n\n- **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links.", "required": false, "schema": { "type": "string", "enum": [ "id", "name", "date", "size" ] }, "example": "id" }, { "name": "direction", "in": "query", "description": "The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order.", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nOffset-based pagination is not guaranteed to work reliably for high offset values and may fail for large datasets. In those cases, reduce the number of items in the folder (for example, by restructuring the folder into smaller subfolders) before retrying the request.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the _folder items list_ will be affected accordingly.\n\nTo fetch more items within the folder, use the [Get items in a folder](/reference/get-folders-id-items)) endpoint.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "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": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folders", "tags": [ "Folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Get folder information", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/4353455\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get folder information", "source": "await client.Folders.GetFolderByIdAsync(folderId: \"0\");" }, { "lang": "swift", "label": "Get folder information", "source": "try await client.folders.getFolderById(folderId: \"0\")" }, { "lang": "java", "label": "Get folder information", "source": "client.getFolders().getFolderById(\"0\")" }, { "lang": "node", "label": "Get folder information", "source": "await client.folders.getFolderById('0');" }, { "lang": "python", "label": "Get folder information", "source": "client.folders.get_folder_by_id(\"0\")" } ] }, "post": { "operationId": "post_folders_id", "summary": "Restore folder", "description": "Restores a folder that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the folder to in case the original folder has been deleted.\n\nDuring 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.\n\nFor the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the folder.", "type": "string", "example": "Restored Photos" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item.", "properties": { "id": { "description": "The ID of parent item.", "type": "string", "example": "123" } } }, { "description": "Specifies an optional ID of a folder to restore the folder to when the original folder no longer exists.\n\nPlease 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." } ] } } } } } }, "responses": { "201": { "description": "Returns a folder object when the folder has been restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFolderRestored" } } } }, "403": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the folder is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returned an error if there is a folder with the same name in the destination folder.\n\n`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.\n\nThe operation can be retried at a later point.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_folders", "tags": [ "Trashed folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Restore folder", "source": "curl -i -X POST \"https://api.box.com/2.0/folders/4353455\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Restore folder", "source": "await client.TrashedFolders.RestoreFolderFromTrashAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "Restore folder", "source": "try await client.trashedFolders.restoreFolderFromTrash(folderId: folder.id)" }, { "lang": "java", "label": "Restore folder", "source": "client.getTrashedFolders().restoreFolderFromTrash(folder.getId())" }, { "lang": "node", "label": "Restore folder", "source": "await client.trashedFolders.restoreFolderFromTrash(folder.id);" }, { "lang": "python", "label": "Restore folder", "source": "client.trashed_folders.restore_folder_from_trash(folder.id)" } ] }, "put": { "operationId": "put_folders_id", "summary": "Update folder", "description": "Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The optional new name for this folder.\n\nThe following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\\`), names with trailing spaces, and names `.` and `..` are not allowed.\n\nFolder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`.", "type": "string", "example": "New Folder" }, "description": { "description": "The optional description of this folder.", "type": "string", "example": "Legal contracts for the new ACME deal", "maxLength": 256, "nullable": false }, "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.", "type": "string", "example": "synced", "enum": [ "synced", "not_synced", "partially_synced" ], "nullable": false }, "can_non_owners_invite": { "description": "Specifies if users who are not the owner of the folder can invite new collaborators to the folder.", "type": "boolean", "example": true }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item.", "properties": { "id": { "description": "The ID of parent item.", "type": "string", "example": "123" }, "user_id": { "description": "The input for `user_id` is optional. Moving to non-root folder is not allowed when `user_id` is present. Parent folder id should be zero when `user_id` is provided.", "type": "string", "example": "12346930" } } }, { "description": "The parent folder for this folder. Use this to move the folder or to restore it out of the trash." } ] }, "shared_link": { "allOf": [ { "description": "Defines a shared link for an item. Set this to `null` to remove the shared link.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link" }, "unshared_at": { "description": "The timestamp at which this shared link will expire. This field can only be set by users with paid accounts.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true } } } } }, { "description": "Enables the creation of a shared link for a folder." } ] }, "folder_upload_email": { "allOf": [ { "title": "Folder upload email", "type": "object", "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.\n\nTo create an email address, set this property either when creating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email address.", "type": "string", "example": "open", "enum": [ "open", "collaborators" ], "nullable": false } } }, { "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly upload files directly to the folder via email.\n\nSetting the value to `null` will disable the email address." } ], "nullable": true }, "tags": { "description": "The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags, modify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000 unique tags per enterprise.", "type": "array", "items": { "type": "string" }, "example": [ "approved" ], "maxItems": 100, "minItems": 1 }, "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.", "type": "boolean", "example": true }, "collections": { "description": "An array of collections to make this folder a member of. Currently we only support the `favorites` collection.\n\nTo get the ID for a collection, use the [List all collections][1] endpoint.\n\nPassing an empty array `[]` or `null` will remove the folder from all collections.\n\n[1]: /reference/get-collections", "type": "array", "items": { "title": "Reference", "description": "The bare basic reference for an object.", "type": "object", "properties": { "id": { "description": "The unique identifier for this object.", "type": "string", "example": "11446498" }, "type": { "description": "The type for this object.", "type": "string", "example": "file" } } }, "nullable": true }, "can_non_owners_view_collaborators": { "description": "Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder.\n\nIt also restricts non-owners from inviting new collaborators.\n\nWhen 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.", "type": "boolean", "example": true } } } } } }, "responses": { "200": { "description": "Returns a folder object for the updated folder\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.\n\nIf the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid, or if a folder lock is preventing a move operation.\n\n- `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`.\n- `item_name_too_long` when the folder name is too long.\n- `item_name_invalid` when the folder name contains non-valid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the user does not have the required access to perform the action.\n\n- `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.\n\n- `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.\n\n- `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.\n\n- `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions.\n\nReturns an error if there are too many actions in the request body.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `not_found` when the authenticated user does not have access to the folder or parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "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.\n\nThe operation can be retried at a later point.\n\n`item_name_in_use`: Returned if a folder with the name already exists in the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error when the operation takes longer than 600 seconds. The operation will continue after this response has been returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folders", "tags": [ "Folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Update folder", "source": "curl -i -X PUT \"https://api.box.com/2.0/folders/4353455\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"New folder name\"\n }'" }, { "lang": "dotnet", "label": "Update folder", "source": "await client.Folders.UpdateFolderByIdAsync(folderId: folderToUpdate.Id, requestBody: new UpdateFolderByIdRequestBody() { Name = updatedName, Description = \"Updated description\" });" }, { "lang": "swift", "label": "Update folder", "source": "try await client.folders.updateFolderById(folderId: folderToUpdate.id, requestBody: UpdateFolderByIdRequestBody(name: updatedName, description: \"Updated description\"))" }, { "lang": "java", "label": "Update folder", "source": "client.getFolders().updateFolderById(folderToUpdate.getId(), new UpdateFolderByIdRequestBody.Builder().name(updatedName).description(\"Updated description\").build())" }, { "lang": "node", "label": "Update folder", "source": "await client.folders.updateFolderById(folderToUpdate.id, {\n requestBody: {\n name: updatedName,\n description: 'Updated description',\n } satisfies UpdateFolderByIdRequestBody,\n} satisfies UpdateFolderByIdOptionalsInput);" }, { "lang": "python", "label": "Update folder", "source": "client.folders.update_folder_by_id(\n folder_to_update.id, name=updated_name, description=\"Updated description\"\n)" } ] }, "delete": { "operationId": "delete_folders_id", "summary": "Delete folder", "description": "Deletes a folder, either permanently or by moving it to the trash.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "if-match", "in": "header", "description": "Ensures this item hasn't recently changed before making changes.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "recursive", "in": "query", "description": "Delete a folder that is not empty by recursively deleting the folder and all of its content.", "required": false, "schema": { "type": "boolean" }, "example": true } ], "responses": { "204": { "description": "Returns an empty response when the folder is successfully deleted or moved to the trash." }, "400": { "description": "Returns an error if the user makes a bad request.\n\n- `folder_not_empty`: Returned if the folder is not empty. Use the `recursive` query parameter to recursively delete the folder and its contents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the user does not have the required access to perform the action.\n\n- `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.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the folder could not be found, or the authenticated user does not have access to the folder.\n\n- `not_found` when the authenticated user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "`operation_blocked_temporary`: Returned if the folder is locked due to another move, copy, delete or restore operation in progress.\n\nThe operation can be retried at a later point.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error when the operation takes longer than 600 seconds. The operation will continue after this response has been returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folders", "tags": [ "Folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete folder", "source": "curl -i -X DELETE \"https://api.box.com/2.0/folders/4353455\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete folder", "source": "await client.Folders.DeleteFolderByIdAsync(folderId: newFolder.Id);" }, { "lang": "swift", "label": "Delete folder", "source": "try await client.folders.deleteFolderById(folderId: newFolder.id)" }, { "lang": "java", "label": "Delete folder", "source": "client.getFolders().deleteFolderById(newFolder.getId())" }, { "lang": "node", "label": "Delete folder", "source": "await client.folders.deleteFolderById(newFolder.id);" }, { "lang": "python", "label": "Delete folder", "source": "client.folders.delete_folder_by_id(new_folder.id)" } ] } }, "/folders/{folder_id}/app_item_associations": { "get": { "operationId": "get_folders_id_app_item_associations", "summary": "List folder app item associations", "description": "**This is a beta feature, which means that its availability might be limited.** Returns all app items the folder is associated with. This includes app items associated with ancestors of the folder. Assuming the context user has access to the folder, the type/ids are revealed even if the context user does not have **View** permission on the app item.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "application_type", "in": "query", "description": "If given, returns only app items for this application type.", "required": false, "schema": { "type": "string", "nullable": false }, "example": "hubs" } ], "responses": { "200": { "description": "Returns a collection of app item objects. If there are no app items on this folder an empty collection will be returned. This list includes app items on ancestors of this folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppItemAssociations" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "app_item_associations", "tags": [ "App item associations" ], "x-codeSamples": [ { "lang": "curl", "label": "List folder app item associations", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/12345/app_item_associations\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List folder app item associations", "source": "await client.AppItemAssociations.GetFolderAppItemAssociationsAsync(folderId: folderId);" }, { "lang": "swift", "label": "List folder app item associations", "source": "try await client.appItemAssociations.getFolderAppItemAssociations(folderId: folderId)" }, { "lang": "java", "label": "List folder app item associations", "source": "client.getAppItemAssociations().getFolderAppItemAssociations(folderId)" }, { "lang": "node", "label": "List folder app item associations", "source": "await client.appItemAssociations.getFolderAppItemAssociations(folderId);" }, { "lang": "python", "label": "List folder app item associations", "source": "client.app_item_associations.get_folder_app_item_associations(folder_id)" } ] } }, "/folders/{folder_id}/items": { "get": { "operationId": "get_folders_id_items", "summary": "List items in folder", "description": "Retrieves a page of items in a folder. These items can be files, folders, and web links.\n\nTo request more information about the folder itself, like its size, use the [Get a folder](/reference/get-folders-id) endpoint instead.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.\n\nAdditionally 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 `?fields=metadata.enterprise_12345.contractTemplate`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "usemarker", "in": "query", "description": "Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time.\n\nBy 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.", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nOffset-based pagination is not guaranteed to work reliably for high offset values and may fail for large datasets. In those cases, use marker-based pagination by setting `usemarker` to `true`.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "boxapi", "in": "header", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been explicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files or folders nested within the item.", "required": false, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" }, { "name": "sort", "in": "query", "description": "Defines the **second** attribute by which items are sorted.\n\nThe folder type affects the way the items are sorted:\n\n- **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links.\n\n- **Root folder**: This parameter is not supported for marker-based pagination on the root folder\n\n(the folder with an `id` of `0`).\n\n- **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links.", "required": false, "schema": { "type": "string", "enum": [ "id", "name", "date", "size" ] }, "example": "id" }, { "name": "direction", "in": "query", "description": "The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order.", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" } ], "responses": { "200": { "description": "Returns a collection of files, folders, and web links contained in a folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items" } } } }, "403": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folders", "tags": [ "Folders" ], "x-codeSamples": [ { "lang": "curl", "label": "List items in folder", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/0/items\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List items in folder", "source": "await client.Folders.GetFolderItemsAsync(folderId: folderOrigin.Id);" }, { "lang": "swift", "label": "List items in folder", "source": "try await client.folders.getFolderItems(folderId: folderOrigin.id)" }, { "lang": "java", "label": "List items in folder", "source": "client.getFolders().getFolderItems(folderOrigin.getId())" }, { "lang": "node", "label": "List items in folder", "source": "await client.folders.getFolderItems(folderOrigin.id);" }, { "lang": "python", "label": "List items in folder", "source": "client.folders.get_folder_items(folder_origin.id)" } ] } }, "/folders": { "post": { "operationId": "post_folders", "summary": "Create folder", "description": "Creates a new empty folder within the specified parent folder.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name for the new folder.\n\nThe following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\\`), names with trailing spaces, and names `.` and `..` are not allowed.\n\nFolder names must be unique within their parent folder. The name check is case-insensitive, so a folder named `New Folder` cannot be created in a parent folder that already contains a folder named `new folder`.", "type": "string", "example": "New Folder", "maxLength": 255, "minLength": 1 }, "parent": { "description": "The parent folder to create the new folder within.", "type": "object", "properties": { "id": { "description": "The ID of parent folder.", "type": "string", "example": "0" } }, "required": [ "id" ] }, "folder_upload_email": { "allOf": [ { "title": "Folder upload email", "type": "object", "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.\n\nTo create an email address, set this property either when creating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email address.", "type": "string", "example": "open", "enum": [ "open", "collaborators" ], "nullable": false } } }, { "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly upload files directly to the folder via email." } ] }, "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.", "type": "string", "example": "synced", "enum": [ "synced", "not_synced", "partially_synced" ], "nullable": false } }, "required": [ "name", "parent" ] } } } }, "responses": { "201": { "description": "Returns a folder object.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `bad_request` when a parameter is missing or incorrect.\n- `item_name_too_long` when the folder name is too long.\n- `item_name_invalid` when the folder name contains non-valid characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the parent folder could not be found, or the authenticated user does not have access to the parent folder.\n\n- `not_found` when the authenticated user does not have access to the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "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.\n\nThe operation can be retried at a later point.\n\n`item_name_in_use`: Returned if a folder with the name already exists in the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folders", "tags": [ "Folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Create folder", "source": "curl -i -X POST \"https://api.box.com/2.0/folders\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"New Folder\",\n \"parent\": {\n \"id\": \"0\"\n }\n }'" }, { "lang": "dotnet", "label": "Create folder", "source": "await client.Folders.CreateFolderAsync(requestBody: new CreateFolderRequestBody(name: newFolderName, parent: new CreateFolderRequestBodyParentField(id: \"0\")));" }, { "lang": "swift", "label": "Create folder", "source": "try await client.folders.createFolder(requestBody: CreateFolderRequestBody(name: newFolderName, parent: CreateFolderRequestBodyParentField(id: \"0\")))" }, { "lang": "java", "label": "Create folder", "source": "client.getFolders().createFolder(new CreateFolderRequestBody(newFolderName, new CreateFolderRequestBodyParentField(\"0\")))" }, { "lang": "node", "label": "Create folder", "source": "await client.folders.createFolder({\n name: newFolderName,\n parent: { id: '0' } satisfies CreateFolderRequestBodyParentField,\n} satisfies CreateFolderRequestBody);" }, { "lang": "python", "label": "Create folder", "source": "client.folders.create_folder(new_folder_name, CreateFolderParent(id=\"0\"))" } ] } }, "/folders/{folder_id}/copy": { "post": { "operationId": "post_folders_id_copy", "summary": "Copy folder", "description": "Creates a copy of a folder within a destination folder.\n\nThe original folder will not be changed.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier of the folder to copy.\n\nThe 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`.\n\nThe root folder with the ID `0` can not be copied.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "0" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the copied folder.\n\nThere 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.\n\nAdditionally, the names `.` and `..` are not allowed either.", "type": "string", "example": "New Folder", "maxLength": 255, "minLength": 1 }, "parent": { "description": "The destination folder to copy the folder to.", "type": "object", "properties": { "id": { "description": "The ID of parent folder.", "type": "string", "example": "0" } }, "required": [ "id" ] } }, "nullable": false, "required": [ "parent" ] } } } }, "responses": { "201": { "description": "Returns a new folder object representing the copied folder.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "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": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `bad_request` when a parameter is missing.\n- `item_name_too_long` when the new folder name is too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the right permissions to copy a folder.\n\n- `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `not_found` when the authenticated user does not have access to the parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a folder by this name already exists in the destination folder, or if the destination folder is locked.\n\n- `item_name_in_use` when a folder with the same name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error when trying to copy the root folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folders", "tags": [ "Folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Copy folder", "source": "curl -i -X POST \"https://api.box.com/2.0/folders/4353455/copy\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"parent\": {\n \"id\": \"345345\"\n }\n }'" }, { "lang": "dotnet", "label": "Copy folder", "source": "await client.Folders.CopyFolderAsync(folderId: folderOrigin.Id, requestBody: new CopyFolderRequestBody(parent: new CopyFolderRequestBodyParentField(id: \"0\")) { Name = copiedFolderName });" }, { "lang": "swift", "label": "Copy folder", "source": "try await client.folders.copyFolder(folderId: folderOrigin.id, requestBody: CopyFolderRequestBody(parent: CopyFolderRequestBodyParentField(id: \"0\"), name: copiedFolderName))" }, { "lang": "java", "label": "Copy folder", "source": "client.getFolders().copyFolder(folderOrigin.getId(), new CopyFolderRequestBody.Builder(new CopyFolderRequestBodyParentField(\"0\")).name(copiedFolderName).build())" }, { "lang": "node", "label": "Copy folder", "source": "await client.folders.copyFolder(folderOrigin.id, {\n parent: { id: '0' } satisfies CopyFolderRequestBodyParentField,\n name: copiedFolderName,\n} satisfies CopyFolderRequestBody);" }, { "lang": "python", "label": "Copy folder", "source": "client.folders.copy_folder(\n folder_origin.id, CopyFolderParent(id=\"0\"), name=copied_folder_name\n)" } ] } }, "/folders/{folder_id}/collaborations": { "get": { "operationId": "get_folders_id_collaborations", "summary": "List folder collaborations", "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.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned.\n\nThis list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaborations" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "list_collaborations", "tags": [ "Collaborations (List)" ], "x-codeSamples": [ { "lang": "curl", "label": "List folder collaborations", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/4353455/collaborations\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List folder collaborations", "source": "await client.ListCollaborations.GetFolderCollaborationsAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "List folder collaborations", "source": "try await client.listCollaborations.getFolderCollaborations(folderId: folder.id)" }, { "lang": "java", "label": "List folder collaborations", "source": "client.getListCollaborations().getFolderCollaborations(folder.getId())" }, { "lang": "node", "label": "List folder collaborations", "source": "await client.listCollaborations.getFolderCollaborations(folder.id);" }, { "lang": "python", "label": "List folder collaborations", "source": "client.list_collaborations.get_folder_collaborations(folder.id)" } ] } }, "/folders/{folder_id}/trash": { "get": { "operationId": "get_folders_id_trash", "summary": "Get trashed folder", "description": "Retrieves a folder that has been moved to the trash.\n\nPlease 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`](/reference/get-folders-id-trash) API.\n\nTo list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](/reference/get-folders-trash-items/) API.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the folder that was trashed, including information about when the it was moved to the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashFolder" } } } }, "404": { "description": "Returns an error if the folder can not be found directly in the trash.\n\nPlease note that a `HTTP 404` is also returned if any of the folder's parent folders have been moved to the trash.\n\nIn that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](/reference/get-folders-id-trash) API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_folders", "tags": [ "Trashed folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Get trashed folder", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/4353455/trash\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get trashed folder", "source": "await client.TrashedFolders.GetTrashedFolderByIdAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "Get trashed folder", "source": "try await client.trashedFolders.getTrashedFolderById(folderId: folder.id)" }, { "lang": "java", "label": "Get trashed folder", "source": "client.getTrashedFolders().getTrashedFolderById(folder.getId())" }, { "lang": "node", "label": "Get trashed folder", "source": "await client.trashedFolders.getTrashedFolderById(folder.id);" }, { "lang": "python", "label": "Get trashed folder", "source": "client.trashed_folders.get_trashed_folder_by_id(folder.id)" } ] }, "delete": { "operationId": "delete_folders_id_trash", "summary": "Permanently remove folder", "description": "Permanently deletes a folder that is in the trash. This action cannot be undone.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the folder was permanently deleted." }, "404": { "description": "Returns an error if the folder is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_folders", "tags": [ "Trashed folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Permanently remove folder", "source": "curl -i -X DELETE \"https://api.box.com/2.0/folders/4353455/trash\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Permanently remove folder", "source": "await client.TrashedFolders.DeleteTrashedFolderByIdAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "Permanently remove folder", "source": "try await client.trashedFolders.deleteTrashedFolderById(folderId: folder.id)" }, { "lang": "java", "label": "Permanently remove folder", "source": "client.getTrashedFolders().deleteTrashedFolderById(folder.getId())" }, { "lang": "node", "label": "Permanently remove folder", "source": "await client.trashedFolders.deleteTrashedFolderById(folder.id);" }, { "lang": "python", "label": "Permanently remove folder", "source": "client.trashed_folders.delete_trashed_folder_by_id(folder.id)" } ] } }, "/folders/{folder_id}/metadata": { "get": { "operationId": "get_folders_id_metadata", "summary": "List metadata instances on folder", "description": "Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "view", "in": "query", "description": "Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter.", "required": false, "schema": { "type": "string" }, "example": "hydrated" } ], "responses": { "200": { "description": "Returns all the metadata associated with a folder.\n\nThis API does not support pagination and will therefore always return all of the metadata associated to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadatas" } } } }, "403": { "description": "Returned when the request parameters are not valid.\n\n- `forbidden` - this operation is not allowed on the Root folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_metadata", "tags": [ "Metadata instances (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "List metadata instances on folder", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/4353455/metadata\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List metadata instances on folder", "source": "await client.FolderMetadata.GetFolderMetadataAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "List metadata instances on folder", "source": "try await client.folderMetadata.getFolderMetadata(folderId: folder.id)" }, { "lang": "java", "label": "List metadata instances on folder", "source": "client.getFolderMetadata().getFolderMetadata(folder.getId())" }, { "lang": "node", "label": "List metadata instances on folder", "source": "await client.folderMetadata.getFolderMetadata(folder.id);" }, { "lang": "python", "label": "List metadata instances on folder", "source": "client.folder_metadata.get_folder_metadata(folder.id)" } ] } }, "/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { "get": { "operationId": "get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Get classification on folder", "description": "Retrieves the classification metadata instance that has been applied to a folder.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "responses": { "200": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder.\n\n- `instance_not_found` - The metadata template was not applied to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_classifications", "tags": [ "Classifications on folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Get classification on folder", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get classification on folder", "source": "await client.FolderClassifications.GetClassificationOnFolderAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "Get classification on folder", "source": "try await client.folderClassifications.getClassificationOnFolder(folderId: folder.id)" }, { "lang": "java", "label": "Get classification on folder", "source": "client.getFolderClassifications().getClassificationOnFolder(folder.getId())" }, { "lang": "node", "label": "Get classification on folder", "source": "await client.folderClassifications.getClassificationOnFolder(folder.id);" }, { "lang": "python", "label": "Get classification on folder", "source": "client.folder_classifications.get_classification_on_folder(folder.id)" } ] }, "post": { "operationId": "post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to folder", "description": "Adds a classification to a folder by specifying the label of the classification to add.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Box__Security__Classification__Key": { "description": "The name of the classification to apply to this folder.\n\nTo list the available classifications in an enterprise, use the classification API to retrieve the [classification template](/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema) which lists all available classification keys.", "type": "string", "example": "Sensitive" } } } } } }, "responses": { "201": { "description": "Returns the classification template instance that was applied to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder or metadata template was not found.\n\n- `not_found` - The folder could not be found, or the user does not have access to the folder.\n- `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already present on the folder.\n\n- `tuple_already_exists` - An instance of them metadata template already exists on the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_classifications", "tags": [ "Classifications on folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Add classification to folder", "source": "curl -i -X POST \"https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"Box__Security__Classification__Key\": \"Sensitive\"\n }'" }, { "lang": "dotnet", "label": "Add classification to folder", "source": "await client.FolderClassifications.AddClassificationToFolderAsync(folderId: folder.Id, requestBody: new AddClassificationToFolderRequestBody() { BoxSecurityClassificationKey = classification.Key });" }, { "lang": "swift", "label": "Add classification to folder", "source": "try await client.folderClassifications.addClassificationToFolder(folderId: folder.id, requestBody: AddClassificationToFolderRequestBody(boxSecurityClassificationKey: classification.key))" }, { "lang": "java", "label": "Add classification to folder", "source": "client.getFolderClassifications().addClassificationToFolder(folder.getId(), new AddClassificationToFolderRequestBody.Builder().boxSecurityClassificationKey(classification.getKey()).build())" }, { "lang": "node", "label": "Add classification to folder", "source": "await client.folderClassifications.addClassificationToFolder(folder.id, {\n requestBody: {\n boxSecurityClassificationKey: classification.key,\n } satisfies AddClassificationToFolderRequestBody,\n} satisfies AddClassificationToFolderOptionalsInput);" }, { "lang": "python", "label": "Add classification to folder", "source": "client.folder_classifications.add_classification_to_folder(\n folder.id, box_security_classification_key=classification.key\n)" } ] }, "put": { "operationId": "put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on folder", "description": "Updates a classification on a folder.\n\nThe 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.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "A list containing the one change to make, to update the classification label.", "type": "array", "items": { "type": "object", "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.", "required": [ "op", "path", "value" ], "properties": { "op": { "description": "The value will always be `replace`.", "type": "string", "example": "replace", "enum": [ "replace" ] }, "path": { "description": "Defines classifications available in the enterprise.", "type": "string", "example": "/Box__Security__Classification__Key", "enum": [ "/Box__Security__Classification__Key" ] }, "value": { "description": "The name of the classification to apply to this folder.\n\nTo list the available classifications in an enterprise, use the classification API to retrieve the [classification template](/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema) which lists all available classification keys.", "type": "string", "example": "Sensitive" } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Returns the updated classification metadata template instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Classification" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `bad_request` - The request body format is not an array of valid JSON Patch operations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_classifications", "tags": [ "Classifications on folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Update classification on folder", "source": "curl -i -X PUT \"https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[{\n \"op\": \"replace\",\n \"path\": \"/Box__Security__Classification__Key\",\n \"value\": \"Internal\"\n }]'" }, { "lang": "dotnet", "label": "Update classification on folder", "source": "await client.FolderClassifications.UpdateClassificationOnFolderAsync(folderId: folder.Id, requestBody: Array.AsReadOnly(new [] {new UpdateClassificationOnFolderRequestBody(value: secondClassification.Key)}));" }, { "lang": "swift", "label": "Update classification on folder", "source": "try await client.folderClassifications.updateClassificationOnFolder(folderId: folder.id, requestBody: [UpdateClassificationOnFolderRequestBody(value: secondClassification.key)])" }, { "lang": "java", "label": "Update classification on folder", "source": "client.getFolderClassifications().updateClassificationOnFolder(folder.getId(), Arrays.asList(new UpdateClassificationOnFolderRequestBody(secondClassification.getKey())))" }, { "lang": "node", "label": "Update classification on folder", "source": "await client.folderClassifications.updateClassificationOnFolder(folder.id, [\n new UpdateClassificationOnFolderRequestBody({\n value: secondClassification.key,\n }),\n]);" }, { "lang": "python", "label": "Update classification on folder", "source": "client.folder_classifications.update_classification_on_folder(\n folder.id,\n [UpdateClassificationOnFolderRequestBody(value=second_classification.key)],\n)" } ] }, "delete": { "operationId": "delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from folder", "description": "Removes any classifications from a folder.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the classification is successfully deleted." }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `instance_not_found` - An instance of the classification metadata template with the was not found on this folder.\n- `not_found` - The folder was not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned when the method was not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_classifications", "tags": [ "Classifications on folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove classification from folder", "source": "curl -i -X DELETE \"https://api.box.com/2.0/folders/12345/metadata/enterprise/securityClassification-6VMVochwUWo\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove classification from folder", "source": "await client.FolderClassifications.DeleteClassificationFromFolderAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "Remove classification from folder", "source": "try await client.folderClassifications.deleteClassificationFromFolder(folderId: folder.id)" }, { "lang": "java", "label": "Remove classification from folder", "source": "client.getFolderClassifications().deleteClassificationFromFolder(folder.getId())" }, { "lang": "node", "label": "Remove classification from folder", "source": "await client.folderClassifications.deleteClassificationFromFolder(folder.id);" }, { "lang": "python", "label": "Remove classification from folder", "source": "client.folder_classifications.delete_classification_from_folder(folder.id)" } ] } }, "/folders/{folder_id}/metadata/{scope}/{template_key}": { "get": { "operationId": "get_folders_id_metadata_id_id", "summary": "Get metadata instance on folder", "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`.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "responses": { "201": { "description": "An instance of the metadata template that includes additional \"key:value\" pairs defined by the user or an application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata--Full" } } } }, "403": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder.\n\n- `instance_not_found` - The metadata template was not applied to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_metadata", "tags": [ "Metadata instances (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata instance on folder", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata instance on folder", "source": "await client.FolderMetadata.GetFolderMetadataByIdAsync(folderId: folder.Id, scope: GetFolderMetadataByIdScope.Global, templateKey: \"properties\");" }, { "lang": "swift", "label": "Get metadata instance on folder", "source": "try await client.folderMetadata.getFolderMetadataById(folderId: folder.id, scope: GetFolderMetadataByIdScope.global, templateKey: \"properties\")" }, { "lang": "java", "label": "Get metadata instance on folder", "source": "client.getFolderMetadata().getFolderMetadataById(folder.getId(), GetFolderMetadataByIdScope.GLOBAL, \"properties\")" }, { "lang": "node", "label": "Get metadata instance on folder", "source": "await client.folderMetadata.getFolderMetadataById(\n folder.id,\n 'global' as GetFolderMetadataByIdScope,\n 'properties',\n);" }, { "lang": "python", "label": "Get metadata instance on folder", "source": "client.folder_metadata.get_folder_metadata_by_id(\n folder.id, GetFolderMetadataByIdScope.GLOBAL, \"properties\"\n)" } ] }, "post": { "operationId": "post_folders_id_metadata_id_id", "summary": "Create metadata instance on folder", "description": "Applies an instance of a metadata template to a folder.\n\nIn 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.\n\nTo 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.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "name": "Aaron Levie" }, "additionalProperties": { "allOf": [ {}, { "example": "Aaron Levie" }, { "description": "A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored in the template. For a taxonomy field, the value should be a list of the node identifiers of the selected taxonomy nodes, since taxonomy fields support multi-select. If a single select taxonomy field is being set, the list should contain a single node identifier." } ] }, "x-box-example-key": "name" } } } }, "responses": { "201": { "description": "Returns the instance of the template that was applied to the folder, including the data that was applied to the template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata--Full" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataError" } } } }, "404": { "description": "Returns an error when the folder or metadata template was not found.\n\n- `not_found` - The folder could not be found, or the user does not have access to the folder.\n- `instance_tuple_not_found` - The metadata template was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when an instance of this metadata template is already present on the folder.\n\n- `tuple_already_exists` - An instance of the metadata template already exists on the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_metadata", "tags": [ "Metadata instances (Folders)" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Create metadata instance on folder", "source": "curl -i -X POST \"https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"audience\": \"internal\",\n \"documentType\": \"Q1 plans\",\n \"competitiveDocument\": \"no\",\n \"status\": \"active\",\n \"author\": \"Jones\",\n \"currentState\": \"proposal\"\n }'" }, { "lang": "dotnet", "label": "Create metadata instance on folder", "source": "await client.FolderMetadata.CreateFolderMetadataByIdAsync(folderId: folder.Id, scope: CreateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary() { { \"name\", \"John\" }, { \"age\", 23 }, { \"birthDate\", \"2001-01-03T02:20:50.520Z\" }, { \"countryCode\", \"US\" }, { \"sports\", Array.AsReadOnly(new [] {\"basketball\",\"tennis\"}) } });" }, { "lang": "swift", "label": "Create metadata instance on folder", "source": "try await client.folderMetadata.createFolderMetadataById(folderId: folder.id, scope: CreateFolderMetadataByIdScope.global, templateKey: \"properties\", requestBody: [\"abc\": \"xyz\"])" }, { "lang": "java", "label": "Create metadata instance on folder", "source": "client.getFolderMetadata().createFolderMetadataById(folder.getId(), CreateFolderMetadataByIdScope.ENTERPRISE, templateKey, mapOf(entryOf(\"name\", \"John\"), entryOf(\"age\", 23), entryOf(\"birthDate\", \"2001-01-03T02:20:50.520Z\"), entryOf(\"countryCode\", \"US\"), entryOf(\"sports\", Arrays.asList(\"basketball\", \"tennis\"))))" }, { "lang": "node", "label": "Create metadata instance on folder", "source": "await client.folderMetadata.createFolderMetadataById(\n folder.id,\n 'enterprise' as CreateFolderMetadataByIdScope,\n templateKey,\n {\n ['name']: 'John',\n ['age']: 23,\n ['birthDate']: '2001-01-03T02:20:50.520Z',\n ['countryCode']: 'US',\n ['sports']: ['basketball', 'tennis'],\n },\n);" }, { "lang": "python", "label": "Create metadata instance on folder", "source": "client.folder_metadata.create_folder_metadata_by_id(\n folder.id,\n CreateFolderMetadataByIdScope.ENTERPRISE,\n template_key,\n {\n \"name\": \"John\",\n \"age\": 23,\n \"birthDate\": \"2001-01-03T02:20:50.520Z\",\n \"countryCode\": \"US\",\n \"sports\": [\"basketball\", \"tennis\"],\n },\n)" } ] }, "put": { "operationId": "put_folders_id_metadata_id_id", "summary": "Update metadata instance on folder", "description": "Updates a piece of metadata on a folder.\n\nThe 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.\n\nThe update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "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.\n\nThe changes are represented as a JSON array of operation objects.", "type": "array", "items": { "title": "A metadata instance update operation", "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a change to make to the metadata instance.", "type": "object", "properties": { "op": { "description": "The type of change to perform on the template. Some of these are hazardous as they will change existing templates.", "type": "string", "example": "add", "enum": [ "add", "replace", "remove", "test", "move", "copy" ] }, "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).\n\nThe 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.", "type": "string", "example": "/currentState" }, "value": { "$ref": "#/components/schemas/MetadataInstanceValue" }, "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).", "type": "string", "example": "/nextState" } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template instance, with the custom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata--Full" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `bad_request` - The request body format is not an array of valid JSON Patch objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid array of JSON Patch items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_metadata", "tags": [ "Metadata instances (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Update metadata instance on folder", "source": "curl -i -X PUT \"https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[\n {\n \"op\": \"test\",\n \"path\": \"/competitiveDocument\",\n \"value\": \"no\"\n },\n {\n \"op\": \"remove\",\n \"path\": \"/competitiveDocument\"\n },\n {\n \"op\": \"test\",\n \"path\": \"/status\",\n \"value\": \"active\"\n },\n {\n \"op\": \"replace\",\n \"path\": \"/status\",\n \"value\": \"inactive\"\n },\n {\n \"op\": \"test\",\n \"path\": \"/author\",\n \"value\": \"Jones\"\n },\n {\n \"op\": \"copy\",\n \"from\": \"/author\",\n \"path\": \"/editor\"\n },\n {\n \"op\": \"test\",\n \"path\": \"/currentState\",\n \"value\": \"proposal\"\n },\n {\n \"op\": \"move\",\n \"from\": \"/currentState\",\n \"path\": \"/previousState\"\n },\n {\n \"op\": \"add\",\n \"path\": \"/currentState\",\n \"value\": \"reviewed\"\n }\n ]'" }, { "lang": "dotnet", "label": "Update metadata instance on folder", "source": "await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = \"/name\", Value = \"Jack\" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = \"/age\", Value = 24L },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = \"/birthDate\", Value = \"2000-01-03T02:20:50.520Z\" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = \"/countryCode\", Value = \"CA\" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = \"/sports\", Value = Array.AsReadOnly(new [] {\"football\"}) }}));" }, { "lang": "java", "label": "Update metadata instance on folder", "source": "client.getFolderMetadata().updateFolderMetadataById(folder.getId(), UpdateFolderMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path(\"/name\").value(\"Jack\").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path(\"/age\").value(24L).build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path(\"/birthDate\").value(\"2000-01-03T02:20:50.520Z\").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path(\"/countryCode\").value(\"CA\").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path(\"/sports\").value(Arrays.asList(\"football\")).build()))" }, { "lang": "node", "label": "Update metadata instance on folder", "source": "await client.folderMetadata.updateFolderMetadataById(\n folder.id,\n 'enterprise' as UpdateFolderMetadataByIdScope,\n templateKey,\n [\n {\n op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,\n path: '/name',\n value: 'Jack',\n } satisfies UpdateFolderMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,\n path: '/age',\n value: 24,\n } satisfies UpdateFolderMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,\n path: '/birthDate',\n value: '2000-01-03T02:20:50.520Z',\n } satisfies UpdateFolderMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,\n path: '/countryCode',\n value: 'CA',\n } satisfies UpdateFolderMetadataByIdRequestBody,\n {\n op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,\n path: '/sports',\n value: ['football'],\n } satisfies UpdateFolderMetadataByIdRequestBody,\n ],\n);" }, { "lang": "python", "label": "Update metadata instance on folder", "source": "client.folder_metadata.update_folder_metadata_by_id(\n folder.id,\n UpdateFolderMetadataByIdScope.ENTERPRISE,\n template_key,\n [\n UpdateFolderMetadataByIdRequestBody(\n op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/name\",\n value=\"Jack\",\n ),\n UpdateFolderMetadataByIdRequestBody(\n op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path=\"/age\", value=24\n ),\n UpdateFolderMetadataByIdRequestBody(\n op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/birthDate\",\n value=\"2000-01-03T02:20:50.520Z\",\n ),\n UpdateFolderMetadataByIdRequestBody(\n op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/countryCode\",\n value=\"CA\",\n ),\n UpdateFolderMetadataByIdRequestBody(\n op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,\n path=\"/sports\",\n value=[\"football\"],\n ),\n ],\n)" } ] }, "delete": { "operationId": "delete_folders_id_metadata_id_id", "summary": "Remove metadata instance from folder", "description": "Deletes a piece of folder metadata.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "responses": { "204": { "description": "Returns an empty response when the metadata is successfully deleted." }, "400": { "description": "Returned when the request parameters are not valid. This may happen of the `scope` is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this folder.\n- `not_found` - The folder was not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_metadata", "tags": [ "Metadata instances (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove metadata instance from folder", "source": "curl -i -X DELETE \"https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove metadata instance from folder", "source": "await client.FolderMetadata.DeleteFolderMetadataByIdAsync(folderId: folder.Id, scope: DeleteFolderMetadataByIdScope.Enterprise, templateKey: templateKey);" }, { "lang": "swift", "label": "Remove metadata instance from folder", "source": "try await client.folderMetadata.deleteFolderMetadataById(folderId: folder.id, scope: DeleteFolderMetadataByIdScope.global, templateKey: \"properties\")" }, { "lang": "java", "label": "Remove metadata instance from folder", "source": "client.getFolderMetadata().deleteFolderMetadataById(folder.getId(), DeleteFolderMetadataByIdScope.ENTERPRISE, templateKey)" }, { "lang": "node", "label": "Remove metadata instance from folder", "source": "await client.folderMetadata.deleteFolderMetadataById(\n folder.id,\n 'enterprise' as DeleteFolderMetadataByIdScope,\n templateKey,\n);" }, { "lang": "python", "label": "Remove metadata instance from folder", "source": "client.folder_metadata.delete_folder_metadata_by_id(\n folder.id, DeleteFolderMetadataByIdScope.ENTERPRISE, template_key\n)" } ] } }, "/folders/trash/items": { "get": { "operationId": "get_folders_trash_items", "summary": "List trashed items", "description": "Retrieves the files and folders that have been moved to the trash.\n\nAny 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.\n\nThis endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter.\n\nThe number of entries returned may be less than `total_count`. For example, if a user deletes items from a shared folder and is later removed as a collaborator, those deleted items will no longer appear in this endpoint’s results, even though they are still included in `total_count`.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "usemarker", "in": "query", "description": "Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time.\n\nBy 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.", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "direction", "in": "query", "description": "The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order.", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "sort", "in": "query", "description": "Defines the **second** attribute by which items are sorted.\n\nItems are always sorted by their `type` first, with folders listed before files, and files listed before web links.\n\nThis parameter is not supported when using marker-based pagination.", "required": false, "schema": { "type": "string", "enum": [ "name", "date", "size" ] }, "example": "name" } ], "responses": { "200": { "description": "Returns a list of items that have been deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `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`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_items", "tags": [ "Trashed items" ], "x-codeSamples": [ { "lang": "curl", "label": "List trashed items", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/trash/items\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List trashed items", "source": "await client.TrashedItems.GetTrashedItemsAsync();" }, { "lang": "swift", "label": "List trashed items", "source": "try await client.trashedItems.getTrashedItems()" }, { "lang": "java", "label": "List trashed items", "source": "client.getTrashedItems().getTrashedItems()" }, { "lang": "node", "label": "List trashed items", "source": "await client.trashedItems.getTrashedItems();" }, { "lang": "python", "label": "List trashed items", "source": "client.trashed_items.get_trashed_items()" } ] } }, "/folders/{folder_id}/watermark": { "get": { "operationId": "get_folders_id_watermark", "summary": "Get watermark for folder", "description": "Retrieve the watermark for a folder.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "responses": { "200": { "description": "Returns an object containing information about the watermark associated for to this folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "404": { "description": "Returns an error if the folder does not have a watermark applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_watermarks", "tags": [ "Watermarks (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get watermark for folder", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/4353455/watermark\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get watermark for folder", "source": "await client.FolderWatermarks.GetFolderWatermarkAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "Get watermark for folder", "source": "try await client.folderWatermarks.getFolderWatermark(folderId: folder.id)" }, { "lang": "java", "label": "Get watermark for folder", "source": "client.getFolderWatermarks().getFolderWatermark(folder.getId())" }, { "lang": "node", "label": "Get watermark for folder", "source": "await client.folderWatermarks.getFolderWatermark(folder.id);" }, { "lang": "python", "label": "Get watermark for folder", "source": "client.folder_watermarks.get_folder_watermark(folder.id)" } ] }, "put": { "operationId": "put_folders_id_watermark", "summary": "Apply watermark to folder", "description": "Applies or update a watermark on a folder.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "watermark": { "description": "The watermark to imprint on the folder.", "type": "object", "properties": { "imprint": { "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "type": "string", "example": "default", "enum": [ "default" ] } }, "required": [ "imprint" ] } }, "required": [ "watermark" ] } } } }, "responses": { "200": { "description": "Returns an updated watermark if a watermark already existed on this folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "201": { "description": "Returns a new watermark if no watermark existed on this folder yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Watermark" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_watermarks", "tags": [ "Watermarks (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Apply watermark to folder", "source": "curl -i -X PUT \"https://api.box.com/2.0/folders/4353455/watermark\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"watermark\": {\n \"imprint\": \"default\"\n }\n }'" }, { "lang": "dotnet", "label": "Apply watermark to folder", "source": "await client.FolderWatermarks.UpdateFolderWatermarkAsync(folderId: folder.Id, requestBody: new UpdateFolderWatermarkRequestBody(watermark: new UpdateFolderWatermarkRequestBodyWatermarkField(imprint: UpdateFolderWatermarkRequestBodyWatermarkImprintField.Default)));" }, { "lang": "swift", "label": "Apply watermark to folder", "source": "try await client.folderWatermarks.updateFolderWatermark(folderId: folder.id, requestBody: UpdateFolderWatermarkRequestBody(watermark: UpdateFolderWatermarkRequestBodyWatermarkField(imprint: UpdateFolderWatermarkRequestBodyWatermarkImprintField.default_)))" }, { "lang": "java", "label": "Apply watermark to folder", "source": "client.getFolderWatermarks().updateFolderWatermark(folder.getId(), new UpdateFolderWatermarkRequestBody(new UpdateFolderWatermarkRequestBodyWatermarkField.Builder().imprint(UpdateFolderWatermarkRequestBodyWatermarkImprintField.DEFAULT).build()))" }, { "lang": "node", "label": "Apply watermark to folder", "source": "await client.folderWatermarks.updateFolderWatermark(folder.id, {\n watermark: new UpdateFolderWatermarkRequestBodyWatermarkField({\n imprint: 'default' as UpdateFolderWatermarkRequestBodyWatermarkImprintField,\n }),\n} satisfies UpdateFolderWatermarkRequestBody);" }, { "lang": "python", "label": "Apply watermark to folder", "source": "client.folder_watermarks.update_folder_watermark(\n folder.id,\n UpdateFolderWatermarkWatermark(\n imprint=UpdateFolderWatermarkWatermarkImprintField.DEFAULT\n ),\n)" } ] }, "delete": { "operationId": "delete_folders_id_watermark", "summary": "Remove watermark from folder", "description": "Removes the watermark from a folder.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "responses": { "204": { "description": "An empty response will be returned when the watermark was successfully deleted." }, "404": { "description": "Returns an error if the folder did not have a watermark applied to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_watermarks", "tags": [ "Watermarks (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove watermark from folder", "source": "curl -i -X DELETE \"https://api.box.com/2.0/folders/4353455/watermark\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove watermark from folder", "source": "await client.FolderWatermarks.DeleteFolderWatermarkAsync(folderId: folder.Id);" }, { "lang": "swift", "label": "Remove watermark from folder", "source": "try await client.folderWatermarks.deleteFolderWatermark(folderId: folder.id)" }, { "lang": "java", "label": "Remove watermark from folder", "source": "client.getFolderWatermarks().deleteFolderWatermark(folder.getId())" }, { "lang": "node", "label": "Remove watermark from folder", "source": "await client.folderWatermarks.deleteFolderWatermark(folder.id);" }, { "lang": "python", "label": "Remove watermark from folder", "source": "client.folder_watermarks.delete_folder_watermark(folder.id)" } ] } }, "/folder_locks": { "get": { "operationId": "get_folder_locks", "summary": "List folder locks", "description": "Retrieves folder lock details for a given folder.\n\nYou must be authenticated as the owner or co-owner of the folder to use this endpoint.", "parameters": [ { "name": "folder_id", "in": "query", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "responses": { "200": { "description": "Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderLocks" } } } }, "403": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_locks", "tags": [ "Folder Locks" ], "x-codeSamples": [ { "lang": "curl", "label": "List folder locks", "source": "curl -i -X GET \"https://api.box.com/2.0/folder_locks?folder_id=33552487093\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List folder locks", "source": "await client.FolderLocks.GetFolderLocksAsync(queryParams: new GetFolderLocksQueryParams(folderId: folder.Id));" }, { "lang": "swift", "label": "List folder locks", "source": "try await client.folderLocks.getFolderLocks(queryParams: GetFolderLocksQueryParams(folderId: folder.id))" }, { "lang": "java", "label": "List folder locks", "source": "client.getFolderLocks().getFolderLocks(new GetFolderLocksQueryParams(folder.getId()))" }, { "lang": "node", "label": "List folder locks", "source": "await client.folderLocks.getFolderLocks({\n folderId: folder.id,\n} satisfies GetFolderLocksQueryParams);" }, { "lang": "python", "label": "List folder locks", "source": "client.folder_locks.get_folder_locks(folder.id)" } ] }, "post": { "operationId": "post_folder_locks", "summary": "Create folder lock", "description": "Creates a folder lock on a folder, preventing it from being moved and/or deleted.\n\nYou must be authenticated as the owner or co-owner of the folder to use this endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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`.", "type": "object", "properties": { "move": { "description": "Whether moving the folder should be locked.", "type": "boolean", "example": true }, "delete": { "description": "Whether deleting the folder should be locked.", "example": true, "type": "boolean" } }, "required": [ "move", "delete" ] }, "folder": { "description": "The folder to apply the lock to.", "type": "object", "properties": { "type": { "description": "The content type the lock is being applied to. Only `folder` is supported.", "type": "string", "example": "folder" }, "id": { "description": "The ID of the folder.", "type": "string", "example": "1234567890" } }, "required": [ "type", "id" ] } }, "required": [ "folder" ] } } } }, "responses": { "200": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderLock" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder was not found.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_locks", "tags": [ "Folder Locks" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Create folder lock", "source": "curl -i -X POST \"https://api.box.com/2.0/folder_locks\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"folder\": {\n \"type\": \"folder\",\n \"id\": \"33552487093\"\n },\n \"locked_operations\": {\n \"move\": true,\n \"delete\": true\n }\n }'" }, { "lang": "dotnet", "label": "Create folder lock", "source": "await client.FolderLocks.CreateFolderLockAsync(requestBody: new CreateFolderLockRequestBody(folder: new CreateFolderLockRequestBodyFolderField(id: folder.Id, type: \"folder\")) { LockedOperations = new CreateFolderLockRequestBodyLockedOperationsField(move: true, delete: true) });" }, { "lang": "swift", "label": "Create folder lock", "source": "try await client.folderLocks.createFolderLock(requestBody: CreateFolderLockRequestBody(folder: CreateFolderLockRequestBodyFolderField(id: folder.id, type: \"folder\"), lockedOperations: CreateFolderLockRequestBodyLockedOperationsField(move: true, delete: true)))" }, { "lang": "java", "label": "Create folder lock", "source": "client.getFolderLocks().createFolderLock(new CreateFolderLockRequestBody.Builder(new CreateFolderLockRequestBodyFolderField(\"folder\", folder.getId())).lockedOperations(new CreateFolderLockRequestBodyLockedOperationsField(true, true)).build())" }, { "lang": "node", "label": "Create folder lock", "source": "await client.folderLocks.createFolderLock({\n folder: {\n id: folder.id,\n type: 'folder',\n } satisfies CreateFolderLockRequestBodyFolderField,\n lockedOperations: {\n move: true,\n delete: true,\n } satisfies CreateFolderLockRequestBodyLockedOperationsField,\n} satisfies CreateFolderLockRequestBody);" }, { "lang": "python", "label": "Create folder lock", "source": "client.folder_locks.create_folder_lock(\n CreateFolderLockFolder(id=folder.id, type=\"folder\"),\n locked_operations=CreateFolderLockLockedOperations(move=True, delete=True),\n)" } ] } }, "/folder_locks/{folder_lock_id}": { "delete": { "operationId": "delete_folder_locks_id", "summary": "Delete folder lock", "description": "Deletes a folder lock on a given folder.\n\nYou must be authenticated as the owner or co-owner of the folder to use this endpoint.", "parameters": [ { "name": "folder_lock_id", "in": "path", "description": "The ID of the folder lock.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the folder lock is successfully deleted." }, "403": { "description": "Returns an error if the user does not have the required access to perform the action.\n\n- `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the folder could not be found, or the authenticated user does not have access to the folder.\n\n- `not_found` when the authenticated user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "folder_locks", "tags": [ "Folder Locks" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete folder lock", "source": "curl -i -X DELETE \"https://api.box.com/2.0/folder_locks/93134\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete folder lock", "source": "await client.FolderLocks.DeleteFolderLockByIdAsync(folderLockId: NullableUtils.Unwrap(folderLock.Id));" }, { "lang": "swift", "label": "Delete folder lock", "source": "try await client.folderLocks.deleteFolderLockById(folderLockId: folderLock.id!)" }, { "lang": "java", "label": "Delete folder lock", "source": "client.getFolderLocks().deleteFolderLockById(folderLock.getId())" }, { "lang": "node", "label": "Delete folder lock", "source": "await client.folderLocks.deleteFolderLockById(folderLock.id!);" }, { "lang": "python", "label": "Delete folder lock", "source": "client.folder_locks.delete_folder_lock_by_id(folder_lock.id)" } ] } }, "/metadata_templates": { "get": { "operationId": "get_metadata_templates", "summary": "Find metadata template by instance ID", "description": "Finds a metadata template by searching for the ID of an instance of the template.", "parameters": [ { "name": "metadata_instance_id", "in": "query", "description": "The ID of an instance of the metadata template to find.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01234500-12f1-1234-aa12-b1d234cb567e" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list containing the 1 metadata template that matches the instance ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplates" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-codeSamples": [ { "lang": "curl", "label": "Find metadata template by instance ID", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_templates?metadata_instance_id=01234500-12f1-1234-aa12-b1d234cb567e\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Find metadata template by instance ID", "source": "await client.MetadataTemplates.GetMetadataTemplatesByInstanceIdAsync(queryParams: new GetMetadataTemplatesByInstanceIdQueryParams(metadataInstanceId: NullableUtils.Unwrap(createdMetadataInstance.Id)));" }, { "lang": "swift", "label": "Find metadata template by instance ID", "source": "try await client.metadataTemplates.getMetadataTemplatesByInstanceId(queryParams: GetMetadataTemplatesByInstanceIdQueryParams(metadataInstanceId: createdMetadataInstance.id!))" }, { "lang": "java", "label": "Find metadata template by instance ID", "source": "client.getMetadataTemplates().getMetadataTemplatesByInstanceId(new GetMetadataTemplatesByInstanceIdQueryParams(createdMetadataInstance.getId()))" }, { "lang": "node", "label": "Find metadata template by instance ID", "source": "await client.metadataTemplates.getMetadataTemplatesByInstanceId({\n metadataInstanceId: createdMetadataInstance.id!,\n} satisfies GetMetadataTemplatesByInstanceIdQueryParams);" }, { "lang": "python", "label": "Find metadata template by instance ID", "source": "client.metadata_templates.get_metadata_templates_by_instance_id(\n created_metadata_instance.id\n)" } ] } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema": { "get": { "operationId": "get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema", "summary": "List all classifications", "description": "Retrieves the classification metadata template and lists all the classifications available to this enterprise.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "responses": { "200": { "description": "Returns the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure the URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "classifications", "tags": [ "Classifications" ], "x-codeSamples": [ { "lang": "curl", "label": "List all classifications", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List all classifications", "source": "await client.Classifications.GetClassificationTemplateAsync();" }, { "lang": "swift", "label": "List all classifications", "source": "try await client.classifications.getClassificationTemplate()" }, { "lang": "java", "label": "List all classifications", "source": "client.getClassifications().getClassificationTemplate()" }, { "lang": "node", "label": "List all classifications", "source": "await client.classifications.getClassificationTemplate();" }, { "lang": "python", "label": "List all classifications", "source": "client.classifications.get_classification_template()" } ] } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add", "summary": "Add classification", "description": "Adds one or more new classifications to the list of classifications available to the enterprise.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "requestBody": { "content": { "application/json": { "schema": { "description": "An array that contains one or more classifications to add to the enterprise's list of classifications.", "type": "array", "items": { "type": "object", "description": "A single classification to add to the enterprise.", "required": [ "op", "fieldKey", "data" ], "properties": { "op": { "description": "The type of change to perform on the classification object.", "type": "string", "example": "addEnumOption", "enum": [ "addEnumOption" ] }, "fieldKey": { "description": "Defines classifications available in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", "enum": [ "Box__Security__Classification__Key" ] }, "data": { "description": "The details of the classification to add.", "type": "object", "properties": { "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.", "type": "string", "example": "Sensitive" }, "staticConfig": { "description": "A static configuration for the classification.", "type": "object", "properties": { "classification": { "description": "Additional details for the classification.", "type": "object", "properties": { "classificationDefinition": { "description": "A longer description of the classification.", "type": "string", "example": "Sensitive information that must not be shared." }, "colorID": { "description": "An internal Box identifier used to assign a color to a classification label.\n\nMapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows.\n\n- `0`: Yellow.\n- `1`: Orange.\n- `2`: Watermelon red.\n- `3`: Purple rain.\n- `4`: Light blue.\n- `5`: Dark blue.\n- `6`: Light green.\n- `7`: Gray.", "type": "integer", "format": "int64", "example": 4 } } } } } }, "required": [ "key" ] } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure the URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "classifications", "tags": [ "Classifications" ], "x-codeSamples": [ { "lang": "curl", "label": "Add classification", "source": "curl -i -X PUT \"https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[{\n \"op\": \"addEnumOption\",\n \"fieldKey\": \"Box__Security__Classification__Key\",\n \"data\": {\n \"key\": \"Sensitive\",\n \"staticConfig\":{\n \"classification\": {\n \"classificationDefinition\": \"Sensitive information that must not be shared.\",\n \"colorID\": 4\n }\n }\n }\n }]'" }, { "lang": "dotnet", "label": "Add classification", "source": "await client.Classifications.AddClassificationAsync(requestBody: Array.AsReadOnly(new [] {new AddClassificationRequestBody(data: new AddClassificationRequestBodyDataField(key: Utils.GetUUID()) { StaticConfig = new AddClassificationRequestBodyDataStaticConfigField() { Classification = new AddClassificationRequestBodyDataStaticConfigClassificationField() { ColorId = 4L, ClassificationDefinition = \"Other description\" } } })}));" }, { "lang": "swift", "label": "Add classification", "source": "try await client.classifications.addClassification(requestBody: [AddClassificationRequestBody(data: AddClassificationRequestBodyDataField(key: Utils.getUUID(), staticConfig: AddClassificationRequestBodyDataStaticConfigField(classification: AddClassificationRequestBodyDataStaticConfigClassificationField(colorId: Int64(4), classificationDefinition: \"Other description\"))))])" }, { "lang": "java", "label": "Add classification", "source": "client.getClassifications().addClassification(Arrays.asList(new AddClassificationRequestBody(new AddClassificationRequestBodyDataField.Builder(getUuid()).staticConfig(new AddClassificationRequestBodyDataStaticConfigField.Builder().classification(new AddClassificationRequestBodyDataStaticConfigClassificationField.Builder().classificationDefinition(\"Other description\").colorId(4L).build()).build()).build())))" }, { "lang": "node", "label": "Add classification", "source": "await client.classifications.addClassification([\n new AddClassificationRequestBody({\n data: {\n key: getUuid(),\n staticConfig: {\n classification: {\n colorId: 4,\n classificationDefinition: 'Other description',\n } satisfies AddClassificationRequestBodyDataStaticConfigClassificationField,\n } satisfies AddClassificationRequestBodyDataStaticConfigField,\n } satisfies AddClassificationRequestBodyDataField,\n }),\n]);" }, { "lang": "python", "label": "Add classification", "source": "client.classifications.add_classification(\n [\n AddClassificationRequestBody(\n data=AddClassificationRequestBodyDataField(\n key=get_uuid(),\n static_config=AddClassificationRequestBodyDataStaticConfigField(\n classification=AddClassificationRequestBodyDataStaticConfigClassificationField(\n color_id=4, classification_definition=\"Other description\"\n )\n ),\n )\n )\n ]\n)" } ] } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update", "summary": "Update classification", "description": "Updates the labels and descriptions of one or more classifications available to the enterprise.\n\nThis API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "requestBody": { "content": { "application/json-patch+json": { "schema": { "description": "An array that contains one or more classifications to update.", "type": "array", "items": { "type": "object", "description": "A single classification to update.", "required": [ "op", "fieldKey", "enumOptionKey", "data" ], "properties": { "op": { "description": "The type of change to perform on the classification object.", "type": "string", "example": "editEnumOption", "enum": [ "editEnumOption" ] }, "fieldKey": { "description": "Defines classifications available in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", "enum": [ "Box__Security__Classification__Key" ] }, "enumOptionKey": { "description": "The original label of the classification to change.", "type": "string", "example": "Sensitive" }, "data": { "description": "The details of the updated classification.", "type": "object", "properties": { "key": { "description": "A new label for the classification, as it will be shown in the web and mobile interfaces.", "type": "string", "example": "Very Sensitive" }, "staticConfig": { "description": "A static configuration for the classification.", "type": "object", "properties": { "classification": { "description": "Additional details for the classification.", "type": "object", "properties": { "classificationDefinition": { "description": "A longer description of the classification.", "type": "string", "example": "Sensitive information that must not be shared." }, "colorID": { "description": "An internal Box identifier used to assign a color to a classification label.\n\nMapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows.\n\n- `0`: Yellow.\n- `1`: Orange.\n- `2`: Watermelon red.\n- `3`: Purple rain.\n- `4`: Light blue.\n- `5`: Dark blue.\n- `6`: Light green.\n- `7`: Gray.", "type": "integer", "format": "int64", "example": 4 } } } } } }, "required": [ "key" ] } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure the URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "classifications", "tags": [ "Classifications" ], "x-codeSamples": [ { "lang": "curl", "label": "Update classification", "source": "curl -i -X PUT \"https://api.box.com/2.0/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[{\n \"op\": \"editEnumOption\",\n \"fieldKey\": \"Box__Security__Classification__Key\",\n \"enumOptionKey\": \"Sensitive\",\n \"data\": {\n \"key\": \"Very Sensitive\",\n \"staticConfig\": {\n \"classification\": {\n \"classificationDefinition\": \"Sensitive information that must not be shared.\",\n \"colorID\": 4\n }\n }\n }\n }]'" }, { "lang": "dotnet", "label": "Update classification", "source": "await client.Classifications.UpdateClassificationAsync(requestBody: Array.AsReadOnly(new [] {new UpdateClassificationRequestBody(enumOptionKey: classification.Key, data: new UpdateClassificationRequestBodyDataField(key: updatedClassificationName) { StaticConfig = new UpdateClassificationRequestBodyDataStaticConfigField() { Classification = new UpdateClassificationRequestBodyDataStaticConfigClassificationField() { ColorId = 2L, ClassificationDefinition = updatedClassificationDescription } } })}));" }, { "lang": "swift", "label": "Update classification", "source": "try await client.classifications.updateClassification(requestBody: [UpdateClassificationRequestBody(enumOptionKey: classification.key, data: UpdateClassificationRequestBodyDataField(key: updatedClassificationName, staticConfig: UpdateClassificationRequestBodyDataStaticConfigField(classification: UpdateClassificationRequestBodyDataStaticConfigClassificationField(colorId: Int64(2), classificationDefinition: updatedClassificationDescription))))])" }, { "lang": "java", "label": "Update classification", "source": "client.getClassifications().updateClassification(Arrays.asList(new UpdateClassificationRequestBody(classification.getKey(), new UpdateClassificationRequestBodyDataField.Builder(updatedClassificationName).staticConfig(new UpdateClassificationRequestBodyDataStaticConfigField.Builder().classification(new UpdateClassificationRequestBodyDataStaticConfigClassificationField.Builder().classificationDefinition(updatedClassificationDescription).colorId(2L).build()).build()).build())))" }, { "lang": "node", "label": "Update classification", "source": "await client.classifications.updateClassification([\n new UpdateClassificationRequestBody({\n enumOptionKey: classification.key,\n data: {\n key: updatedClassificationName,\n staticConfig: {\n classification: {\n colorId: 2,\n classificationDefinition: updatedClassificationDescription,\n } satisfies UpdateClassificationRequestBodyDataStaticConfigClassificationField,\n } satisfies UpdateClassificationRequestBodyDataStaticConfigField,\n } satisfies UpdateClassificationRequestBodyDataField,\n }),\n]);" }, { "lang": "python", "label": "Update classification", "source": "client.classifications.update_classification(\n [\n UpdateClassificationRequestBody(\n enum_option_key=classification.key,\n data=UpdateClassificationRequestBodyDataField(\n key=updated_classification_name,\n static_config=UpdateClassificationRequestBodyDataStaticConfigField(\n classification=UpdateClassificationRequestBodyDataStaticConfigClassificationField(\n color_id=2,\n classification_definition=updated_classification_description,\n )\n ),\n ),\n )\n ]\n)" } ] } }, "/metadata_templates/{scope}/{template_key}/schema": { "get": { "operationId": "get_metadata_templates_id_id_schema", "summary": "Get metadata template by name", "description": "Retrieves a metadata template by its `scope` and `templateKey` values.\n\nTo 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.", "parameters": [ { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "responses": { "200": { "description": "Returns the metadata template matching the `scope` and `template` name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template with the given `scope` and `template_key` can not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata template by name", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata template by name", "source": "await client.MetadataTemplates.GetMetadataTemplateAsync(scope: GetMetadataTemplateScope.Enterprise, templateKey: NullableUtils.Unwrap(template.TemplateKey));" }, { "lang": "swift", "label": "Get metadata template by name", "source": "try await client.metadataTemplates.getMetadataTemplate(scope: GetMetadataTemplateScope.enterprise, templateKey: template.templateKey!)" }, { "lang": "java", "label": "Get metadata template by name", "source": "client.getMetadataTemplates().getMetadataTemplate(GetMetadataTemplateScope.ENTERPRISE, template.getTemplateKey())" }, { "lang": "node", "label": "Get metadata template by name", "source": "await client.metadataTemplates.getMetadataTemplate(\n 'enterprise' as GetMetadataTemplateScope,\n template.templateKey!,\n);" }, { "lang": "python", "label": "Get metadata template by name", "source": "client.metadata_templates.get_metadata_template(\n GetMetadataTemplateScope.ENTERPRISE, template.template_key\n)" } ] }, "put": { "operationId": "put_metadata_templates_id_id_schema", "summary": "Update metadata template", "description": "Updates a metadata template.\n\nThe metadata template can only be updated if the template already exists.\n\nThe update is applied atomically. If any errors occur during the application of the operations, the metadata template will not be changed.", "parameters": [ { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "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.\n\nThe changes are represented as a JSON array of operation objects.", "type": "array", "items": { "title": "A metadata template update operation", "description": "A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a change to make to the metadata instance.", "type": "object", "required": [ "op" ], "properties": { "op": { "description": "The type of change to perform on the template. Some of these are hazardous as they will change existing templates.", "type": "string", "example": "addEnumOption", "enum": [ "editTemplate", "addField", "reorderFields", "addEnumOption", "reorderEnumOptions", "reorderMultiSelectOptions", "addMultiSelectOption", "editField", "removeField", "editEnumOption", "removeEnumOption", "editMultiSelectOption", "removeMultiSelectOption" ] }, "data": { "description": "The data for the operation. This will vary depending on the operation being performed.", "type": "object", "example": { "name": "Aaron Levie" }, "additionalProperties": { "allOf": [ {}, { "example": "Aaron Levie" }, { "description": "A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template." } ], "x-box-example-key": "name" } }, "fieldKey": { "description": "For operations that affect a single field this defines the key of the field that is affected.", "type": "string", "example": "category" }, "fieldKeys": { "description": "For operations that affect multiple fields this defines the keys of the fields that are affected.", "type": "array", "items": { "type": "string" }, "example": [ "category", "name" ] }, "enumOptionKey": { "description": "For operations that affect a single `enum` option this defines the key of the option that is affected.", "type": "string", "example": "option1" }, "enumOptionKeys": { "description": "For operations that affect multiple `enum` options this defines the keys of the options that are affected.", "type": "array", "items": { "type": "string" }, "example": [ "option1", "option2", "option3" ] }, "multiSelectOptionKey": { "description": "For operations that affect a single multi select option this defines the key of the option that is affected.", "type": "string", "example": "option1" }, "multiSelectOptionKeys": { "description": "For operations that affect multiple multi select options this defines the keys of the options that are affected.", "type": "array", "items": { "type": "string" }, "example": [ "option1", "option2", "option3" ] } } } } } } }, "responses": { "200": { "description": "Returns the updated metadata template, with the custom template data included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "The request body does not contain a valid metadata schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "The request body contains a scope that the user is not allowed to create templates for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "The requested template could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-codeSamples": [ { "lang": "curl", "label": "Update metadata template", "source": "curl -i -X PUT \"https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json-patch+json\" \\\n -d '[\n {\n \"op\": \"editField\",\n \"fieldKey\": \"category\",\n \"data\": {\n \"displayName\": \"Customer Group\"\n }\n }\n ]'" }, { "lang": "dotnet", "label": "Update metadata template", "source": "await client.MetadataTemplates.UpdateMetadataTemplateAsync(scope: UpdateMetadataTemplateScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateMetadataTemplateRequestBody(op: UpdateMetadataTemplateRequestBodyOpField.AddField) { FieldKey = \"newfieldname\", Data = new Dictionary() { { \"type\", \"string\" }, { \"displayName\", \"newFieldName\" } } }}));" }, { "lang": "swift", "label": "Update metadata template", "source": "try await client.metadataTemplates.updateMetadataTemplate(scope: UpdateMetadataTemplateScope.enterprise, templateKey: templateKey, requestBody: [UpdateMetadataTemplateRequestBody(op: UpdateMetadataTemplateRequestBodyOpField.addField, fieldKey: \"newfieldname\", data: [\"type\": \"string\", \"displayName\": \"newFieldName\"])])" }, { "lang": "java", "label": "Update metadata template", "source": "client.getMetadataTemplates().updateMetadataTemplate(UpdateMetadataTemplateScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateMetadataTemplateRequestBody.Builder(UpdateMetadataTemplateRequestBodyOpField.ADDFIELD).data(mapOf(entryOf(\"type\", \"string\"), entryOf(\"displayName\", \"newFieldName\"))).fieldKey(\"newfieldname\").build()))" }, { "lang": "node", "label": "Update metadata template", "source": "await client.metadataTemplates.updateMetadataTemplate(\n 'enterprise' as UpdateMetadataTemplateScope,\n templateKey,\n [\n {\n op: 'addField' as UpdateMetadataTemplateRequestBodyOpField,\n fieldKey: 'newfieldname',\n data: { ['type']: 'string', ['displayName']: 'newFieldName' },\n } satisfies UpdateMetadataTemplateRequestBody,\n ],\n);" }, { "lang": "python", "label": "Update metadata template", "source": "client.metadata_templates.update_metadata_template(\n UpdateMetadataTemplateScope.ENTERPRISE,\n template_key,\n [\n UpdateMetadataTemplateRequestBody(\n op=UpdateMetadataTemplateRequestBodyOpField.ADDFIELD,\n field_key=\"newfieldname\",\n data={\"type\": \"string\", \"displayName\": \"newFieldName\"},\n )\n ],\n)" } ] }, "delete": { "operationId": "delete_metadata_templates_id_id_schema", "summary": "Remove metadata template", "description": "Delete a metadata template and its instances. This deletion is permanent and can not be reversed.", "parameters": [ { "name": "scope", "in": "path", "description": "The scope of the metadata template.", "required": true, "schema": { "type": "string", "enum": [ "global", "enterprise" ] }, "example": "global" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" } ], "responses": { "204": { "description": "Returns an empty response when the metadata template is successfully deleted." }, "400": { "description": "Request body does not contain a valid metadata schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Request body contains a scope that the user is not allowed to create a template for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove metadata template", "source": "curl -i -X DELETE \"https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove metadata template", "source": "await client.MetadataTemplates.DeleteMetadataTemplateAsync(scope: DeleteMetadataTemplateScope.Enterprise, templateKey: NullableUtils.Unwrap(template.TemplateKey));" }, { "lang": "swift", "label": "Remove metadata template", "source": "try await client.metadataTemplates.deleteMetadataTemplate(scope: DeleteMetadataTemplateScope.enterprise, templateKey: template.templateKey!)" }, { "lang": "java", "label": "Remove metadata template", "source": "client.getMetadataTemplates().deleteMetadataTemplate(DeleteMetadataTemplateScope.ENTERPRISE, template.getTemplateKey())" }, { "lang": "node", "label": "Remove metadata template", "source": "await client.metadataTemplates.deleteMetadataTemplate(\n 'enterprise' as DeleteMetadataTemplateScope,\n template.templateKey!,\n);" }, { "lang": "python", "label": "Remove metadata template", "source": "client.metadata_templates.delete_metadata_template(\n DeleteMetadataTemplateScope.ENTERPRISE, template.template_key\n)" } ] } }, "/metadata_templates/{template_id}": { "get": { "operationId": "get_metadata_templates_id", "summary": "Get metadata template by ID", "description": "Retrieves a metadata template by its ID.", "parameters": [ { "name": "template_id", "in": "path", "description": "The ID of the template.", "required": true, "schema": { "type": "string" }, "example": "f7a9891f" } ], "responses": { "200": { "description": "Returns the metadata template that matches the ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.\n\n- `bad_request`: Often returned with a message when the ID of the template is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata template by ID", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_templates/d9671692-3df6-11ea-b77f-2e728ce88125\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata template by ID", "source": "await client.MetadataTemplates.GetMetadataTemplateByIdAsync(templateId: template.Id);" }, { "lang": "swift", "label": "Get metadata template by ID", "source": "try await client.metadataTemplates.getMetadataTemplateById(templateId: template.id)" }, { "lang": "java", "label": "Get metadata template by ID", "source": "client.getMetadataTemplates().getMetadataTemplateById(template.getId())" }, { "lang": "node", "label": "Get metadata template by ID", "source": "await client.metadataTemplates.getMetadataTemplateById(template.id);" }, { "lang": "python", "label": "Get metadata template by ID", "source": "client.metadata_templates.get_metadata_template_by_id(template.id)" } ] } }, "/metadata_templates/global": { "get": { "operationId": "get_metadata_templates_global", "summary": "List all global metadata templates", "description": "Used to retrieve all generic, global metadata templates available to all enterprises using Box.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns all of the metadata templates available to all enterprises and their corresponding schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplates" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-codeSamples": [ { "lang": "curl", "label": "List all global metadata templates", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_templates/global\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List all global metadata templates", "source": "await client.MetadataTemplates.GetGlobalMetadataTemplatesAsync();" }, { "lang": "swift", "label": "List all global metadata templates", "source": "try await client.metadataTemplates.getGlobalMetadataTemplates()" }, { "lang": "java", "label": "List all global metadata templates", "source": "client.getMetadataTemplates().getGlobalMetadataTemplates()" }, { "lang": "node", "label": "List all global metadata templates", "source": "await client.metadataTemplates.getGlobalMetadataTemplates();" }, { "lang": "python", "label": "List all global metadata templates", "source": "client.metadata_templates.get_global_metadata_templates()" } ] } }, "/metadata_templates/enterprise": { "get": { "operationId": "get_metadata_templates_enterprise", "summary": "List all metadata templates for enterprise", "description": "Used to retrieve all metadata templates created to be used specifically within the user's enterprise.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns all of the metadata templates within an enterprise and their corresponding schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplates" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-codeSamples": [ { "lang": "curl", "label": "List all metadata templates for enterprise", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_templates/enterprise\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List all metadata templates for enterprise", "source": "await client.MetadataTemplates.GetEnterpriseMetadataTemplatesAsync();" }, { "lang": "swift", "label": "List all metadata templates for enterprise", "source": "try await client.metadataTemplates.getEnterpriseMetadataTemplates()" }, { "lang": "java", "label": "List all metadata templates for enterprise", "source": "client.getMetadataTemplates().getEnterpriseMetadataTemplates()" }, { "lang": "node", "label": "List all metadata templates for enterprise", "source": "await client.metadataTemplates.getEnterpriseMetadataTemplates();" }, { "lang": "python", "label": "List all metadata templates for enterprise", "source": "client.metadata_templates.get_enterprise_metadata_templates()" } ] } }, "/metadata_templates/schema": { "post": { "operationId": "post_metadata_templates_schema", "summary": "Create metadata template", "description": "Creates a new metadata template that can be applied to files and folders.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "description": "The scope of the metadata template to create. Applications can only create templates for use within the authenticated user's enterprise.\n\nThis value needs to be set to `enterprise`, as `global` scopes can not be created by applications.", "type": "string", "example": "enterprise" }, "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.\n\nWhen not provided, the API will create a unique `templateKey` based on the value of the `displayName`.", "type": "string", "example": "productInfo", "maxLength": 64, "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" }, "displayName": { "description": "The display name of the template.", "type": "string", "example": "Product Info", "maxLength": 4096 }, "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.", "type": "boolean", "example": true, "default": false }, "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.", "type": "array", "items": { "title": "Metadata Field (Write)", "description": "A field within a metadata template. Fields can be a basic text, date, or number field, a list of options, or a taxonomy.", "required": [ "type", "key", "displayName" ], "type": "object", "properties": { "type": { "description": "The type of field. The basic fields are a `string` field for text, a `float` field for numbers, and a `date` field to present the user with a date-time picker.\n\nAdditionally, 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.\n\nMetadata taxonomies are also supported as a `taxonomy` field type with a specific set of additional properties, which describe its structure.", "type": "string", "example": "string", "enum": [ "string", "float", "date", "enum", "multiSelect", "taxonomy" ] }, "key": { "description": "A unique identifier for the field. The identifier must be unique within the template to which it belongs.", "type": "string", "example": "category", "maxLength": 256 }, "displayName": { "description": "The display name of the field as it is shown to the user in the web and mobile apps.", "type": "string", "example": "Category", "maxLength": 4096 }, "description": { "description": "A description of the field. This is not shown to the user.", "type": "string", "example": "The category", "maxLength": 4096 }, "hidden": { "description": "Whether this field is hidden in the UI for the user and can only be set through the API instead.", "type": "boolean", "example": true }, "options": { "description": "A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types.", "type": "array", "items": { "title": "Metadata Option (Write)", "type": "object", "description": "An option for a Metadata Template Field.\n\nOptions 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.", "required": [ "key" ], "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.", "type": "string", "example": "Category 1" } } } }, "taxonomyKey": { "description": "The unique key of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "string", "example": "locationTaxonomy" }, "taxonomyId": { "description": "The unique ID of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "string", "example": "05ece6d7-fec4-4d3f-bfd2-36fd4dddea97" }, "namespace": { "description": "The namespace of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "string", "example": "enterprise_123456" }, "optionsRules": { "description": "An object defining additional rules for the options of the taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "object", "properties": { "multiSelect": { "description": "Whether to allow users to select multiple values.", "type": "boolean", "example": true }, "selectableLevels": { "description": "An array of integers defining which levels of the taxonomy are selectable by users.", "type": "array", "items": { "type": "integer" }, "example": [ 1, 2 ] } } } } } }, "copyInstanceOnItemCopy": { "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.", "type": "boolean", "example": true, "default": false } }, "required": [ "scope", "displayName" ] } } } }, "responses": { "201": { "description": "The schema representing the metadata template created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTemplate" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_templates", "tags": [ "Metadata templates" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Create metadata template", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_templates/schema\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"scope\": \"enterprise\",\n \"displayName\": \"Customer\",\n \"fields\": [\n {\n \"type\": \"string\",\n \"key\": \"name\",\n \"displayName\": \"Name\",\n \"description\": \"The customer name\",\n \"hidden\": false\n },\n {\n \"type\": \"date\",\n \"key\": \"last_contacted_at\",\n \"displayName\": \"Last Contacted At\",\n \"description\": \"When this customer was last contacted at\",\n \"hidden\": false\n },\n {\n \"type\": \"enum\",\n \"key\": \"industry\",\n \"displayName\": \"Industry\",\n \"options\": [\n {\"key\": \"Technology\"},\n {\"key\": \"Healthcare\"},\n {\"key\": \"Legal\"}\n ]\n },\n {\n \"type\": \"multiSelect\",\n \"key\": \"role\",\n \"displayName\": \"Contact Role\",\n \"options\": [\n {\"key\": \"Developer\"},\n {\"key\": \"Business Owner\"},\n {\"key\": \"Marketing\"},\n {\"key\": \"Legal\"},\n {\"key\": \"Sales\"}\n ]\n }\n ]\n }'" }, { "lang": "dotnet", "label": "Create metadata template", "source": "await client.MetadataTemplates.CreateMetadataTemplateAsync(requestBody: new CreateMetadataTemplateRequestBody(scope: \"enterprise\", displayName: templateKey) { TemplateKey = templateKey, Fields = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.String, key: \"testName\", displayName: \"testName\"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Float, key: \"age\", displayName: \"age\"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Date, key: \"birthDate\", displayName: \"birthDate\"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Enum, key: \"countryCode\", displayName: \"countryCode\") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"US\"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"CA\")}) },new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.MultiSelect, key: \"sports\", displayName: \"sports\") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"basketball\"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"football\"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"tennis\")}) }}) });" }, { "lang": "swift", "label": "Create metadata template", "source": "try await client.metadataTemplates.createMetadataTemplate(requestBody: CreateMetadataTemplateRequestBody(scope: \"enterprise\", displayName: templateKey, templateKey: templateKey, fields: [CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.string, key: \"testName\", displayName: \"testName\"), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.float, key: \"age\", displayName: \"age\"), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.date, key: \"birthDate\", displayName: \"birthDate\"), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.enum_, key: \"countryCode\", displayName: \"countryCode\", options: [CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"US\"), CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"CA\")]), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.multiSelect, key: \"sports\", displayName: \"sports\", options: [CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"basketball\"), CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"football\"), CreateMetadataTemplateRequestBodyFieldsOptionsField(key: \"tennis\")])]))" }, { "lang": "java", "label": "Create metadata template", "source": "client.getMetadataTemplates().createMetadataTemplate(new CreateMetadataTemplateRequestBody.Builder(\"enterprise\", templateKey).templateKey(templateKey).fields(Arrays.asList(new CreateMetadataTemplateRequestBodyFieldsField(CreateMetadataTemplateRequestBodyFieldsTypeField.STRING, \"testName\", \"testName\"), new CreateMetadataTemplateRequestBodyFieldsField(CreateMetadataTemplateRequestBodyFieldsTypeField.FLOAT, \"age\", \"age\"), new CreateMetadataTemplateRequestBodyFieldsField(CreateMetadataTemplateRequestBodyFieldsTypeField.DATE, \"birthDate\", \"birthDate\"), new CreateMetadataTemplateRequestBodyFieldsField.Builder(CreateMetadataTemplateRequestBodyFieldsTypeField.ENUM, \"countryCode\", \"countryCode\").options(Arrays.asList(new CreateMetadataTemplateRequestBodyFieldsOptionsField(\"US\"), new CreateMetadataTemplateRequestBodyFieldsOptionsField(\"CA\"))).build(), new CreateMetadataTemplateRequestBodyFieldsField.Builder(CreateMetadataTemplateRequestBodyFieldsTypeField.MULTISELECT, \"sports\", \"sports\").options(Arrays.asList(new CreateMetadataTemplateRequestBodyFieldsOptionsField(\"basketball\"), new CreateMetadataTemplateRequestBodyFieldsOptionsField(\"football\"), new CreateMetadataTemplateRequestBodyFieldsOptionsField(\"tennis\"))).build())).build())" }, { "lang": "node", "label": "Create metadata template", "source": "await client.metadataTemplates.createMetadataTemplate({\n scope: 'enterprise',\n displayName: templateKey,\n templateKey: templateKey,\n fields: [\n {\n type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField,\n key: 'testName',\n displayName: 'testName',\n } satisfies CreateMetadataTemplateRequestBodyFieldsField,\n {\n type: 'float' as CreateMetadataTemplateRequestBodyFieldsTypeField,\n key: 'age',\n displayName: 'age',\n } satisfies CreateMetadataTemplateRequestBodyFieldsField,\n {\n type: 'date' as CreateMetadataTemplateRequestBodyFieldsTypeField,\n key: 'birthDate',\n displayName: 'birthDate',\n } satisfies CreateMetadataTemplateRequestBodyFieldsField,\n {\n type: 'enum' as CreateMetadataTemplateRequestBodyFieldsTypeField,\n key: 'countryCode',\n displayName: 'countryCode',\n options: [\n {\n key: 'US',\n } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,\n {\n key: 'CA',\n } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,\n ],\n } satisfies CreateMetadataTemplateRequestBodyFieldsField,\n {\n type: 'multiSelect' as CreateMetadataTemplateRequestBodyFieldsTypeField,\n key: 'sports',\n displayName: 'sports',\n options: [\n {\n key: 'basketball',\n } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,\n {\n key: 'football',\n } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,\n {\n key: 'tennis',\n } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,\n ],\n } satisfies CreateMetadataTemplateRequestBodyFieldsField,\n ],\n} satisfies CreateMetadataTemplateRequestBody);" }, { "lang": "python", "label": "Create metadata template", "source": "client.metadata_templates.create_metadata_template(\n \"enterprise\",\n template_key,\n template_key=template_key,\n fields=[\n CreateMetadataTemplateFields(\n type=CreateMetadataTemplateFieldsTypeField.STRING,\n key=\"testName\",\n display_name=\"testName\",\n ),\n CreateMetadataTemplateFields(\n type=CreateMetadataTemplateFieldsTypeField.FLOAT,\n key=\"age\",\n display_name=\"age\",\n ),\n CreateMetadataTemplateFields(\n type=CreateMetadataTemplateFieldsTypeField.DATE,\n key=\"birthDate\",\n display_name=\"birthDate\",\n ),\n CreateMetadataTemplateFields(\n type=CreateMetadataTemplateFieldsTypeField.ENUM,\n key=\"countryCode\",\n display_name=\"countryCode\",\n options=[\n CreateMetadataTemplateFieldsOptionsField(key=\"US\"),\n CreateMetadataTemplateFieldsOptionsField(key=\"CA\"),\n ],\n ),\n CreateMetadataTemplateFields(\n type=CreateMetadataTemplateFieldsTypeField.MULTISELECT,\n key=\"sports\",\n display_name=\"sports\",\n options=[\n CreateMetadataTemplateFieldsOptionsField(key=\"basketball\"),\n CreateMetadataTemplateFieldsOptionsField(key=\"football\"),\n CreateMetadataTemplateFieldsOptionsField(key=\"tennis\"),\n ],\n ),\n ],\n)" } ] } }, "/metadata_templates/schema#classifications": { "post": { "operationId": "post_metadata_templates_schema#classifications", "summary": "Add initial classifications", "description": "When an enterprise does not yet have any classifications, this API call initializes the classification template with an initial set of classifications.\n\nIf an enterprise already has a classification, the template will already exist and instead an API call should be made to add additional classifications.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "templateKey": { "description": "Defines the list of metadata templates.", "type": "string", "example": "securityClassification-6VMVochwUWo", "enum": [ "securityClassification-6VMVochwUWo" ] }, "displayName": { "description": "The name of the template as shown in web and mobile interfaces.", "type": "string", "example": "Classification", "enum": [ "Classification" ] }, "hidden": { "description": "Determines if the classification template is hidden or available on web and mobile devices.", "type": "boolean", "example": false }, "copyInstanceOnItemCopy": { "description": "Determines if classifications are copied along when the file or folder is copied.", "type": "boolean", "example": false }, "fields": { "description": "The classification template requires exactly one field, which holds all the valid classification values.", "type": "array", "items": { "required": [ "type", "key", "displayName", "options" ], "type": "object", "description": "The `enum` field which holds all the valid classification values.", "properties": { "type": { "description": "The type of the field that is always enum.", "type": "string", "example": "enum", "enum": [ "enum" ] }, "key": { "description": "Defines classifications available in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { "description": "A display name for the classification.", "type": "string", "example": "Classification", "enum": [ "Classification" ] }, "hidden": { "description": "Determines if the classification template is hidden or available on web and mobile devices.", "type": "boolean", "example": false }, "options": { "description": "The actual list of classifications that are present on this template.", "type": "array", "items": { "required": [ "key" ], "type": "object", "description": "An individual classification.", "properties": { "key": { "description": "The display name and key this classification. This will be show in the Box UI.", "type": "string", "example": "Sensitive" }, "staticConfig": { "description": "Additional information about the classification.", "type": "object", "properties": { "classification": { "description": "Additional information about the classification.", "type": "object", "properties": { "classificationDefinition": { "description": "A longer description of the classification.", "type": "string", "example": "Sensitive information" }, "colorID": { "description": "An identifier used to assign a color to a classification label.\n\nMapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows.\n\n- `0`: Yellow.\n- `1`: Orange.\n- `2`: Watermelon red.\n- `3`: Purple rain.\n- `4`: Light blue.\n- `5`: Dark blue.\n- `6`: Light green.\n- `7`: Gray.", "type": "integer", "format": "int64", "example": 4 } } } } } } } } } } } }, "required": [ "scope", "displayName", "fields", "templateKey" ] } } } }, "responses": { "200": { "description": "Returns a new `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationTemplate" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a template name is not correct. Please make sure the URL for the request is correct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "classifications", "tags": [ "Classifications" ], "x-codeSamples": [ { "lang": "curl", "label": "Add initial classifications", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_templates/schema\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"templateKey\": \"securityClassification-6VMVochwUWo\",\n \"scope\": \"enterprise\",\n \"displayName\": \"Classification\",\n \"hidden\": false,\n \"copyInstanceOnItemCopy\": true,\n \"fields\": [\n {\n \"type\": \"enum\",\n \"key\": \"Box__Security__Classification__Key\",\n \"displayName\": \"Classification\",\n \"hidden\": false,\n \"options\": [\n {\n \"key\": \"Classified\",\n \"staticConfig\": {\n \"classification\": {\n \"colorID\": 7,\n \"classificationDefinition\": \"Top Seret\"\n }\n }\n }\n ]\n }\n ]\n }'" } ] } }, "/metadata_cascade_policies": { "get": { "operationId": "get_metadata_cascade_policies", "summary": "List metadata cascade policies", "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`.", "parameters": [ { "name": "folder_id", "in": "query", "description": "Specifies which folder to return policies for. This can not be used on the root folder with ID `0`.", "required": true, "schema": { "type": "string" }, "example": "31232" }, { "name": "owner_enterprise_id", "in": "query", "description": "The ID of the enterprise ID for which to find metadata cascade policies. If not specified, it defaults to the current enterprise.", "schema": { "type": "string" }, "example": "31232" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of metadata cascade policies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataCascadePolicies" } } } }, "400": { "description": "Returns an error when any of the parameters are not in a valid format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the folder can not be accessed. This error often happens when accessing the root folder with ID `0`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the folder can not be found or the user does not have access to the folder.\n\n- `not_found` - The folder could not be found or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_cascade_policies", "tags": [ "Metadata cascade policies" ], "x-codeSamples": [ { "lang": "curl", "label": "List metadata cascade policies", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_cascade_policies?folder_id=31232\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List metadata cascade policies", "source": "await client.MetadataCascadePolicies.GetMetadataCascadePoliciesAsync(queryParams: new GetMetadataCascadePoliciesQueryParams(folderId: folder.Id));" }, { "lang": "swift", "label": "List metadata cascade policies", "source": "try await client.metadataCascadePolicies.getMetadataCascadePolicies(queryParams: GetMetadataCascadePoliciesQueryParams(folderId: folder.id))" }, { "lang": "java", "label": "List metadata cascade policies", "source": "client.getMetadataCascadePolicies().getMetadataCascadePolicies(new GetMetadataCascadePoliciesQueryParams(folder.getId()))" }, { "lang": "node", "label": "List metadata cascade policies", "source": "await client.metadataCascadePolicies.getMetadataCascadePolicies({\n folderId: folder.id,\n} satisfies GetMetadataCascadePoliciesQueryParams);" }, { "lang": "python", "label": "List metadata cascade policies", "source": "client.metadata_cascade_policies.get_metadata_cascade_policies(folder.id)" } ] }, "post": { "operationId": "post_metadata_cascade_policies", "summary": "Create metadata cascade policy", "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.\n\nIn order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "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.", "type": "string", "example": "1234567" }, "scope": { "description": "The scope of the targeted metadata template. This template will need to already have an instance applied to the targeted folder.", "type": "string", "example": "enterprise", "enum": [ "global", "enterprise" ] }, "templateKey": { "description": "The key of the targeted metadata template. This template will need to already have an instance applied to the targeted folder.\n\nIn 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.\n\nPlease [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template's key.\n\n[list]: /reference/get-metadata-templates-enterprise\n[file]: /reference/get-files-id-metadata\n[folder]: /reference/get-folders-id-metadata", "type": "string", "example": "productInfo" } }, "required": [ "folder_id", "scope", "templateKey" ] } } } }, "responses": { "201": { "description": "Returns a new of metadata cascade policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataCascadePolicy" } } } }, "400": { "description": "Returns an error when any of the parameters are not in a valid format.\n\n- `bad_request` - Either the `scope`, `templateKey`, or `folder_id` are not in a valid format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when trying to apply a policy to a restricted folder, for example the root folder with ID `0`.\n\n- `forbidden` - Although the folder ID was valid and the user has access to the folder, the policy could not be applied to this folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.\n\n- `instance_tuple_not_found` - The template could not be found or the user does not have access to the template.\n- `not_found` - The folder could not be found or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error when a policy for this folder and template is already in place.\n\n- `tuple_already_exists` - A cascade policy for this combination of `folder_id`, `scope` and `templateKey` already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_cascade_policies", "tags": [ "Metadata cascade policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Create metadata cascade policy", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_cascade_policies\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"folder_id\": \"12321\",\n \"scope\": \"enterprise_27335\",\n \"templateKey\": \"productInfo\"\n }'" }, { "lang": "dotnet", "label": "Create metadata cascade policy", "source": "await client.MetadataCascadePolicies.CreateMetadataCascadePolicyAsync(requestBody: new CreateMetadataCascadePolicyRequestBody(folderId: folder.Id, scope: CreateMetadataCascadePolicyRequestBodyScopeField.Enterprise, templateKey: templateKey));" }, { "lang": "swift", "label": "Create metadata cascade policy", "source": "try await client.metadataCascadePolicies.createMetadataCascadePolicy(requestBody: CreateMetadataCascadePolicyRequestBody(folderId: folder.id, scope: CreateMetadataCascadePolicyRequestBodyScopeField.enterprise, templateKey: templateKey))" }, { "lang": "java", "label": "Create metadata cascade policy", "source": "client.getMetadataCascadePolicies().createMetadataCascadePolicy(new CreateMetadataCascadePolicyRequestBody(folder.getId(), CreateMetadataCascadePolicyRequestBodyScopeField.ENTERPRISE, templateKey))" }, { "lang": "node", "label": "Create metadata cascade policy", "source": "await client.metadataCascadePolicies.createMetadataCascadePolicy({\n folderId: folder.id,\n scope: 'enterprise' as CreateMetadataCascadePolicyRequestBodyScopeField,\n templateKey: templateKey,\n} satisfies CreateMetadataCascadePolicyRequestBody);" }, { "lang": "python", "label": "Create metadata cascade policy", "source": "client.metadata_cascade_policies.create_metadata_cascade_policy(\n folder.id, CreateMetadataCascadePolicyScope.ENTERPRISE, template_key\n)" } ] } }, "/metadata_cascade_policies/{metadata_cascade_policy_id}": { "get": { "operationId": "get_metadata_cascade_policies_id", "summary": "Get metadata cascade policy", "description": "Retrieve a specific metadata cascade policy assigned to a folder.", "parameters": [ { "name": "metadata_cascade_policy_id", "in": "path", "description": "The ID of the metadata cascade policy.", "required": true, "schema": { "type": "string" }, "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" } ], "responses": { "200": { "description": "Returns a metadata cascade policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataCascadePolicy" } } } }, "404": { "description": "Returns an error when the policy can not be found or the user does not have access to the folder.\n\n- `instance_not_found` - The policy could not be found\n- `not_found` - The folder could not be found or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_cascade_policies", "tags": [ "Metadata cascade policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata cascade policy", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_cascade_policies/324324\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata cascade policy", "source": "await client.MetadataCascadePolicies.GetMetadataCascadePolicyByIdAsync(metadataCascadePolicyId: cascadePolicyId);" }, { "lang": "swift", "label": "Get metadata cascade policy", "source": "try await client.metadataCascadePolicies.getMetadataCascadePolicyById(metadataCascadePolicyId: cascadePolicyId)" }, { "lang": "java", "label": "Get metadata cascade policy", "source": "client.getMetadataCascadePolicies().getMetadataCascadePolicyById(cascadePolicyId)" }, { "lang": "node", "label": "Get metadata cascade policy", "source": "await client.metadataCascadePolicies.getMetadataCascadePolicyById(\n cascadePolicyId,\n);" }, { "lang": "python", "label": "Get metadata cascade policy", "source": "client.metadata_cascade_policies.get_metadata_cascade_policy_by_id(cascade_policy_id)" } ] }, "delete": { "operationId": "delete_metadata_cascade_policies_id", "summary": "Remove metadata cascade policy", "description": "Deletes a metadata cascade policy.", "parameters": [ { "name": "metadata_cascade_policy_id", "in": "path", "description": "The ID of the metadata cascade policy.", "required": true, "schema": { "type": "string" }, "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" } ], "responses": { "204": { "description": "Returns an empty response when the policy is successfully deleted." }, "404": { "description": "Returns an error when the policy can not be found or the user does not have access to the folder.\n\n- `instance_not_found` - The policy could not be found\n- `not_found` - The folder could not be found or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_cascade_policies", "tags": [ "Metadata cascade policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove metadata cascade policy", "source": "curl -i -X DELETE \"https://api.box.com/2.0/metadata_cascade_policies/324324\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove metadata cascade policy", "source": "await client.MetadataCascadePolicies.DeleteMetadataCascadePolicyByIdAsync(metadataCascadePolicyId: cascadePolicyId);" }, { "lang": "swift", "label": "Remove metadata cascade policy", "source": "try await client.metadataCascadePolicies.deleteMetadataCascadePolicyById(metadataCascadePolicyId: cascadePolicyId)" }, { "lang": "java", "label": "Remove metadata cascade policy", "source": "client.getMetadataCascadePolicies().deleteMetadataCascadePolicyById(cascadePolicyId)" }, { "lang": "node", "label": "Remove metadata cascade policy", "source": "await client.metadataCascadePolicies.deleteMetadataCascadePolicyById(\n cascadePolicyId,\n);" }, { "lang": "python", "label": "Remove metadata cascade policy", "source": "client.metadata_cascade_policies.delete_metadata_cascade_policy_by_id(cascade_policy_id)" } ] } }, "/metadata_cascade_policies/{metadata_cascade_policy_id}/apply": { "post": { "operationId": "post_metadata_cascade_policies_id_apply", "summary": "Force-apply metadata cascade policy to folder", "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.", "parameters": [ { "name": "metadata_cascade_policy_id", "in": "path", "description": "The ID of the cascade policy to force-apply.", "required": true, "schema": { "type": "string" }, "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "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.\n\n- `none` will preserve the existing value on the file\n- `overwrite` will force-apply the templates values over any existing values.", "type": "string", "example": "none", "enum": [ "none", "overwrite" ] } }, "required": [ "conflict_resolution" ] } } } }, "responses": { "202": { "description": "Returns an empty response when the API call was successful. The metadata cascade operation will be performed asynchronously.\n\nThe 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": { "description": "Returns an error when the policy can not be found or the user does not have access to the folder.\n\n- `instance_not_found` - The policy could not be found\n- `not_found` - The folder could not be found or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_cascade_policies", "tags": [ "Metadata cascade policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Force-apply metadata cascade policy to folder", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_cascade_policies/21312/apply\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"conflict_resolution\": \"overwrite\"\n }'" }, { "lang": "dotnet", "label": "Force-apply metadata cascade policy to folder", "source": "await client.MetadataCascadePolicies.ApplyMetadataCascadePolicyAsync(metadataCascadePolicyId: cascadePolicyId, requestBody: new ApplyMetadataCascadePolicyRequestBody(conflictResolution: ApplyMetadataCascadePolicyRequestBodyConflictResolutionField.Overwrite));" }, { "lang": "swift", "label": "Force-apply metadata cascade policy to folder", "source": "try await client.metadataCascadePolicies.applyMetadataCascadePolicy(metadataCascadePolicyId: cascadePolicyId, requestBody: ApplyMetadataCascadePolicyRequestBody(conflictResolution: ApplyMetadataCascadePolicyRequestBodyConflictResolutionField.overwrite))" }, { "lang": "java", "label": "Force-apply metadata cascade policy to folder", "source": "client.getMetadataCascadePolicies().applyMetadataCascadePolicy(cascadePolicyId, new ApplyMetadataCascadePolicyRequestBody(ApplyMetadataCascadePolicyRequestBodyConflictResolutionField.OVERWRITE))" }, { "lang": "node", "label": "Force-apply metadata cascade policy to folder", "source": "await client.metadataCascadePolicies.applyMetadataCascadePolicy(\n cascadePolicyId,\n {\n conflictResolution:\n 'overwrite' as ApplyMetadataCascadePolicyRequestBodyConflictResolutionField,\n } satisfies ApplyMetadataCascadePolicyRequestBody,\n);" }, { "lang": "python", "label": "Force-apply metadata cascade policy to folder", "source": "client.metadata_cascade_policies.apply_metadata_cascade_policy(\n cascade_policy_id, ApplyMetadataCascadePolicyConflictResolution.OVERWRITE\n)" } ] } }, "/metadata_queries/execute_read": { "post": { "operationId": "post_metadata_queries_execute_read", "summary": "Query files/folders by metadata", "description": "Create a search using SQL-like syntax to return items that match specific metadata.\n\nBy default, this endpoint returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataQuery" } } } }, "responses": { "200": { "description": "Returns a list of files and folders that match this metadata query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataQueryResults" } } } }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.\n- `unexpected_json_type` - An argument from the `query` string is not present in `query_param`. For example, `query` of `name = :name` requires the `query_param` to include a value for the `name` argument, for example `{ \"name\": \"Box, Inc\" }`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when a metadata template with the given `scope` and `templateKey` can not be found. The error response will include extra details.\n\n- `instance_not_found` - The template was not found. Please make sure to use the full template scope including the enterprise ID, like `enterprise_12345`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "search", "tags": [ "Search" ], "x-codeSamples": [ { "lang": "curl", "label": "Query files/folders by metadata", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_queries/execute_read\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"from\": \"enterprise_123456.contractTemplate\",\n \"query\": \"amount >= :value\",\n \"query_params\": {\n \"value\": 100\n },\n \"fields\": [\n \"created_at\",\n \"metadata.enterprise_123456.contractTemplate.amount\",\n \"metadata.enterprise_123456.contractTemplate.customerName\"\n ],\n \"ancestor_folder_id\": \"5555\",\n \"order_by\": [\n {\n \"field_key\": \"amount\",\n \"direction\": \"asc\"\n }\n ],\n \"limit\": 100\n }'" }, { "lang": "dotnet", "label": "Query files/folders by metadata", "source": "await client.Search.SearchByMetadataQueryAsync(requestBody: new MetadataQuery(ancestorFolderId: \"0\", from: searchFrom) { Query = \"name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports\", QueryParams = new Dictionary() { { \"name\", \"John\" }, { \"age\", 50 }, { \"birthDate\", \"2001-01-01T02:20:10.120Z\" }, { \"countryCode\", \"US\" }, { \"sports\", Array.AsReadOnly(new [] {\"basketball\",\"tennis\"}) } } });" }, { "lang": "swift", "label": "Query files/folders by metadata", "source": "try await client.search.searchByMetadataQuery(requestBody: MetadataQuery(ancestorFolderId: \"0\", from: searchFrom, query: \"name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports\", queryParams: [\"name\": \"John\", \"age\": 50, \"birthDate\": \"2001-01-01T02:20:10.120Z\", \"countryCode\": \"US\", \"sports\": [\"basketball\", \"tennis\"]]))" }, { "lang": "java", "label": "Query files/folders by metadata", "source": "client.getSearch().searchByMetadataQuery(new MetadataQuery.Builder(searchFrom, \"0\").query(\"name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports\").queryParams(mapOf(entryOf(\"name\", \"John\"), entryOf(\"age\", 50), entryOf(\"birthDate\", \"2001-01-01T02:20:10.120Z\"), entryOf(\"countryCode\", \"US\"), entryOf(\"sports\", Arrays.asList(\"basketball\", \"tennis\")))).build())" }, { "lang": "node", "label": "Query files/folders by metadata", "source": "await client.search.searchByMetadataQuery({\n ancestorFolderId: '0',\n from: searchFrom,\n query:\n 'name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports',\n queryParams: {\n ['name']: 'John',\n ['age']: 50,\n ['birthDate']: '2001-01-01T02:20:10.120Z',\n ['countryCode']: 'US',\n ['sports']: ['basketball', 'tennis'],\n },\n} satisfies MetadataQuery);" }, { "lang": "python", "label": "Query files/folders by metadata", "source": "client.search.search_by_metadata_query(\n search_from,\n \"0\",\n query=\"name = :name AND age < :age AND birthDate >= :birthDate AND countryCode = :countryCode AND sports = :sports\",\n query_params={\n \"name\": \"John\",\n \"age\": 50,\n \"birthDate\": \"2001-01-01T02:20:10.120Z\",\n \"countryCode\": \"US\",\n \"sports\": [\"basketball\", \"tennis\"],\n },\n)" } ] } }, "/comments/{comment_id}": { "get": { "operationId": "get_comments_id", "summary": "Get comment", "description": "Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment.", "parameters": [ { "name": "comment_id", "in": "path", "description": "The ID of the comment.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns a full comment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "comments", "tags": [ "Comments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get comment", "source": "curl -i -X GET \"https://api.box.com/2.0/comments/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get comment", "source": "await client.Comments.GetCommentByIdAsync(commentId: NullableUtils.Unwrap(newComment.Id));" }, { "lang": "swift", "label": "Get comment", "source": "try await client.comments.getCommentById(commentId: newComment.id!)" }, { "lang": "java", "label": "Get comment", "source": "client.getComments().getCommentById(newComment.getId())" }, { "lang": "node", "label": "Get comment", "source": "await client.comments.getCommentById(newComment.id!);" }, { "lang": "python", "label": "Get comment", "source": "client.comments.get_comment_by_id(new_comment.id)" } ] }, "put": { "operationId": "put_comments_id", "summary": "Update comment", "description": "Update the message of a comment.", "parameters": [ { "name": "comment_id", "in": "path", "description": "The ID of the comment.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "description": "The text of the comment to update.", "type": "string", "example": "Review completed!" } } } } } }, "responses": { "200": { "description": "Returns the updated comment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "comments", "tags": [ "Comments" ], "x-codeSamples": [ { "lang": "curl", "label": "Update comment", "source": "curl -i -X PUT \"https://api.box.com/2.0/comments/12345\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"message\": \"My New Message\"\n }'" }, { "lang": "dotnet", "label": "Update comment", "source": "await client.Comments.UpdateCommentByIdAsync(commentId: NullableUtils.Unwrap(newReplyComment.Id), requestBody: new UpdateCommentByIdRequestBody() { Message = newMessage });" }, { "lang": "swift", "label": "Update comment", "source": "try await client.comments.updateCommentById(commentId: newReplyComment.id!, requestBody: UpdateCommentByIdRequestBody(message: newMessage))" }, { "lang": "java", "label": "Update comment", "source": "client.getComments().updateCommentById(newReplyComment.getId(), new UpdateCommentByIdRequestBody.Builder().message(newMessage).build())" }, { "lang": "node", "label": "Update comment", "source": "await client.comments.updateCommentById(newReplyComment.id!, {\n requestBody: { message: newMessage } satisfies UpdateCommentByIdRequestBody,\n} satisfies UpdateCommentByIdOptionalsInput);" }, { "lang": "python", "label": "Update comment", "source": "client.comments.update_comment_by_id(new_reply_comment.id, message=new_message)" } ] }, "delete": { "operationId": "delete_comments_id", "summary": "Remove comment", "description": "Permanently deletes a comment.", "parameters": [ { "name": "comment_id", "in": "path", "description": "The ID of the comment.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the comment has been deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "comments", "tags": [ "Comments" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove comment", "source": "curl -i -X DELETE \"https://api.box.com/2.0/comments/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove comment", "source": "await client.Comments.DeleteCommentByIdAsync(commentId: NullableUtils.Unwrap(newComment.Id));" }, { "lang": "swift", "label": "Remove comment", "source": "try await client.comments.deleteCommentById(commentId: newComment.id!)" }, { "lang": "java", "label": "Remove comment", "source": "client.getComments().deleteCommentById(newComment.getId())" }, { "lang": "node", "label": "Remove comment", "source": "await client.comments.deleteCommentById(newComment.id!);" }, { "lang": "python", "label": "Remove comment", "source": "client.comments.delete_comment_by_id(new_comment.id)" } ] } }, "/comments": { "post": { "operationId": "post_comments", "summary": "Create comment", "description": "Adds a comment by the user to a specific file, or as a reply to an other comment.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "description": "The text of the comment.\n\nTo mention a user, use the `tagged_message` parameter instead.", "type": "string", "example": "Review completed!" }, "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.\n\nThe `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.\n\nIf you are not mentioning another user, use `message` instead.", "type": "string", "example": "@[1234:John] Review completed!" }, "item": { "description": "The item to attach the comment to.", "type": "object", "properties": { "id": { "description": "The ID of the item.", "type": "string", "example": "11446498" }, "type": { "description": "The type of the item that this comment will be placed on.", "type": "string", "example": "file", "enum": [ "file", "comment" ] } }, "required": [ "id", "type" ] } }, "required": [ "message", "item" ] } } } }, "responses": { "201": { "description": "Returns the newly created comment object.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "comments", "tags": [ "Comments" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Create comment", "source": "curl -i -X POST \"https://api.box.com/2.0/comments\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"message\": \"Review completed!\",\n \"item\": {\n \"type\": \"file\",\n \"id\": 426436\n }\n }'" }, { "lang": "dotnet", "label": "Create comment", "source": "await client.Comments.CreateCommentAsync(requestBody: new CreateCommentRequestBody(message: message, item: new CreateCommentRequestBodyItemField(id: fileId, type: CreateCommentRequestBodyItemTypeField.File)));" }, { "lang": "swift", "label": "Create comment", "source": "try await client.comments.createComment(requestBody: CreateCommentRequestBody(message: message, item: CreateCommentRequestBodyItemField(id: fileId, type: CreateCommentRequestBodyItemTypeField.file)))" }, { "lang": "java", "label": "Create comment", "source": "client.getComments().createComment(new CreateCommentRequestBody(message, new CreateCommentRequestBodyItemField(fileId, CreateCommentRequestBodyItemTypeField.FILE)))" }, { "lang": "node", "label": "Create comment", "source": "await client.comments.createComment({\n message: message,\n item: {\n id: fileId,\n type: 'file' as CreateCommentRequestBodyItemTypeField,\n } satisfies CreateCommentRequestBodyItemField,\n} satisfies CreateCommentRequestBody);" }, { "lang": "python", "label": "Create comment", "source": "client.comments.create_comment(\n message, CreateCommentItem(id=file_id, type=CreateCommentItemTypeField.FILE)\n)" } ] } }, "/collaborations/{collaboration_id}": { "get": { "operationId": "get_collaborations_id", "summary": "Get collaboration", "description": "Retrieves a single collaboration.", "parameters": [ { "name": "collaboration_id", "in": "path", "description": "The ID of the collaboration.", "required": true, "schema": { "type": "string" }, "example": "1234" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns a collaboration object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaboration" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "user_collaborations", "tags": [ "Collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "Get collaboration", "source": "curl -i -X GET \"https://api.box.com/2.0/collaborations/1234\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get collaboration", "source": "await client.UserCollaborations.GetCollaborationByIdAsync(collaborationId: collaborationId);" }, { "lang": "swift", "label": "Get collaboration", "source": "try await client.userCollaborations.getCollaborationById(collaborationId: collaborationId)" }, { "lang": "java", "label": "Get collaboration", "source": "client.getUserCollaborations().getCollaborationById(collaborationId)" }, { "lang": "node", "label": "Get collaboration", "source": "await client.userCollaborations.getCollaborationById(collaborationId);" }, { "lang": "python", "label": "Get collaboration", "source": "client.user_collaborations.get_collaboration_by_id(collaboration_id)" } ] }, "put": { "operationId": "put_collaborations_id", "summary": "Update collaboration", "description": "Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. In case of accepting collaboration invite, role is not required.", "parameters": [ { "name": "collaboration_id", "in": "path", "description": "The ID of the collaboration.", "required": true, "schema": { "type": "string" }, "example": "1234" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "description": "The level of access granted.", "type": "string", "example": "editor", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner", "owner" ] }, "status": { "description": "Set the status of a `pending` collaboration invitation, effectively accepting, or rejecting the invite.", "type": "string", "example": "accepted", "enum": [ "pending", "accepted", "rejected" ] }, "expires_at": { "description": "Update the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item.\n\nThis 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.\n\nAdditionally, a collaboration can only be given an expiration if it was created after the **Automatically remove invited collaborator** setting was enabled.", "type": "string", "format": "date-time", "example": "2019-08-29T23:59:00-07:00" }, "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.\n\nBe 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.\n\nOnly an owner or co-owners can invite collaborators with a `can_view_path` of `true`. Only an owner can update `can_view_path` on existing collaborations.\n\n`can_view_path` can only be used for folder collaborations.\n\nWhen you delete a folder with `can_view_path=true`, collaborators may still see the parent path. For instructions on how to remove this, see [Even though a folder invited via can_view_path is deleted, the path remains displayed](https://support.box.com/hc/en-us/articles/37472814319891-Even-though-a-folder-invited-via-can-view-path-is-deleted-the-path-remains-displayed).", "type": "boolean", "example": true } } } } } }, "responses": { "200": { "description": "Returns an updated collaboration object unless the owner has changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaboration" } } } }, "204": { "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": { "description": "Returns an error if the authenticated user does not have the right permissions to update the collaboration.\n\nAdditionally, 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "user_collaborations", "tags": [ "Collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "Update collaboration", "source": "curl -i -X PUT \"https://api.box.com/2.0/collaborations/1234\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"role\": \"viewer\"\n }'" }, { "lang": "dotnet", "label": "Update collaboration", "source": "await client.UserCollaborations.UpdateCollaborationByIdAsync(collaborationId: collaborationId, requestBody: new UpdateCollaborationByIdRequestBody() { Role = UpdateCollaborationByIdRequestBodyRoleField.Viewer });" }, { "lang": "swift", "label": "Update collaboration", "source": "try await client.userCollaborations.updateCollaborationById(collaborationId: collaborationId, requestBody: UpdateCollaborationByIdRequestBody(role: UpdateCollaborationByIdRequestBodyRoleField.viewer))" }, { "lang": "java", "label": "Update collaboration", "source": "client.getUserCollaborations().updateCollaborationById(collaborationId, new UpdateCollaborationByIdRequestBody.Builder().role(UpdateCollaborationByIdRequestBodyRoleField.VIEWER).build())" }, { "lang": "node", "label": "Update collaboration", "source": "await client.userCollaborations.updateCollaborationById(collaborationId, {\n requestBody: {\n role: 'viewer' as UpdateCollaborationByIdRequestBodyRoleField,\n } satisfies UpdateCollaborationByIdRequestBody,\n} satisfies UpdateCollaborationByIdOptionalsInput);" }, { "lang": "python", "label": "Update collaboration", "source": "client.user_collaborations.update_collaboration_by_id(\n collaboration_id, role=UpdateCollaborationByIdRole.VIEWER\n)" } ] }, "delete": { "operationId": "delete_collaborations_id", "summary": "Remove collaboration", "description": "Deletes a single collaboration.", "parameters": [ { "name": "collaboration_id", "in": "path", "description": "The ID of the collaboration.", "required": true, "schema": { "type": "string" }, "example": "1234" } ], "responses": { "204": { "description": "A blank response is returned if the collaboration was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "user_collaborations", "tags": [ "Collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove collaboration", "source": "curl -i -X DELETE \"https://api.box.com/2.0/collaborations/1234\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove collaboration", "source": "await client.UserCollaborations.DeleteCollaborationByIdAsync(collaborationId: collaborationId);" }, { "lang": "swift", "label": "Remove collaboration", "source": "try await client.userCollaborations.deleteCollaborationById(collaborationId: collaborationId)" }, { "lang": "java", "label": "Remove collaboration", "source": "client.getUserCollaborations().deleteCollaborationById(collaborationId)" }, { "lang": "node", "label": "Remove collaboration", "source": "await client.userCollaborations.deleteCollaborationById(collaborationId);" }, { "lang": "python", "label": "Remove collaboration", "source": "client.user_collaborations.delete_collaboration_by_id(collaboration_id)" } ] } }, "/collaborations": { "get": { "operationId": "get_collaborations", "summary": "List pending collaborations", "description": "Retrieves all pending collaboration invites for this user.", "parameters": [ { "name": "status", "in": "query", "description": "The status of the collaborations to retrieve.", "required": true, "schema": { "type": "string", "enum": [ "pending" ] }, "example": "pending" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of pending collaboration objects.\n\nIf the user has no pending collaborations, the collection will be empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationsOffsetPaginated" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "list_collaborations", "tags": [ "Collaborations (List)" ], "x-codeSamples": [ { "lang": "curl", "label": "List pending collaborations", "source": "curl -i -X GET \"https://api.box.com/2.0/collaborations?status=pending\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List pending collaborations", "source": "await client.ListCollaborations.GetCollaborationsAsync(queryParams: new GetCollaborationsQueryParams(status: GetCollaborationsQueryParamsStatusField.Pending));" }, { "lang": "swift", "label": "List pending collaborations", "source": "try await client.listCollaborations.getCollaborations(queryParams: GetCollaborationsQueryParams(status: GetCollaborationsQueryParamsStatusField.pending))" }, { "lang": "java", "label": "List pending collaborations", "source": "client.getListCollaborations().getCollaborations(new GetCollaborationsQueryParams(GetCollaborationsQueryParamsStatusField.PENDING))" }, { "lang": "node", "label": "List pending collaborations", "source": "await client.listCollaborations.getCollaborations({\n status: 'pending' as GetCollaborationsQueryParamsStatusField,\n} satisfies GetCollaborationsQueryParams);" }, { "lang": "python", "label": "List pending collaborations", "source": "client.list_collaborations.get_collaborations(GetCollaborationsStatus.PENDING)" } ] }, "post": { "operationId": "post_collaborations", "summary": "Create collaboration", "description": "Adds a collaboration for a single user or a single group to a file or folder.\n\nCollaborations can be created using email address, user IDs, or a group IDs.\n\nIf a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited.\n\nIf collaboration is in `pending` status, field `name` is redacted when:\n\n- a collaboration was created using `user_id`,\n- a collaboration was created using `login`.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "notify", "in": "query", "description": "Determines if users should receive email notification for the action performed.", "required": false, "schema": { "type": "boolean" }, "example": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "description": "The item to attach the comment to.", "type": "object", "properties": { "type": { "description": "The type of the item that this collaboration will be granted access to.", "type": "string", "example": "file", "enum": [ "file", "folder" ] }, "id": { "description": "The ID of the item that will be granted access to.", "type": "string", "example": "11446498" } } }, "accessible_by": { "description": "The user or group to give access to the item.", "type": "object", "properties": { "type": { "description": "The type of collaborator to invite.", "type": "string", "example": "user", "enum": [ "user", "group" ] }, "id": { "description": "The ID of the user or group.\n\nAlternatively, use `login` to specify a user by email address.", "type": "string", "example": "23522323" }, "login": { "description": "The email address of the user to grant access to the item.\n\nAlternatively, use `id` to specify a user by user ID.", "type": "string", "example": "john@example.com" } }, "required": [ "type" ] }, "role": { "description": "The level of access granted.", "type": "string", "example": "editor", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "is_access_only": { "description": "If set to `true`, collaborators have access to shared items, but such items won't be visible in the All Files list. Additionally, collaborators won't see the path to the root folder for the shared item.", "type": "boolean", "example": true }, "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.\n\nBe 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.\n\nOnly an owner or co-owners can invite collaborators with a `can_view_path` of `true`. Only an owner can update `can_view_path` on existing collaborations.\n\n`can_view_path` can only be used for folder collaborations.\n\nWhen you delete a folder with `can_view_path=true`, collaborators may still see the parent path. For instructions on how to remove this, see [Even though a folder invited via can_view_path is deleted, the path remains displayed](https://support.box.com/hc/en-us/articles/37472814319891-Even-though-a-folder-invited-via-can-view-path-is-deleted-the-path-remains-displayed).", "type": "boolean", "example": true }, "expires_at": { "description": "Set the expiration date for the collaboration. At this date, the collaboration will be automatically removed from the item.\n\nThis 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.", "type": "string", "format": "date-time", "example": "2019-08-29T23:59:00-07:00" } }, "required": [ "item", "accessible_by", "role" ] } } } }, "responses": { "201": { "description": "Returns a new collaboration object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collaboration" } } } }, "403": { "description": "Returns an error when the user does not have the right permissions to create the collaboration.\n\n- `forbidden_by_policy`: Creating a collaboration is forbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "user_collaborations", "tags": [ "Collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "Create collaboration", "source": "curl -i -X POST \"https://api.box.com/2.0/collaborations\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"item\": {\n \"type\": \"file\",\n \"id\": \"11446498\"\n },\n \"accessible_by\": {\n \"type\": \"user\",\n \"login\": \"user@example.com\"\n },\n \"role\": \"editor\"\n }'" }, { "lang": "dotnet", "label": "Create collaboration", "source": "await client.UserCollaborations.CreateCollaborationAsync(requestBody: new CreateCollaborationRequestBody(item: new CreateCollaborationRequestBodyItemField() { Type = CreateCollaborationRequestBodyItemTypeField.Folder, Id = folder.Id }, accessibleBy: new CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.User) { Id = user.Id }, role: CreateCollaborationRequestBodyRoleField.Editor));" }, { "lang": "swift", "label": "Create collaboration", "source": "try await client.userCollaborations.createCollaboration(requestBody: CreateCollaborationRequestBody(item: CreateCollaborationRequestBodyItemField(type: CreateCollaborationRequestBodyItemTypeField.folder, id: folder.id), accessibleBy: CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.user, id: user.id), role: CreateCollaborationRequestBodyRoleField.editor))" }, { "lang": "java", "label": "Create collaboration", "source": "client.getUserCollaborations().createCollaboration(new CreateCollaborationRequestBody(new CreateCollaborationRequestBodyItemField.Builder().type(CreateCollaborationRequestBodyItemTypeField.FOLDER).id(folder.getId()).build(), new CreateCollaborationRequestBodyAccessibleByField.Builder(CreateCollaborationRequestBodyAccessibleByTypeField.USER).id(user.getId()).build(), CreateCollaborationRequestBodyRoleField.EDITOR))" }, { "lang": "node", "label": "Create collaboration", "source": "await client.userCollaborations.createCollaboration({\n item: {\n type: 'folder' as CreateCollaborationRequestBodyItemTypeField,\n id: folder.id,\n } satisfies CreateCollaborationRequestBodyItemField,\n accessibleBy: {\n type: 'user' as CreateCollaborationRequestBodyAccessibleByTypeField,\n id: user.id,\n } satisfies CreateCollaborationRequestBodyAccessibleByField,\n role: 'editor' as CreateCollaborationRequestBodyRoleField,\n} satisfies CreateCollaborationRequestBody);" }, { "lang": "python", "label": "Create collaboration", "source": "client.user_collaborations.create_collaboration(\n CreateCollaborationItem(type=CreateCollaborationItemTypeField.FOLDER, id=folder.id),\n CreateCollaborationAccessibleBy(\n type=CreateCollaborationAccessibleByTypeField.USER, id=user.id\n ),\n CreateCollaborationRole.EDITOR,\n)" } ] } }, "/search": { "get": { "operationId": "get_search", "summary": "Search for content", "description": "Searches for files, folders, web links, and shared files across the users content or across the entire enterprise.", "parameters": [ { "name": "query", "in": "query", "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.\n\nThis parameter supports a variety of operators to further refine the results returns.\n\n- `\"\"` - 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.\n- `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.\n- `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.\n- `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.\n\nWe do not support lower case (that is, `and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`) operators.\n\nThis field is required unless the `mdfilters` parameter is defined.", "required": false, "schema": { "type": "string" }, "example": "sales" }, { "name": "scope", "in": "query", "description": "Limits the search results to either the files that the user has access to, or to files available to the entire enterprise.\n\nThe scope defaults to `user_content`, which limits the search results to content that is available to the currently authenticated user.\n\nThe `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.", "required": false, "schema": { "type": "string", "default": "user_content", "enum": [ "user_content", "enterprise_content" ] }, "example": "user_content" }, { "name": "file_extensions", "in": "query", "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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "pdf", "png", "gif" ], "explode": false }, { "name": "created_at_range", "in": "query", "description": "Limits the search results to any items created within a given date range.\n\nDate ranges are defined as comma separated RFC3339 timestamps.\n\nIf the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything created before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "2014-05-15T13:35:01-07:00", "2014-05-17T13:35:01-07:00" ], "explode": false }, { "name": "updated_at_range", "in": "query", "description": "Limits the search results to any items updated within a given date range.\n\nDate ranges are defined as comma separated RFC3339 timestamps.\n\nIf the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything updated before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "2014-05-15T13:35:01-07:00", "2014-05-17T13:35:01-07:00" ], "explode": false }, { "name": "size_range", "in": "query", "description": "Limits the search results to any items with a size within a given file size range. This applied to files and folders.\n\nSize ranges are defined as comma separated list of a lower and upper byte size limit (inclusive).\n\nThe upper and lower bound can be omitted to create open ranges.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "example": [ 1000000, 5000000 ], "explode": false }, { "name": "owner_user_ids", "in": "query", "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.\n\nThe 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.\n\nTo search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "123422", "23532", "3241212" ], "explode": false }, { "name": "recent_updater_user_ids", "in": "query", "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.\n\nThe 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.\n\nThis feature only searches back to the last 10 versions of an item.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "123422", "23532", "3241212" ], "explode": false }, { "name": "ancestor_folder_ids", "in": "query", "description": "Limits the search results to items within the given list of folders, defined as a comma separated lists of folder IDs.\n\nSearch results will also include items within any subfolders of those ancestor folders.\n\nThe 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.\n\nTo search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "4535234", "234123235", "2654345" ], "explode": false }, { "name": "content_types", "in": "query", "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.\n\nContent types are defined as a comma separated lists of Box recognized content types. The allowed content types are as follows.\n\n- `name` - The name of the item, as defined by its `name` field.\n- `description` - The description of the item, as defined by its `description` field.\n- `file_content` - The actual content of the file.\n- `comments` - The content of any of the comments on a file or folder.\n- `tags` - Any tags that are applied to an item, as defined by its `tags` field.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "description", "file_content", "comments", "tags" ] } }, "example": [ "name", "description" ], "explode": false }, { "name": "type", "in": "query", "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.\n\n- `file` - Limits the search results to files,\n- `folder` - Limits the search results to folders,\n- `web_link` - Limits the search results to web links, also known as bookmarks.", "required": false, "schema": { "type": "string", "enum": [ "file", "folder", "web_link" ] }, "example": "file" }, { "name": "trash_content", "in": "query", "description": "Determines if the search should look in the trash for items.\n\nBy default, this API only returns search results for items not currently in the trash (`non_trashed_only`).\n\n- `trashed_only` - Only searches for items currently in the trash\n- `non_trashed_only` - Only searches for items currently not in the trash\n- `all_items` - Searches for both trashed and non-trashed items.", "required": false, "schema": { "type": "string", "default": "non_trashed_only", "enum": [ "non_trashed_only", "trashed_only", "all_items" ] }, "example": "non_trashed_only" }, { "name": "mdfilters", "in": "query", "description": "Limits the search results to any items for which the metadata matches the provided filter. This parameter is a list that specifies exactly **one** metadata template used to filter the search results. The parameter is required unless the `query` parameter is provided.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataFilter" }, "maxItems": 1, "minItems": 1 }, "example": [ { "scope": "enterprise", "templateKey": "contract", "filters": [ { "category": "online" }, { "contractValue": 100000 } ] } ] }, { "name": "sort", "in": "query", "description": "Defines the order in which search results are returned. This API defaults to returning items by relevance unless this parameter is explicitly specified.\n\n- `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.\n- `modified_at` returns the results ordered in descending order by date at which the item was last modified.", "required": false, "schema": { "type": "string", "default": "relevance", "enum": [ "modified_at", "relevance" ] }, "example": "modified_at" }, { "name": "direction", "in": "query", "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.\n\nWhen results are sorted by `relevance` the ordering is locked to returning items in descending order of relevance, and this parameter is ignored.", "required": false, "schema": { "type": "string", "default": "DESC", "enum": [ "DESC", "ASC" ] }, "example": "ASC" }, { "name": "limit", "in": "query", "description": "Defines the maximum number of items to return as part of a page of results.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 30, "maximum": 200 }, "example": 100 }, { "name": "include_recent_shared_links", "in": "query", "description": "Defines whether the search results should include any items that the user recently accessed through a shared link.\n\nWhen 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](/reference/resources/search-results-with-shared-links).", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "deleted_user_ids", "in": "query", "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.\n\nThe `trash_content` parameter needs to be set to `trashed_only`.\n\nIf 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.\n\nIf the user does not have access to any files owned by any of the users, an empty result set is returned.\n\nData available from 2023-02-01 onwards.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "123422", "23532", "3241212" ] }, { "name": "deleted_at_range", "in": "query", "description": "Limits the search results to any items deleted within a given date range.\n\nDate ranges are defined as comma separated RFC3339 timestamps.\n\nIf the start date is omitted (`2014-05-17T13:35:01-07:00`), anything deleted before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00`), the current date will be used as the end date instead.\n\nThe `trash_content` parameter needs to be set to `trashed_only`.\n\nIf searching in trash is not performed, then an empty result is returned.\n\nData available from 2023-02-01 onwards.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "2014-05-15T13:35:01-07:00", "2014-05-17T13:35:01-07:00" ] } ], "responses": { "200": { "description": "Returns a collection of search results. If there are no matching search results, the `entries` array will be empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResultsResponse" } } } }, "400": { "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.\n\n- `missing_parameter` - Please provide at least the `query` or `mdfilters` query parameter in a search.\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the permission to make this API call.\n\n- The developer provided a `scope` of `enterprise_content` but did not request this scope to be enabled for the user through our support channels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the user does not have access to an item mentioned in the request.\n\n- The developer provided a folder ID in `ancestor_folder_ids` that either does not exist or the user does not have access to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "search", "tags": [ "Search" ], "x-codeSamples": [ { "lang": "curl", "label": "Search for content", "source": "curl -i -X GET \"https://api.box.com/2.0/search?query=sales\" \\\n -H \"authorization: Bearer \"" }, { "lang": "java", "label": "Search for content", "source": "client.getSearch().searchForContent(new SearchForContentQueryParams.Builder().ancestorFolderIds(Arrays.asList(\"0\")).mdfilters(Arrays.asList(new MetadataFilter.Builder().scope(MetadataFilterScopeField.ENTERPRISE).templateKey(templateKey).filters(searchFilters).build())).build())" }, { "lang": "node", "label": "Search for content", "source": "await client.search.searchForContent({\n ancestorFolderIds: ['0'],\n mdfilters: [\n {\n filters: searchFilters,\n scope: 'enterprise' as MetadataFilterScopeField,\n templateKey: templateKey,\n } satisfies MetadataFilter,\n ],\n} satisfies SearchForContentQueryParams);" }, { "lang": "python", "label": "Search for content", "source": "client.search.search_for_content(\n ancestor_folder_ids=[\"0\"],\n mdfilters=[\n MetadataFilter(\n filters=search_filters,\n scope=MetadataFilterScopeField.ENTERPRISE,\n template_key=template_key,\n )\n ],\n)" } ] } }, "/tasks": { "post": { "operationId": "post_tasks", "summary": "Create task", "description": "Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "description": "The file to attach the task to.", "type": "object", "properties": { "id": { "description": "The ID of the file.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `file`.", "type": "string", "example": "file", "enum": [ "file" ] } } }, "action": { "description": "The action the task assignee will be prompted to do. Must be\n\n- `review` defines an approval task that can be approved or, rejected\n- `complete` defines a general task which can be completed.", "type": "string", "example": "review", "default": "review", "enum": [ "review", "complete" ] }, "message": { "description": "An optional message to include with the task.", "type": "string", "example": "Please review", "default": "" }, "due_at": { "description": "Defines when the task is due. Defaults to `null` if not provided.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "completion_rule": { "description": "Defines which assignees need to complete this task before the task is considered completed.\n\n- `all_assignees` (default) requires all assignees to review or approve the task in order for it to be considered completed.\n- `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed.", "type": "string", "example": "all_assignees", "default": "all_assignees", "enum": [ "all_assignees", "any_assignee" ] } }, "required": [ "item" ] } } } }, "responses": { "201": { "description": "Returns the newly created task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the permission to create a task on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "tasks", "tags": [ "Tasks" ], "x-codeSamples": [ { "lang": "curl", "label": "Create task", "source": "curl -i -X POST \"https://api.box.com/2.0/tasks\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"item\": {\n \"id\": \"11446498\",\n \"type\": \"file\"\n },\n \"action\": \"review\"\n }'" }, { "lang": "dotnet", "label": "Create task", "source": "await client.Tasks.CreateTaskAsync(requestBody: new CreateTaskRequestBody(item: new CreateTaskRequestBodyItemField() { Type = CreateTaskRequestBodyItemTypeField.File, Id = file.Id }) { Message = \"test message\", DueAt = dateTime, Action = CreateTaskRequestBodyActionField.Review, CompletionRule = CreateTaskRequestBodyCompletionRuleField.AllAssignees });" }, { "lang": "swift", "label": "Create task", "source": "try await client.tasks.createTask(requestBody: CreateTaskRequestBody(item: CreateTaskRequestBodyItemField(type: CreateTaskRequestBodyItemTypeField.file, id: file.id), message: \"test message\", dueAt: dateTime, action: CreateTaskRequestBodyActionField.review, completionRule: CreateTaskRequestBodyCompletionRuleField.allAssignees))" }, { "lang": "java", "label": "Create task", "source": "client.getTasks().createTask(new CreateTaskRequestBody.Builder(new CreateTaskRequestBodyItemField.Builder().id(file.getId()).type(CreateTaskRequestBodyItemTypeField.FILE).build()).action(CreateTaskRequestBodyActionField.REVIEW).message(\"test message\").dueAt(dateTime).completionRule(CreateTaskRequestBodyCompletionRuleField.ALL_ASSIGNEES).build())" }, { "lang": "node", "label": "Create task", "source": "await client.tasks.createTask({\n item: {\n type: 'file' as CreateTaskRequestBodyItemTypeField,\n id: file.id,\n } satisfies CreateTaskRequestBodyItemField,\n message: 'test message',\n dueAt: dateTime,\n action: 'review' as CreateTaskRequestBodyActionField,\n completionRule: 'all_assignees' as CreateTaskRequestBodyCompletionRuleField,\n} satisfies CreateTaskRequestBody);" }, { "lang": "python", "label": "Create task", "source": "client.tasks.create_task(\n CreateTaskItem(type=CreateTaskItemTypeField.FILE, id=file.id),\n action=CreateTaskAction.REVIEW,\n message=\"test message\",\n due_at=date_time,\n completion_rule=CreateTaskCompletionRule.ALL_ASSIGNEES,\n)" } ] } }, "/tasks/{task_id}": { "get": { "operationId": "get_tasks_id", "summary": "Get task", "description": "Retrieves information about a specific task.", "parameters": [ { "name": "task_id", "in": "path", "description": "The ID of the task.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "Returns a task object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "tasks", "tags": [ "Tasks" ], "x-codeSamples": [ { "lang": "curl", "label": "Get task", "source": "curl -i -X GET \"https://api.box.com/2.0/tasks/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get task", "source": "await client.Tasks.GetTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id));" }, { "lang": "swift", "label": "Get task", "source": "try await client.tasks.getTaskById(taskId: task.id!)" }, { "lang": "java", "label": "Get task", "source": "client.getTasks().getTaskById(task.getId())" }, { "lang": "node", "label": "Get task", "source": "await client.tasks.getTaskById(task.id!);" }, { "lang": "python", "label": "Get task", "source": "client.tasks.get_task_by_id(task.id)" } ] }, "put": { "operationId": "put_tasks_id", "summary": "Update task", "description": "Updates a task. This can be used to update a task's configuration, or to update its completion state.", "parameters": [ { "name": "task_id", "in": "path", "description": "The ID of the task.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "description": "The action the task assignee will be prompted to do. Must be\n\n- `review` defines an approval task that can be approved or rejected,\n- `complete` defines a general task which can be completed.", "type": "string", "example": "review", "enum": [ "review", "complete" ] }, "message": { "description": "The message included with the task.", "type": "string", "example": "Please review" }, "due_at": { "description": "When the task is due at.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "completion_rule": { "description": "Defines which assignees need to complete this task before the task is considered completed.\n\n- `all_assignees` (default) requires all assignees to review or approve the task in order for it to be considered completed.\n- `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed.", "type": "string", "example": "all_assignees", "enum": [ "all_assignees", "any_assignee" ] } } } } } }, "responses": { "200": { "description": "Returns the updated task object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error when the user does not have the permission to update a task on the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "tasks", "tags": [ "Tasks" ], "x-codeSamples": [ { "lang": "curl", "label": "Update task", "source": "curl -i -X PUT \"https://api.box.com/2.0/tasks/12345\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"action\": \"review\"\n }'" }, { "lang": "dotnet", "label": "Update task", "source": "await client.Tasks.UpdateTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id), requestBody: new UpdateTaskByIdRequestBody() { Message = \"updated message\" });" }, { "lang": "swift", "label": "Update task", "source": "try await client.tasks.updateTaskById(taskId: task.id!, requestBody: UpdateTaskByIdRequestBody(message: \"updated message\"))" }, { "lang": "java", "label": "Update task", "source": "client.getTasks().updateTaskById(task.getId(), new UpdateTaskByIdRequestBody.Builder().message(\"updated message\").build())" }, { "lang": "node", "label": "Update task", "source": "await client.tasks.updateTaskById(task.id!, {\n requestBody: {\n message: 'updated message',\n } satisfies UpdateTaskByIdRequestBody,\n} satisfies UpdateTaskByIdOptionalsInput);" }, { "lang": "python", "label": "Update task", "source": "client.tasks.update_task_by_id(task.id, message=\"updated message\")" } ] }, "delete": { "operationId": "delete_tasks_id", "summary": "Remove task", "description": "Removes a task from a file.", "parameters": [ { "name": "task_id", "in": "path", "description": "The ID of the task.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the task was successfully deleted." }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "tasks", "tags": [ "Tasks" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove task", "source": "curl -i -X DELETE \"https://api.box.com/2.0/tasks/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove task", "source": "await client.Tasks.DeleteTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id));" }, { "lang": "swift", "label": "Remove task", "source": "try await client.tasks.deleteTaskById(taskId: task.id!)" }, { "lang": "java", "label": "Remove task", "source": "client.getTasks().deleteTaskById(task.getId())" }, { "lang": "node", "label": "Remove task", "source": "await client.tasks.deleteTaskById(task.id!);" }, { "lang": "python", "label": "Remove task", "source": "client.tasks.delete_task_by_id(task.id)" } ] } }, "/tasks/{task_id}/assignments": { "get": { "operationId": "get_tasks_id_assignments", "summary": "List task assignments", "description": "Lists all of the assignments for a given task.", "parameters": [ { "name": "task_id", "in": "path", "description": "The ID of the task.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "Returns a collection of task assignment defining what task on a file has been assigned to which users and by who.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignments" } } } }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error if the task assignment ID was omitted in the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "task_assignments", "tags": [ "Task assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "List task assignments", "source": "curl -i -X GET \"https://api.box.com/2.0/tasks/12345/assignments\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List task assignments", "source": "await client.TaskAssignments.GetTaskAssignmentsAsync(taskId: NullableUtils.Unwrap(task.Id));" }, { "lang": "swift", "label": "List task assignments", "source": "try await client.taskAssignments.getTaskAssignments(taskId: task.id!)" }, { "lang": "java", "label": "List task assignments", "source": "client.getTaskAssignments().getTaskAssignments(task.getId())" }, { "lang": "node", "label": "List task assignments", "source": "await client.taskAssignments.getTaskAssignments(task.id!);" }, { "lang": "python", "label": "List task assignments", "source": "client.task_assignments.get_task_assignments(task.id)" } ] } }, "/task_assignments": { "post": { "operationId": "post_task_assignments", "summary": "Assign task", "description": "Assigns a task to a user.\n\nA task can be assigned to more than one user by creating multiple assignments.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "description": "The task to assign to a user.", "type": "object", "properties": { "id": { "description": "The ID of the task.", "type": "string", "example": "11446498" }, "type": { "description": "The type of the item to assign.", "type": "string", "example": "task", "enum": [ "task" ] } }, "required": [ "id", "type" ] }, "assign_to": { "description": "The user to assign the task to.", "type": "object", "properties": { "id": { "description": "The ID of the user to assign to the task.\n\nTo specify a user by their email address use the `login` parameter.", "type": "string", "example": "3242343" }, "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.", "type": "string", "example": "john@example.com" } } } }, "required": [ "task", "assign_to" ] } } } }, "responses": { "201": { "description": "Returns a new task assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignment" } } } }, "403": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the task cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "task_assignments", "tags": [ "Task assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Assign task", "source": "curl -i -X POST \"https://api.box.com/2.0/task_assignments\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"task\": {\n \"id\": \"11446498\",\n \"type\": \"task\"\n },\n \"assign_to\": {\n \"id\": \"4823213\"\n }\n }'" }, { "lang": "dotnet", "label": "Assign task", "source": "await client.TaskAssignments.CreateTaskAssignmentAsync(requestBody: new CreateTaskAssignmentRequestBody(task: new CreateTaskAssignmentRequestBodyTaskField(type: CreateTaskAssignmentRequestBodyTaskTypeField.Task, id: NullableUtils.Unwrap(task.Id)), assignTo: new CreateTaskAssignmentRequestBodyAssignToField() { Id = currentUser.Id }));" }, { "lang": "swift", "label": "Assign task", "source": "try await client.taskAssignments.createTaskAssignment(requestBody: CreateTaskAssignmentRequestBody(task: CreateTaskAssignmentRequestBodyTaskField(type: CreateTaskAssignmentRequestBodyTaskTypeField.task, id: task.id!), assignTo: CreateTaskAssignmentRequestBodyAssignToField(id: currentUser.id)))" }, { "lang": "java", "label": "Assign task", "source": "client.getTaskAssignments().createTaskAssignment(new CreateTaskAssignmentRequestBody(new CreateTaskAssignmentRequestBodyTaskField.Builder(task.getId()).type(CreateTaskAssignmentRequestBodyTaskTypeField.TASK).build(), new CreateTaskAssignmentRequestBodyAssignToField.Builder().id(currentUser.getId()).build()))" }, { "lang": "node", "label": "Assign task", "source": "await client.taskAssignments.createTaskAssignment({\n task: new CreateTaskAssignmentRequestBodyTaskField({\n type: 'task' as CreateTaskAssignmentRequestBodyTaskTypeField,\n id: task.id!,\n }),\n assignTo: {\n id: currentUser.id,\n } satisfies CreateTaskAssignmentRequestBodyAssignToField,\n} satisfies CreateTaskAssignmentRequestBody);" }, { "lang": "python", "label": "Assign task", "source": "client.task_assignments.create_task_assignment(\n CreateTaskAssignmentTask(type=CreateTaskAssignmentTaskTypeField.TASK, id=task.id),\n CreateTaskAssignmentAssignTo(id=current_user.id),\n)" } ] } }, "/task_assignments/{task_assignment_id}": { "get": { "operationId": "get_task_assignments_id", "summary": "Get task assignment", "description": "Retrieves information about a task assignment.", "parameters": [ { "name": "task_assignment_id", "in": "path", "description": "The ID of the task assignment.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "Returns a task assignment, specifying who the task has been assigned to and by whom.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignment" } } } }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "task_assignments", "tags": [ "Task assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get task assignment", "source": "curl -i -X GET \"https://api.box.com/2.0/task_assignments/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get task assignment", "source": "await client.TaskAssignments.GetTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id));" }, { "lang": "swift", "label": "Get task assignment", "source": "try await client.taskAssignments.getTaskAssignmentById(taskAssignmentId: taskAssignment.id!)" }, { "lang": "java", "label": "Get task assignment", "source": "client.getTaskAssignments().getTaskAssignmentById(taskAssignment.getId())" }, { "lang": "node", "label": "Get task assignment", "source": "await client.taskAssignments.getTaskAssignmentById(taskAssignment.id!);" }, { "lang": "python", "label": "Get task assignment", "source": "client.task_assignments.get_task_assignment_by_id(task_assignment.id)" } ] }, "put": { "operationId": "put_task_assignments_id", "summary": "Update task assignment", "description": "Updates a task assignment. This endpoint can be used to update the state of a task assigned to a user.", "parameters": [ { "name": "task_assignment_id", "in": "path", "description": "The ID of the task assignment.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "description": "An optional message by the assignee that can be added to the task.", "type": "string", "example": "Looks good to me" }, "resolution_state": { "description": "The state of the task assigned to the user.\n\n- For a task with an `action` value of `complete` this can be `incomplete` or `completed`.\n- For a task with an `action` of `review` this can be `incomplete`, `approved`, or `rejected`.", "type": "string", "example": "completed", "enum": [ "completed", "incomplete", "approved", "rejected" ] } } } } } }, "responses": { "200": { "description": "Returns the updated task assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskAssignment" } } } }, "400": { "description": "Returns an error if a resolution state is incompatible with the action type of the task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "task_assignments", "tags": [ "Task assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Update task assignment", "source": "curl -i -X PUT \"https://api.box.com/2.0/task_assignments/12345\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"message\": \"New message\",\n \"resolution_state\": \"completed\"\n }'" }, { "lang": "dotnet", "label": "Update task assignment", "source": "await client.TaskAssignments.UpdateTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id), requestBody: new UpdateTaskAssignmentByIdRequestBody() { Message = \"updated message\", ResolutionState = UpdateTaskAssignmentByIdRequestBodyResolutionStateField.Approved });" }, { "lang": "swift", "label": "Update task assignment", "source": "try await client.taskAssignments.updateTaskAssignmentById(taskAssignmentId: taskAssignment.id!, requestBody: UpdateTaskAssignmentByIdRequestBody(message: \"updated message\", resolutionState: UpdateTaskAssignmentByIdRequestBodyResolutionStateField.approved))" }, { "lang": "java", "label": "Update task assignment", "source": "client.getTaskAssignments().updateTaskAssignmentById(taskAssignment.getId(), new UpdateTaskAssignmentByIdRequestBody.Builder().message(\"updated message\").resolutionState(UpdateTaskAssignmentByIdRequestBodyResolutionStateField.APPROVED).build())" }, { "lang": "node", "label": "Update task assignment", "source": "await client.taskAssignments.updateTaskAssignmentById(taskAssignment.id!, {\n requestBody: {\n message: 'updated message',\n resolutionState:\n 'approved' as UpdateTaskAssignmentByIdRequestBodyResolutionStateField,\n } satisfies UpdateTaskAssignmentByIdRequestBody,\n} satisfies UpdateTaskAssignmentByIdOptionalsInput);" }, { "lang": "python", "label": "Update task assignment", "source": "client.task_assignments.update_task_assignment_by_id(\n task_assignment.id,\n message=\"updated message\",\n resolution_state=UpdateTaskAssignmentByIdResolutionState.APPROVED,\n)" } ] }, "delete": { "operationId": "delete_task_assignments_id", "summary": "Unassign task", "description": "Deletes a specific task assignment.", "parameters": [ { "name": "task_assignment_id", "in": "path", "description": "The ID of the task assignment.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the task assignment was successfully deleted." }, "404": { "description": "Returns an error if the task assignment for the given ID does not exist or is inaccessible to your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "task_assignments", "tags": [ "Task assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Unassign task", "source": "curl -i -X DELETE \"https://api.box.com/2.0/task_assignments/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Unassign task", "source": "await client.TaskAssignments.DeleteTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id));" }, { "lang": "swift", "label": "Unassign task", "source": "try await client.taskAssignments.deleteTaskAssignmentById(taskAssignmentId: taskAssignment.id!)" }, { "lang": "java", "label": "Unassign task", "source": "client.getTaskAssignments().deleteTaskAssignmentById(taskAssignment.getId())" }, { "lang": "node", "label": "Unassign task", "source": "await client.taskAssignments.deleteTaskAssignmentById(taskAssignment.id!);" }, { "lang": "python", "label": "Unassign task", "source": "client.task_assignments.delete_task_assignment_by_id(task_assignment.id)" } ] } }, "/shared_items": { "get": { "operationId": "get_shared_items", "summary": "Find file for shared link", "description": "Returns the file represented by a shared link.\n\nA shared file can be represented by a shared link, which can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a shared file when only given a shared link.\n\nThe `shared_link_permission_options` array field can be returned by requesting it in the `fields` query parameter.", "parameters": [ { "name": "if-none-match", "in": "header", "description": "Ensures an item is only returned if it has changed.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "boxapi", "in": "header", "description": "A header containing the shared link and optional password for the shared link.\n\nThe format for this header is as follows:\n\n`shared_link=[link]&shared_link_password=[password]`.", "required": true, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { "200": { "description": "Returns a full file resource if the shared link is valid and the user has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" } } } }, "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." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_files", "tags": [ "Shared links (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Find file for shared link", "source": "curl -i -X GET \"https://api.box.com/2.0/shared_items\" \\\n -H \"authorization: Bearer \" \\\n -H \"boxapi: shared_link=https://app.box.com/s/gjasdasjhasd&shared_link_password=letmein\"" }, { "lang": "dotnet", "label": "Find file for shared link", "source": "await userClient.SharedLinksFiles.FindFileForSharedLinkAsync(queryParams: new FindFileForSharedLinkQueryParams(), headers: new FindFileForSharedLinkHeaders(boxapi: string.Concat(\"shared_link=\", NullableUtils.Unwrap(fileFromApi.SharedLink).Url, \"&shared_link_password=Secret123@\")));" }, { "lang": "swift", "label": "Find file for shared link", "source": "try await userClient.sharedLinksFiles.findFileForSharedLink(queryParams: FindFileForSharedLinkQueryParams(), headers: FindFileForSharedLinkHeaders(boxapi: \"\\(\"shared_link=\")\\(fileFromApi.sharedLink!.url)\\(\"&shared_link_password=Secret123@\")\"))" }, { "lang": "java", "label": "Find file for shared link", "source": "userClient.getSharedLinksFiles().findFileForSharedLink(new FindFileForSharedLinkQueryParams(), new FindFileForSharedLinkHeaders(String.join(\"\", \"shared_link=\", fileFromApi.getSharedLink().getUrl(), \"&shared_link_password=Secret123@\")))" }, { "lang": "node", "label": "Find file for shared link", "source": "await userClient.sharedLinksFiles.findFileForSharedLink(\n {} satisfies FindFileForSharedLinkQueryParams,\n {\n boxapi: ''.concat(\n 'shared_link=',\n fileFromApi.sharedLink!.url,\n '&shared_link_password=Secret123@',\n ) as string,\n } satisfies FindFileForSharedLinkHeadersInput,\n);" }, { "lang": "python", "label": "Find file for shared link", "source": "user_client.shared_links_files.find_file_for_shared_link(\n \"\".join(\n [\n \"shared_link=\",\n file_from_api.shared_link.url,\n \"&shared_link_password=Secret123@\",\n ]\n )\n)" } ] } }, "/files/{file_id}#get_shared_link": { "get": { "operationId": "get_files_id#get_shared_link", "summary": "Get shared link for file", "description": "Gets the information for a shared link on a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "responses": { "200": { "description": "Returns the base representation of a file with the additional shared link information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_files", "tags": [ "Shared links (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shared link for file", "source": "curl -i -X GET \"https://api.box.com/2.0/files/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shared link for file", "source": "await client.SharedLinksFiles.GetSharedLinkForFileAsync(fileId: fileId, queryParams: new GetSharedLinkForFileQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Get shared link for file", "source": "try await client.sharedLinksFiles.getSharedLinkForFile(fileId: fileId, queryParams: GetSharedLinkForFileQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Get shared link for file", "source": "client.getSharedLinksFiles().getSharedLinkForFile(fileId, new GetSharedLinkForFileQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Get shared link for file", "source": "await client.sharedLinksFiles.getSharedLinkForFile(fileId, {\n fields: 'shared_link',\n} satisfies GetSharedLinkForFileQueryParams);" }, { "lang": "python", "label": "Get shared link for file", "source": "client.shared_links_files.get_shared_link_for_file(file_id, \"shared_link\")" } ] } }, "/files/{file_id}#add_shared_link": { "put": { "operationId": "put_files_id#add_shared_link", "summary": "Add shared link to file", "description": "Adds a shared link to a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "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.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link", "minLength": 12 }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true }, "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.", "type": "boolean", "example": true }, "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`.", "type": "boolean", "example": true } } } } } } } } } }, "responses": { "200": { "description": "Returns the base representation of a file with a new shared link attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_files", "tags": [ "Shared links (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Add shared link to file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": {\n \"access\": \"open\",\n \"password\": \"mypassword\",\n \"unshared_at\": \"2012-12-12T10:53:43-08:00\",\n \"permissions\": {\n \"can_download\": false\n }\n }\n }'" }, { "lang": "dotnet", "label": "Add shared link to file", "source": "await client.SharedLinksFiles.AddShareLinkToFileAsync(fileId: fileId, requestBody: new AddShareLinkToFileRequestBody() { SharedLink = new AddShareLinkToFileRequestBodySharedLinkField() { Access = AddShareLinkToFileRequestBodySharedLinkAccessField.Open, Password = \"Secret123@\" } }, queryParams: new AddShareLinkToFileQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Add shared link to file", "source": "try await client.sharedLinksFiles.addShareLinkToFile(fileId: fileId, requestBody: AddShareLinkToFileRequestBody(sharedLink: AddShareLinkToFileRequestBodySharedLinkField(access: AddShareLinkToFileRequestBodySharedLinkAccessField.open, password: \"Secret123@\")), queryParams: AddShareLinkToFileQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Add shared link to file", "source": "client.getSharedLinksFiles().addShareLinkToFile(fileId, new AddShareLinkToFileRequestBody.Builder().sharedLink(new AddShareLinkToFileRequestBodySharedLinkField.Builder().access(AddShareLinkToFileRequestBodySharedLinkAccessField.OPEN).password(\"Secret123@\").build()).build(), new AddShareLinkToFileQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Add shared link to file", "source": "await client.sharedLinksFiles.addShareLinkToFile(\n fileId,\n {\n sharedLink: {\n access: 'open' as AddShareLinkToFileRequestBodySharedLinkAccessField,\n password: 'Secret123@',\n } satisfies AddShareLinkToFileRequestBodySharedLinkField,\n } satisfies AddShareLinkToFileRequestBody,\n { fields: 'shared_link' } satisfies AddShareLinkToFileQueryParams,\n);" }, { "lang": "python", "label": "Add shared link to file", "source": "client.shared_links_files.add_share_link_to_file(\n file_id,\n \"shared_link\",\n shared_link=AddShareLinkToFileSharedLink(\n access=AddShareLinkToFileSharedLinkAccessField.OPEN, password=\"Secret123@\"\n ),\n)" } ] } }, "/files/{file_id}#update_shared_link": { "put": { "operationId": "put_files_id#update_shared_link", "summary": "Update shared link on file", "description": "Updates a shared link on a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link", "minLength": 12 }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true }, "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.", "type": "boolean", "example": true }, "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`.", "type": "boolean", "example": true } } } } } } } } } }, "responses": { "200": { "description": "Returns a basic representation of the file, with the updated shared link attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": true } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_files", "tags": [ "Shared links (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Update shared link on file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": {\n \"access\": \"open\",\n \"password\": \"mypassword\",\n \"unshared_at\": \"2012-12-12T10:53:43-08:00\",\n \"permissions\": {\n \"can_download\": false\n }\n }\n }'" }, { "lang": "dotnet", "label": "Update shared link on file", "source": "await client.SharedLinksFiles.UpdateSharedLinkOnFileAsync(fileId: fileId, requestBody: new UpdateSharedLinkOnFileRequestBody() { SharedLink = new UpdateSharedLinkOnFileRequestBodySharedLinkField() { Access = UpdateSharedLinkOnFileRequestBodySharedLinkAccessField.Collaborators } }, queryParams: new UpdateSharedLinkOnFileQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Update shared link on file", "source": "try await client.sharedLinksFiles.updateSharedLinkOnFile(fileId: fileId, requestBody: UpdateSharedLinkOnFileRequestBody(sharedLink: UpdateSharedLinkOnFileRequestBodySharedLinkField(access: UpdateSharedLinkOnFileRequestBodySharedLinkAccessField.collaborators)), queryParams: UpdateSharedLinkOnFileQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Update shared link on file", "source": "client.getSharedLinksFiles().updateSharedLinkOnFile(fileId, new UpdateSharedLinkOnFileRequestBody.Builder().sharedLink(new UpdateSharedLinkOnFileRequestBodySharedLinkField.Builder().access(UpdateSharedLinkOnFileRequestBodySharedLinkAccessField.COLLABORATORS).build()).build(), new UpdateSharedLinkOnFileQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Update shared link on file", "source": "await client.sharedLinksFiles.updateSharedLinkOnFile(\n fileId,\n {\n sharedLink: {\n access:\n 'collaborators' as UpdateSharedLinkOnFileRequestBodySharedLinkAccessField,\n } satisfies UpdateSharedLinkOnFileRequestBodySharedLinkField,\n } satisfies UpdateSharedLinkOnFileRequestBody,\n { fields: 'shared_link' } satisfies UpdateSharedLinkOnFileQueryParams,\n);" }, { "lang": "python", "label": "Update shared link on file", "source": "client.shared_links_files.update_shared_link_on_file(\n file_id,\n \"shared_link\",\n shared_link=UpdateSharedLinkOnFileSharedLink(\n access=UpdateSharedLinkOnFileSharedLinkAccessField.COLLABORATORS\n ),\n)" } ] } }, "/files/{file_id}#remove_shared_link": { "put": { "operationId": "put_files_id#remove_shared_link", "summary": "Remove shared link from file", "description": "Removes a shared link from a file.", "parameters": [ { "name": "file_id", "in": "path", "description": "The unique identifier that represents a file.\n\nThe 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`.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link is removed from the file.", "type": "object", "example": null, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a basic representation of a file, with the shared link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": null } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_files", "tags": [ "Shared links (Files)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove shared link from file", "source": "curl -i -X PUT \"https://api.box.com/2.0/files/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": null\n }'" }, { "lang": "dotnet", "label": "Remove shared link from file", "source": "await client.SharedLinksFiles.RemoveSharedLinkFromFileAsync(fileId: fileId, requestBody: new RemoveSharedLinkFromFileRequestBody() { SharedLink = null }, queryParams: new RemoveSharedLinkFromFileQueryParams(fields: \"shared_link\"));" }, { "lang": "java", "label": "Remove shared link from file", "source": "client.getSharedLinksFiles().removeSharedLinkFromFile(fileId, new RemoveSharedLinkFromFileRequestBody.Builder().sharedLink(null).build(), new RemoveSharedLinkFromFileQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Remove shared link from file", "source": "await client.sharedLinksFiles.removeSharedLinkFromFile(\n fileId,\n { sharedLink: createNull() } satisfies RemoveSharedLinkFromFileRequestBody,\n { fields: 'shared_link' } satisfies RemoveSharedLinkFromFileQueryParams,\n);" }, { "lang": "python", "label": "Remove shared link from file", "source": "client.shared_links_files.remove_shared_link_from_file(\n file_id, \"shared_link\", shared_link=create_null()\n)" } ] } }, "/shared_items#folders": { "get": { "operationId": "get_shared_items#folders", "summary": "Find folder for shared link", "description": "Return the folder represented by a shared link.\n\nA shared folder can be represented by a shared link, which can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a shared folder when only given a shared link.", "parameters": [ { "name": "if-none-match", "in": "header", "description": "Ensures an item is only returned if it has changed.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "boxapi", "in": "header", "description": "A header containing the shared link and optional password for the shared link.\n\nThe format for this header is as follows:\n\n`shared_link=[link]&shared_link_password=[password]`.", "required": true, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { "200": { "description": "Returns a full folder resource if the shared link is valid and the user has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "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": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_folders", "tags": [ "Shared links (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Find folder for shared link", "source": "curl -i -X GET \"https://api.box.com/2.0/shared_items\" \\\n -H \"authorization: Bearer \" \\\n -H \"boxapi: shared_link=https://app.box.com/s/jsasdsd8sad24&shared_link_password=letmein\"" }, { "lang": "dotnet", "label": "Find folder for shared link", "source": "await userClient.SharedLinksFolders.FindFolderForSharedLinkAsync(queryParams: new FindFolderForSharedLinkQueryParams(), headers: new FindFolderForSharedLinkHeaders(boxapi: string.Concat(\"shared_link=\", NullableUtils.Unwrap(folderFromApi.SharedLink).Url, \"&shared_link_password=Secret123@\")));" }, { "lang": "swift", "label": "Find folder for shared link", "source": "try await userClient.sharedLinksFolders.findFolderForSharedLink(queryParams: FindFolderForSharedLinkQueryParams(), headers: FindFolderForSharedLinkHeaders(boxapi: \"\\(\"shared_link=\")\\(folderFromApi.sharedLink!.url)\\(\"&shared_link_password=Secret123@\")\"))" }, { "lang": "java", "label": "Find folder for shared link", "source": "userClient.getSharedLinksFolders().findFolderForSharedLink(new FindFolderForSharedLinkQueryParams(), new FindFolderForSharedLinkHeaders(String.join(\"\", \"shared_link=\", folderFromApi.getSharedLink().getUrl(), \"&shared_link_password=Secret123@\")))" }, { "lang": "node", "label": "Find folder for shared link", "source": "await userClient.sharedLinksFolders.findFolderForSharedLink(\n {} satisfies FindFolderForSharedLinkQueryParams,\n {\n boxapi: ''.concat(\n 'shared_link=',\n folderFromApi.sharedLink!.url,\n '&shared_link_password=Secret123@',\n ) as string,\n } satisfies FindFolderForSharedLinkHeadersInput,\n);" }, { "lang": "python", "label": "Find folder for shared link", "source": "user_client.shared_links_folders.find_folder_for_shared_link(\n \"\".join(\n [\n \"shared_link=\",\n folder_from_api.shared_link.url,\n \"&shared_link_password=Secret123@\",\n ]\n )\n)" } ] } }, "/folders/{folder_id}#get_shared_link": { "get": { "operationId": "get_folders_id#get_shared_link", "summary": "Get shared link for folder", "description": "Gets the information for a shared link on a folder.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "responses": { "200": { "description": "Returns the base representation of a folder with the additional shared link information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_folders", "tags": [ "Shared links (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shared link for folder", "source": "curl -i -X GET \"https://api.box.com/2.0/folders/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shared link for folder", "source": "await client.SharedLinksFolders.GetSharedLinkForFolderAsync(folderId: folder.Id, queryParams: new GetSharedLinkForFolderQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Get shared link for folder", "source": "try await client.sharedLinksFolders.getSharedLinkForFolder(folderId: folder.id, queryParams: GetSharedLinkForFolderQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Get shared link for folder", "source": "client.getSharedLinksFolders().getSharedLinkForFolder(folder.getId(), new GetSharedLinkForFolderQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Get shared link for folder", "source": "await client.sharedLinksFolders.getSharedLinkForFolder(folder.id, {\n fields: 'shared_link',\n} satisfies GetSharedLinkForFolderQueryParams);" }, { "lang": "python", "label": "Get shared link for folder", "source": "client.shared_links_folders.get_shared_link_for_folder(folder.id, \"shared_link\")" } ] } }, "/folders/{folder_id}#add_shared_link": { "put": { "operationId": "put_folders_id#add_shared_link", "summary": "Add shared link to folder", "description": "Adds a shared link to a folder.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to create on the folder.\n\nUse an empty object (`{}`) to use the default settings for shared links.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link", "minLength": 12 }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true }, "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.", "type": "boolean", "example": true }, "can_edit": { "description": "This value can only be `false` for items with a `type` of `folder`.", "type": "boolean", "example": false } } } } } } } } } }, "responses": { "200": { "description": "Returns the base representation of a folder with a new shared link attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_folders", "tags": [ "Shared links (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Add shared link to folder", "source": "curl -i -X PUT \"https://api.box.com/2.0/folders/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": {\n \"access\": \"open\",\n \"password\": \"mypassword\",\n \"unshared_at\": \"2012-12-12T10:53:43-08:00\",\n \"permissions\": {\n \"can_download\": false\n }\n }\n }'" }, { "lang": "dotnet", "label": "Add shared link to folder", "source": "await client.SharedLinksFolders.AddShareLinkToFolderAsync(folderId: folder.Id, requestBody: new AddShareLinkToFolderRequestBody() { SharedLink = new AddShareLinkToFolderRequestBodySharedLinkField() { Access = AddShareLinkToFolderRequestBodySharedLinkAccessField.Open, Password = \"Secret123@\" } }, queryParams: new AddShareLinkToFolderQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Add shared link to folder", "source": "try await client.sharedLinksFolders.addShareLinkToFolder(folderId: folder.id, requestBody: AddShareLinkToFolderRequestBody(sharedLink: AddShareLinkToFolderRequestBodySharedLinkField(access: AddShareLinkToFolderRequestBodySharedLinkAccessField.open, password: \"Secret123@\")), queryParams: AddShareLinkToFolderQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Add shared link to folder", "source": "client.getSharedLinksFolders().addShareLinkToFolder(folder.getId(), new AddShareLinkToFolderRequestBody.Builder().sharedLink(new AddShareLinkToFolderRequestBodySharedLinkField.Builder().access(AddShareLinkToFolderRequestBodySharedLinkAccessField.OPEN).password(\"Secret123@\").build()).build(), new AddShareLinkToFolderQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Add shared link to folder", "source": "await client.sharedLinksFolders.addShareLinkToFolder(\n folder.id,\n {\n sharedLink: {\n access: 'open' as AddShareLinkToFolderRequestBodySharedLinkAccessField,\n password: 'Secret123@',\n } satisfies AddShareLinkToFolderRequestBodySharedLinkField,\n } satisfies AddShareLinkToFolderRequestBody,\n { fields: 'shared_link' } satisfies AddShareLinkToFolderQueryParams,\n);" }, { "lang": "python", "label": "Add shared link to folder", "source": "client.shared_links_folders.add_share_link_to_folder(\n folder.id,\n \"shared_link\",\n shared_link=AddShareLinkToFolderSharedLink(\n access=AddShareLinkToFolderSharedLinkAccessField.OPEN, password=\"Secret123@\"\n ),\n)" } ] } }, "/folders/{folder_id}#update_shared_link": { "put": { "operationId": "put_folders_id#update_shared_link", "summary": "Update shared link on folder", "description": "Updates a shared link on a folder.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password" }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link", "minLength": 12 }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true }, "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.", "type": "boolean", "example": true }, "can_edit": { "description": "This value can only be `false` for items with a `type` of `folder`.", "type": "boolean", "example": false } } } } } } } } } }, "responses": { "200": { "description": "Returns a basic representation of the folder, with the updated shared link attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_folders", "tags": [ "Shared links (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Update shared link on folder", "source": "curl -i -X PUT \"https://api.box.com/2.0/folders/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": {\n \"access\": \"open\",\n \"password\": \"mypassword\",\n \"unshared_at\": \"2012-12-12T10:53:43-08:00\",\n \"permissions\": {\n \"can_download\": false\n }\n }\n }'" }, { "lang": "dotnet", "label": "Update shared link on folder", "source": "await client.SharedLinksFolders.UpdateSharedLinkOnFolderAsync(folderId: folder.Id, requestBody: new UpdateSharedLinkOnFolderRequestBody() { SharedLink = new UpdateSharedLinkOnFolderRequestBodySharedLinkField() { Access = UpdateSharedLinkOnFolderRequestBodySharedLinkAccessField.Collaborators } }, queryParams: new UpdateSharedLinkOnFolderQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Update shared link on folder", "source": "try await client.sharedLinksFolders.updateSharedLinkOnFolder(folderId: folder.id, requestBody: UpdateSharedLinkOnFolderRequestBody(sharedLink: UpdateSharedLinkOnFolderRequestBodySharedLinkField(access: UpdateSharedLinkOnFolderRequestBodySharedLinkAccessField.collaborators)), queryParams: UpdateSharedLinkOnFolderQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Update shared link on folder", "source": "client.getSharedLinksFolders().updateSharedLinkOnFolder(folder.getId(), new UpdateSharedLinkOnFolderRequestBody.Builder().sharedLink(new UpdateSharedLinkOnFolderRequestBodySharedLinkField.Builder().access(UpdateSharedLinkOnFolderRequestBodySharedLinkAccessField.COLLABORATORS).build()).build(), new UpdateSharedLinkOnFolderQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Update shared link on folder", "source": "await client.sharedLinksFolders.updateSharedLinkOnFolder(\n folder.id,\n {\n sharedLink: {\n access:\n 'collaborators' as UpdateSharedLinkOnFolderRequestBodySharedLinkAccessField,\n } satisfies UpdateSharedLinkOnFolderRequestBodySharedLinkField,\n } satisfies UpdateSharedLinkOnFolderRequestBody,\n { fields: 'shared_link' } satisfies UpdateSharedLinkOnFolderQueryParams,\n);" }, { "lang": "python", "label": "Update shared link on folder", "source": "client.shared_links_folders.update_shared_link_on_folder(\n folder.id,\n \"shared_link\",\n shared_link=UpdateSharedLinkOnFolderSharedLink(\n access=UpdateSharedLinkOnFolderSharedLinkAccessField.COLLABORATORS\n ),\n)" } ] } }, "/folders/{folder_id}#remove_shared_link": { "put": { "operationId": "put_folders_id#remove_shared_link", "summary": "Remove shared link from folder", "description": "Removes a shared link from a folder.", "parameters": [ { "name": "folder_id", "in": "path", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link is removed from the folder.", "type": "object", "example": null, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a basic representation of a folder, with the shared link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": null } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_folders", "tags": [ "Shared links (Folders)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove shared link from folder", "source": "curl -i -X PUT \"https://api.box.com/2.0/folders/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": null\n }'" }, { "lang": "dotnet", "label": "Remove shared link from folder", "source": "await client.SharedLinksFolders.RemoveSharedLinkFromFolderAsync(folderId: folder.Id, requestBody: new RemoveSharedLinkFromFolderRequestBody() { SharedLink = null }, queryParams: new RemoveSharedLinkFromFolderQueryParams(fields: \"shared_link\"));" }, { "lang": "java", "label": "Remove shared link from folder", "source": "client.getSharedLinksFolders().removeSharedLinkFromFolder(folder.getId(), new RemoveSharedLinkFromFolderRequestBody.Builder().sharedLink(null).build(), new RemoveSharedLinkFromFolderQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Remove shared link from folder", "source": "await client.sharedLinksFolders.removeSharedLinkFromFolder(\n folder.id,\n { sharedLink: createNull() } satisfies RemoveSharedLinkFromFolderRequestBody,\n { fields: 'shared_link' } satisfies RemoveSharedLinkFromFolderQueryParams,\n);" }, { "lang": "python", "label": "Remove shared link from folder", "source": "client.shared_links_folders.remove_shared_link_from_folder(\n folder.id, \"shared_link\", shared_link=create_null()\n)" } ] } }, "/web_links": { "post": { "operationId": "post_web_links", "summary": "Create web link", "description": "Creates a web link object within a folder.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "The URL that this web link links to. Must start with `\"http://\"` or `\"https://\"`.", "type": "string", "example": "https://box.com" }, "parent": { "description": "The parent folder to create the web link within.", "type": "object", "properties": { "id": { "description": "The ID of parent folder.", "type": "string", "example": "0" } }, "required": [ "id" ] }, "name": { "description": "Name of the web link. Defaults to the URL if not set.", "type": "string", "example": "Box Website" }, "description": { "description": "Description of the web link.", "type": "string", "example": "Cloud Content Management" } }, "required": [ "parent", "url" ] } } } }, "responses": { "200": { "description": "Returns the newly created web link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "web_links", "tags": [ "Web links" ], "x-codeSamples": [ { "lang": "curl", "label": "Create web link", "source": "curl -i -X POST \"https://api.box.com/2.0/web_links\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"Cloud Content Management\",\n \"url\": \"https://box.com\",\n \"parent\": {\n \"id\": \"0\"\n }\n }'" }, { "lang": "dotnet", "label": "Create web link", "source": "await client.WebLinks.CreateWebLinkAsync(requestBody: new CreateWebLinkRequestBody(url: \"https://www.box.com\", parent: new CreateWebLinkRequestBodyParentField(id: parent.Id)) { Name = Utils.GetUUID(), Description = \"Weblink description\" });" }, { "lang": "swift", "label": "Create web link", "source": "try await client.webLinks.createWebLink(requestBody: CreateWebLinkRequestBody(url: \"https://www.box.com\", parent: CreateWebLinkRequestBodyParentField(id: parent.id), name: Utils.getUUID(), description: \"Weblink description\"))" }, { "lang": "java", "label": "Create web link", "source": "client.getWebLinks().createWebLink(new CreateWebLinkRequestBody.Builder(url, new CreateWebLinkRequestBodyParentField(parent.getId())).name(name).description(description).build())" }, { "lang": "node", "label": "Create web link", "source": "await client.webLinks.createWebLink({\n url: 'https://www.box.com',\n parent: { id: parent.id } satisfies CreateWebLinkRequestBodyParentField,\n name: getUuid(),\n description: 'Weblink description',\n} satisfies CreateWebLinkRequestBody);" }, { "lang": "python", "label": "Create web link", "source": "client.web_links.create_web_link(\n \"https://www.box.com\",\n CreateWebLinkParent(id=parent.id),\n name=get_uuid(),\n description=\"Weblink description\",\n)" } ] } }, "/web_links/{web_link_id}": { "get": { "operationId": "get_web_links_id", "summary": "Get web link", "description": "Retrieve information about a web link.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "boxapi", "in": "header", "description": "The URL, and optional password, for the shared link of this item.\n\nThis header can be used to access items that have not been explicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then use `shared_link=[link]&shared_link_password=[password]`.\n\nThis header can be used on the file or folder shared, as well as on any files or folders nested within the item.", "required": false, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { "200": { "description": "Returns the web link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "web_links", "tags": [ "Web links" ], "x-codeSamples": [ { "lang": "curl", "label": "Get web link", "source": "curl -i -X GET \"https://api.box.com/2.0/web_links/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get web link", "source": "await client.WebLinks.GetWebLinkByIdAsync(webLinkId: weblink.Id);" }, { "lang": "swift", "label": "Get web link", "source": "try await client.webLinks.getWebLinkById(webLinkId: weblink.id)" }, { "lang": "java", "label": "Get web link", "source": "client.getWebLinks().getWebLinkById(weblink.getId())" }, { "lang": "node", "label": "Get web link", "source": "await client.webLinks.getWebLinkById(weblink.id);" }, { "lang": "python", "label": "Get web link", "source": "client.web_links.get_web_link_by_id(weblink.id)" } ] }, "post": { "operationId": "post_web_links_id", "summary": "Restore web link", "description": "Restores a web link that has been moved to the trash.\n\nAn optional new parent ID can be provided to restore the web link to in case the original folder has been deleted.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the web link.", "type": "string", "example": "Restored.docx" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item.", "properties": { "id": { "description": "The ID of parent item.", "type": "string", "example": "123" } } }, { "description": "Specifies an optional ID of a folder to restore the web link to when the original folder no longer exists.\n\nPlease 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." } ] } } } } } }, "responses": { "201": { "description": "Returns a web link object when it has been restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashWebLinkRestored" } } } }, "403": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the web link is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there is an web link with the same name in the folder the web link is being restored to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_web_links", "tags": [ "Trashed web links" ], "x-codeSamples": [ { "lang": "curl", "label": "Restore web link", "source": "curl -i -X POST \"https://api.box.com/2.0/web_links/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Restore web link", "source": "await client.TrashedWebLinks.RestoreWeblinkFromTrashAsync(webLinkId: weblink.Id);" }, { "lang": "swift", "label": "Restore web link", "source": "try await client.trashedWebLinks.restoreWeblinkFromTrash(webLinkId: weblink.id)" }, { "lang": "java", "label": "Restore web link", "source": "client.getTrashedWebLinks().restoreWeblinkFromTrash(weblink.getId())" }, { "lang": "node", "label": "Restore web link", "source": "await client.trashedWebLinks.restoreWeblinkFromTrash(weblink.id);" }, { "lang": "python", "label": "Restore web link", "source": "client.trashed_web_links.restore_weblink_from_trash(weblink.id)" } ] }, "put": { "operationId": "put_web_links_id", "summary": "Update web link", "description": "Updates a web link object.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "The new URL that the web link links to. Must start with `\"http://\"` or `\"https://\"`.", "type": "string", "example": "https://box.com" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item.", "properties": { "id": { "description": "The ID of parent item.", "type": "string", "example": "123" }, "user_id": { "description": "The input for `user_id` is optional. Moving to non-root folder is not allowed when `user_id` is present. Parent folder id should be zero when `user_id` is provided.", "type": "string", "example": "12346930" } } }, { "description": "The new parent folder to put the web link in. Use this to move the web link to a different folder." } ] }, "name": { "description": "A new name for the web link. Defaults to the URL if not set.", "type": "string", "example": "Box Website" }, "description": { "description": "A new description of the web link.", "type": "string", "example": "Cloud Content Management" }, "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-not-use-this-password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link", "minLength": 12 }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } } } } } } } }, "responses": { "200": { "description": "Returns the updated web link object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "web_links", "tags": [ "Web links" ], "x-codeSamples": [ { "lang": "curl", "label": "Update web link", "source": "curl -i -X PUT \"https://api.box.com/2.0/web_links/12345\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"Cloud Content Management\"\n }'" }, { "lang": "dotnet", "label": "Update web link", "source": "await client.WebLinks.UpdateWebLinkByIdAsync(webLinkId: weblink.Id, requestBody: new UpdateWebLinkByIdRequestBody() { Name = updatedName, SharedLink = new UpdateWebLinkByIdRequestBodySharedLinkField() { Access = UpdateWebLinkByIdRequestBodySharedLinkAccessField.Open, Password = password } });" }, { "lang": "swift", "label": "Update web link", "source": "try await client.webLinks.updateWebLinkById(webLinkId: weblink.id, requestBody: UpdateWebLinkByIdRequestBody(name: updatedName, sharedLink: UpdateWebLinkByIdRequestBodySharedLinkField(access: UpdateWebLinkByIdRequestBodySharedLinkAccessField.open, password: password)))" }, { "lang": "java", "label": "Update web link", "source": "client.getWebLinks().updateWebLinkById(weblink.getId(), new UpdateWebLinkByIdRequestBody.Builder().name(updatedName).sharedLink(new UpdateWebLinkByIdRequestBodySharedLinkField.Builder().access(UpdateWebLinkByIdRequestBodySharedLinkAccessField.OPEN).password(password).build()).build())" }, { "lang": "node", "label": "Update web link", "source": "await client.webLinks.updateWebLinkById(weblink.id, {\n requestBody: {\n name: updatedName,\n sharedLink: {\n access: 'open' as UpdateWebLinkByIdRequestBodySharedLinkAccessField,\n password: password,\n } satisfies UpdateWebLinkByIdRequestBodySharedLinkField,\n } satisfies UpdateWebLinkByIdRequestBody,\n} satisfies UpdateWebLinkByIdOptionalsInput);" }, { "lang": "python", "label": "Update web link", "source": "client.web_links.update_web_link_by_id(\n weblink.id,\n name=updated_name,\n shared_link=UpdateWebLinkByIdSharedLink(\n access=UpdateWebLinkByIdSharedLinkAccessField.OPEN, password=password\n ),\n)" } ] }, "delete": { "operationId": "delete_web_links_id", "summary": "Remove web link", "description": "Deletes a web link.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "An empty response will be returned when the web link was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "web_links", "tags": [ "Web links" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove web link", "source": "curl -i -X DELETE \"https://api.box.com/2.0/web_links/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove web link", "source": "await client.WebLinks.DeleteWebLinkByIdAsync(webLinkId: webLinkId);" }, { "lang": "swift", "label": "Remove web link", "source": "try await client.webLinks.deleteWebLinkById(webLinkId: webLinkId)" }, { "lang": "java", "label": "Remove web link", "source": "client.getWebLinks().deleteWebLinkById(weblink.getId())" }, { "lang": "node", "label": "Remove web link", "source": "await client.webLinks.deleteWebLinkById(webLinkId);" }, { "lang": "python", "label": "Remove web link", "source": "client.web_links.delete_web_link_by_id(web_link_id)" } ] } }, "/web_links/{web_link_id}/trash": { "get": { "operationId": "get_web_links_id_trash", "summary": "Get trashed web link", "description": "Retrieves a web link that has been moved to the trash.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the web link that was trashed, including information about when the it was moved to the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashWebLink" } } } }, "404": { "description": "Returns an error if the web link is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_web_links", "tags": [ "Trashed web links" ], "x-codeSamples": [ { "lang": "curl", "label": "Get trashed web link", "source": "curl -i -X GET \"https://api.box.com/2.0/web_links/12345/trash\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get trashed web link", "source": "await client.TrashedWebLinks.GetTrashedWebLinkByIdAsync(webLinkId: weblink.Id);" }, { "lang": "swift", "label": "Get trashed web link", "source": "try await client.trashedWebLinks.getTrashedWebLinkById(webLinkId: weblink.id)" }, { "lang": "java", "label": "Get trashed web link", "source": "client.getTrashedWebLinks().getTrashedWebLinkById(weblink.getId())" }, { "lang": "node", "label": "Get trashed web link", "source": "await client.trashedWebLinks.getTrashedWebLinkById(weblink.id);" }, { "lang": "python", "label": "Get trashed web link", "source": "client.trashed_web_links.get_trashed_web_link_by_id(weblink.id)" } ] }, "delete": { "operationId": "delete_web_links_id_trash", "summary": "Permanently remove web link", "description": "Permanently deletes a web link that is in the trash. This action cannot be undone.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "Returns an empty response when the web link was permanently deleted." }, "404": { "description": "Returns an error if the web link is not in the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "trashed_web_links", "tags": [ "Trashed web links" ], "x-codeSamples": [ { "lang": "curl", "label": "Permanently remove web link", "source": "curl -i -X DELETE \"https://api.box.com/2.0/web_links/12345/trash\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Permanently remove web link", "source": "await client.TrashedWebLinks.DeleteTrashedWebLinkByIdAsync(webLinkId: weblink.Id);" }, { "lang": "swift", "label": "Permanently remove web link", "source": "try await client.trashedWebLinks.deleteTrashedWebLinkById(webLinkId: weblink.id)" }, { "lang": "java", "label": "Permanently remove web link", "source": "client.getTrashedWebLinks().deleteTrashedWebLinkById(weblink.getId())" }, { "lang": "node", "label": "Permanently remove web link", "source": "await client.trashedWebLinks.deleteTrashedWebLinkById(weblink.id);" }, { "lang": "python", "label": "Permanently remove web link", "source": "client.trashed_web_links.delete_trashed_web_link_by_id(weblink.id)" } ] } }, "/shared_items#web_links": { "get": { "operationId": "get_shared_items#web_links", "summary": "Find web link for shared link", "description": "Returns the web link represented by a shared link.\n\nA shared web link can be represented by a shared link, which can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a shared web link when only given a shared link.", "parameters": [ { "name": "if-none-match", "in": "header", "description": "Ensures an item is only returned if it has changed.\n\nPass 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.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "boxapi", "in": "header", "description": "A header containing the shared link and optional password for the shared link.\n\nThe format for this header is as follows:\n\n`shared_link=[link]&shared_link_password=[password]`.", "required": true, "schema": { "type": "string" }, "example": "shared_link=[link]&shared_link_password=[password]" } ], "responses": { "200": { "description": "Returns a full web link resource if the shared link is valid and the user has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" } } } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches the current `etag` value of the web link. This indicates that the web link has not changed since it was last requested." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_web_links", "tags": [ "Shared links (Web Links)" ], "x-codeSamples": [ { "lang": "dotnet", "label": "Find web link for shared link", "source": "await userClient.SharedLinksWebLinks.FindWebLinkForSharedLinkAsync(queryParams: new FindWebLinkForSharedLinkQueryParams(), headers: new FindWebLinkForSharedLinkHeaders(boxapi: string.Concat(\"shared_link=\", NullableUtils.Unwrap(webLinkFromApi.SharedLink).Url, \"&shared_link_password=Secret123@\")));" }, { "lang": "swift", "label": "Find web link for shared link", "source": "try await userClient.sharedLinksWebLinks.findWebLinkForSharedLink(queryParams: FindWebLinkForSharedLinkQueryParams(), headers: FindWebLinkForSharedLinkHeaders(boxapi: \"\\(\"shared_link=\")\\(webLinkFromApi.sharedLink!.url)\\(\"&shared_link_password=Secret123@\")\"))" }, { "lang": "java", "label": "Find web link for shared link", "source": "userClient.getSharedLinksWebLinks().findWebLinkForSharedLink(new FindWebLinkForSharedLinkQueryParams(), new FindWebLinkForSharedLinkHeaders(String.join(\"\", \"shared_link=\", webLinkFromApi.getSharedLink().getUrl(), \"&shared_link_password=Secret123@\")))" }, { "lang": "node", "label": "Find web link for shared link", "source": "await userClient.sharedLinksWebLinks.findWebLinkForSharedLink(\n {} satisfies FindWebLinkForSharedLinkQueryParams,\n {\n boxapi: ''.concat(\n 'shared_link=',\n webLinkFromApi.sharedLink!.url,\n '&shared_link_password=Secret123@',\n ) as string,\n } satisfies FindWebLinkForSharedLinkHeadersInput,\n);" }, { "lang": "python", "label": "Find web link for shared link", "source": "user_client.shared_links_web_links.find_web_link_for_shared_link(\n \"\".join(\n [\n \"shared_link=\",\n web_link_from_api.shared_link.url,\n \"&shared_link_password=Secret123@\",\n ]\n )\n)" } ] } }, "/web_links/{web_link_id}#get_shared_link": { "get": { "operationId": "get_web_links_id#get_shared_link", "summary": "Get shared link for web link", "description": "Gets the information for a shared link on a web link.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "responses": { "200": { "description": "Returns the base representation of a web link with the additional shared link information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_web_links", "tags": [ "Shared links (Web Links)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shared link for web link", "source": "curl -i -X GET \"https://api.box.com/2.0/web_links/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shared link for web link", "source": "await client.SharedLinksWebLinks.GetSharedLinkForWebLinkAsync(webLinkId: webLinkId, queryParams: new GetSharedLinkForWebLinkQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Get shared link for web link", "source": "try await client.sharedLinksWebLinks.getSharedLinkForWebLink(webLinkId: webLinkId, queryParams: GetSharedLinkForWebLinkQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Get shared link for web link", "source": "client.getSharedLinksWebLinks().getSharedLinkForWebLink(webLinkId, new GetSharedLinkForWebLinkQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Get shared link for web link", "source": "await client.sharedLinksWebLinks.getSharedLinkForWebLink(webLinkId, {\n fields: 'shared_link',\n} satisfies GetSharedLinkForWebLinkQueryParams);" }, { "lang": "python", "label": "Get shared link for web link", "source": "client.shared_links_web_links.get_shared_link_for_web_link(web_link_id, \"shared_link\")" } ] } }, "/web_links/{web_link_id}#add_shared_link": { "put": { "operationId": "put_web_links_id#add_shared_link", "summary": "Add shared link to web link", "description": "Adds a shared link to a web link.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to create on the web link.\n\nUse an empty object (`{}`) to use the default settings for shared links.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link", "minLength": 12 }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true }, "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.", "type": "boolean", "example": true }, "can_edit": { "description": "This value can only be `true` is `type` is `file`.", "type": "boolean", "example": false } } } } } } } } } }, "responses": { "200": { "description": "Returns the base representation of a web link with a new shared link attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_web_links", "tags": [ "Shared links (Web Links)" ], "x-codeSamples": [ { "lang": "curl", "label": "Add shared link to web link", "source": "curl -i -X PUT \"https://api.box.com/2.0/web_links/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": {\n \"access\": \"open\",\n \"password\": \"mypassword\",\n \"unshared_at\": \"2012-12-12T10:53:43-08:00\",\n \"permissions\": {\n \"can_download\": false\n }\n }\n }'" }, { "lang": "dotnet", "label": "Add shared link to web link", "source": "await client.SharedLinksWebLinks.AddShareLinkToWebLinkAsync(webLinkId: webLinkId, requestBody: new AddShareLinkToWebLinkRequestBody() { SharedLink = new AddShareLinkToWebLinkRequestBodySharedLinkField() { Access = AddShareLinkToWebLinkRequestBodySharedLinkAccessField.Open, Password = \"Secret123@\" } }, queryParams: new AddShareLinkToWebLinkQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Add shared link to web link", "source": "try await client.sharedLinksWebLinks.addShareLinkToWebLink(webLinkId: webLinkId, requestBody: AddShareLinkToWebLinkRequestBody(sharedLink: AddShareLinkToWebLinkRequestBodySharedLinkField(access: AddShareLinkToWebLinkRequestBodySharedLinkAccessField.open, password: \"Secret123@\")), queryParams: AddShareLinkToWebLinkQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Add shared link to web link", "source": "client.getSharedLinksWebLinks().addShareLinkToWebLink(webLinkId, new AddShareLinkToWebLinkRequestBody.Builder().sharedLink(new AddShareLinkToWebLinkRequestBodySharedLinkField.Builder().access(AddShareLinkToWebLinkRequestBodySharedLinkAccessField.OPEN).password(\"Secret123@\").build()).build(), new AddShareLinkToWebLinkQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Add shared link to web link", "source": "await client.sharedLinksWebLinks.addShareLinkToWebLink(\n webLinkId,\n {\n sharedLink: {\n access: 'open' as AddShareLinkToWebLinkRequestBodySharedLinkAccessField,\n password: 'Secret123@',\n } satisfies AddShareLinkToWebLinkRequestBodySharedLinkField,\n } satisfies AddShareLinkToWebLinkRequestBody,\n { fields: 'shared_link' } satisfies AddShareLinkToWebLinkQueryParams,\n);" }, { "lang": "python", "label": "Add shared link to web link", "source": "client.shared_links_web_links.add_share_link_to_web_link(\n web_link_id,\n \"shared_link\",\n shared_link=AddShareLinkToWebLinkSharedLink(\n access=AddShareLinkToWebLinkSharedLinkAccessField.OPEN, password=\"Secret123@\"\n ),\n)" } ] } }, "/web_links/{web_link_id}#update_shared_link": { "put": { "operationId": "put_web_links_id#update_shared_link", "summary": "Update shared link on web link", "description": "Updates a shared link on a web link.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "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`).\n\nIf 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\": {} }`.\n\nThe `company` access level is only available to paid accounts.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "password": { "description": "The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`.", "type": "string", "example": "do-n8t-use-this-Password", "nullable": true }, "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`.\n\nCustom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links.", "type": "string", "example": "my-shared-link", "minLength": 12 }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "permissions": { "type": "object", "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`.", "type": "boolean", "example": true }, "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.", "type": "boolean", "example": true }, "can_edit": { "description": "This value can only be `true` is `type` is `file`.", "type": "boolean", "example": true } } } } } } } } } }, "responses": { "200": { "description": "Returns a basic representation of the web link, with the updated shared link attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": { "url": "https://app.box.com/s/kwio6b4ovt1264rnfbyqo1", "download_url": "https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf", "vanity_url": null, "vanity_name": null, "effective_access": "open", "effective_permission": "can_download", "is_password_enabled": false, "unshared_at": "2020-09-21T10:34:41-07:00", "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_preview": true, "can_download": true, "can_edit": false } } } } } } } }, "400": { "description": "Returned when there is an incorrect permission combination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_web_links", "tags": [ "Shared links (Web Links)" ], "x-codeSamples": [ { "lang": "curl", "label": "Update shared link on web link", "source": "curl -i -X PUT \"https://api.box.com/2.0/web_links/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": {\n \"access\": \"open\",\n \"password\": \"mypassword\",\n \"unshared_at\": \"2012-12-12T10:53:43-08:00\",\n \"permissions\": {\n \"can_download\": false\n }\n }\n }'" }, { "lang": "dotnet", "label": "Update shared link on web link", "source": "await client.SharedLinksWebLinks.UpdateSharedLinkOnWebLinkAsync(webLinkId: webLinkId, requestBody: new UpdateSharedLinkOnWebLinkRequestBody() { SharedLink = new UpdateSharedLinkOnWebLinkRequestBodySharedLinkField() { Access = UpdateSharedLinkOnWebLinkRequestBodySharedLinkAccessField.Collaborators } }, queryParams: new UpdateSharedLinkOnWebLinkQueryParams(fields: \"shared_link\"));" }, { "lang": "swift", "label": "Update shared link on web link", "source": "try await client.sharedLinksWebLinks.updateSharedLinkOnWebLink(webLinkId: webLinkId, requestBody: UpdateSharedLinkOnWebLinkRequestBody(sharedLink: UpdateSharedLinkOnWebLinkRequestBodySharedLinkField(access: UpdateSharedLinkOnWebLinkRequestBodySharedLinkAccessField.collaborators)), queryParams: UpdateSharedLinkOnWebLinkQueryParams(fields: \"shared_link\"))" }, { "lang": "java", "label": "Update shared link on web link", "source": "client.getSharedLinksWebLinks().updateSharedLinkOnWebLink(webLinkId, new UpdateSharedLinkOnWebLinkRequestBody.Builder().sharedLink(new UpdateSharedLinkOnWebLinkRequestBodySharedLinkField.Builder().access(UpdateSharedLinkOnWebLinkRequestBodySharedLinkAccessField.COLLABORATORS).build()).build(), new UpdateSharedLinkOnWebLinkQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Update shared link on web link", "source": "await client.sharedLinksWebLinks.updateSharedLinkOnWebLink(\n webLinkId,\n {\n sharedLink: {\n access:\n 'collaborators' as UpdateSharedLinkOnWebLinkRequestBodySharedLinkAccessField,\n } satisfies UpdateSharedLinkOnWebLinkRequestBodySharedLinkField,\n } satisfies UpdateSharedLinkOnWebLinkRequestBody,\n { fields: 'shared_link' } satisfies UpdateSharedLinkOnWebLinkQueryParams,\n);" }, { "lang": "python", "label": "Update shared link on web link", "source": "client.shared_links_web_links.update_shared_link_on_web_link(\n web_link_id,\n \"shared_link\",\n shared_link=UpdateSharedLinkOnWebLinkSharedLink(\n access=UpdateSharedLinkOnWebLinkSharedLinkAccessField.COLLABORATORS\n ),\n)" } ] } }, "/web_links/{web_link_id}#remove_shared_link": { "put": { "operationId": "put_web_links_id#remove_shared_link", "summary": "Remove shared link from web link", "description": "Removes a shared link from a web link.", "parameters": [ { "name": "web_link_id", "in": "path", "description": "The ID of the web link.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "description": "Explicitly request the `shared_link` fields to be returned for this item.", "required": true, "schema": { "type": "string" }, "example": "shared_link" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link is removed from the web link.", "type": "object", "example": null, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a basic representation of a web link, with the shared link removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebLink" }, "examples": { "default": { "value": { "id": "12345", "type": "web_link", "etag": "1", "shared_link": null } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned if the user does not have all the permissions to complete the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the file is not found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "412": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_web_links", "tags": [ "Shared links (Web Links)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove shared link from web link", "source": "curl -i -X PUT \"https://api.box.com/2.0/web_links/32423234?fields=shared_link\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"shared_link\": null\n }'" }, { "lang": "dotnet", "label": "Remove shared link from web link", "source": "await client.SharedLinksWebLinks.RemoveSharedLinkFromWebLinkAsync(webLinkId: webLinkId, requestBody: new RemoveSharedLinkFromWebLinkRequestBody() { SharedLink = null }, queryParams: new RemoveSharedLinkFromWebLinkQueryParams(fields: \"shared_link\"));" }, { "lang": "java", "label": "Remove shared link from web link", "source": "client.getSharedLinksWebLinks().removeSharedLinkFromWebLink(webLinkId, new RemoveSharedLinkFromWebLinkRequestBody.Builder().sharedLink(null).build(), new RemoveSharedLinkFromWebLinkQueryParams(\"shared_link\"))" }, { "lang": "node", "label": "Remove shared link from web link", "source": "await client.sharedLinksWebLinks.removeSharedLinkFromWebLink(\n webLinkId,\n { sharedLink: createNull() } satisfies RemoveSharedLinkFromWebLinkRequestBody,\n { fields: 'shared_link' } satisfies RemoveSharedLinkFromWebLinkQueryParams,\n);" }, { "lang": "python", "label": "Remove shared link from web link", "source": "client.shared_links_web_links.remove_shared_link_from_web_link(\n web_link_id, \"shared_link\", shared_link=create_null()\n)" } ] } }, "/shared_items#app_items": { "get": { "operationId": "get_shared_items#app_items", "summary": "Find app item for shared link", "description": "Returns the app item represented by a shared link.\n\nThe link can originate from the current enterprise or another.", "parameters": [ { "name": "boxapi", "in": "header", "description": "A header containing the shared link and optional password for the shared link.\n\nThe format for this header is `shared_link=[link]&shared_link_password=[password]`.", "required": true, "schema": { "type": "string" }, "example": "shared_link=[example.com]&shared_link_password=[xyz123]" } ], "responses": { "200": { "description": "Returns a full app item resource if the shared link is valid and the user has access to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppItem" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shared_links_app_items", "tags": [ "Shared links (App Items)" ], "x-codeSamples": [ { "lang": "dotnet", "label": "Find app item for shared link", "source": "await client.SharedLinksAppItems.FindAppItemForSharedLinkAsync(headers: new FindAppItemForSharedLinkHeaders(boxapi: string.Concat(\"shared_link=\", appItemSharedLink)));" }, { "lang": "swift", "label": "Find app item for shared link", "source": "try await client.sharedLinksAppItems.findAppItemForSharedLink(headers: FindAppItemForSharedLinkHeaders(boxapi: \"\\(\"shared_link=\")\\(appItemSharedLink)\"))" }, { "lang": "java", "label": "Find app item for shared link", "source": "client.getSharedLinksAppItems().findAppItemForSharedLink(new FindAppItemForSharedLinkHeaders(String.join(\"\", \"shared_link=\", appItemSharedLink)))" }, { "lang": "node", "label": "Find app item for shared link", "source": "await client.sharedLinksAppItems.findAppItemForSharedLink({\n boxapi: ''.concat('shared_link=', appItemSharedLink) as string,\n} satisfies FindAppItemForSharedLinkHeadersInput);" }, { "lang": "python", "label": "Find app item for shared link", "source": "client.shared_links_app_items.find_app_item_for_shared_link(\n \"\".join([\"shared_link=\", app_item_shared_link])\n)" } ] } }, "/users": { "get": { "operationId": "get_users", "summary": "List enterprise users", "description": "Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`.\n\nThe application and the authenticated user need to have the permission to look up users in the entire enterprise.", "parameters": [ { "name": "filter_term", "in": "query", "description": "Limits the results to only users who's `name` or `login` start with the search term.\n\nFor 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.", "required": false, "schema": { "type": "string" }, "example": "john" }, { "name": "user_type", "in": "query", "description": "Limits the results to the kind of user specified.\n\n- `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.\n- `managed` returns all managed and app users for whom the `login` or `name` partially matches the `filter_term`.\n- `external` returns all external users for whom the `login` matches the `filter_term` exactly.", "required": false, "schema": { "type": "string", "enum": [ "all", "managed", "external" ] }, "example": "managed" }, { "name": "external_app_user_id", "in": "query", "description": "Limits the results to app users with the given `external_app_user_id` value.\n\nWhen 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.", "required": false, "schema": { "type": "string" }, "example": "my-user-1234" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "usemarker", "in": "query", "description": "Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time.\n\nBy 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.", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { "200": { "description": "Returns all of the users in the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Users" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "users", "tags": [ "Users" ], "x-codeSamples": [ { "lang": "curl", "label": "List enterprise users", "source": "curl -i -X GET \"https://api.box.com/2.0/users\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List enterprise users", "source": "await client.Users.GetUsersAsync();" }, { "lang": "swift", "label": "List enterprise users", "source": "try await client.users.getUsers()" }, { "lang": "java", "label": "List enterprise users", "source": "client.getUsers().getUsers()" }, { "lang": "node", "label": "List enterprise users", "source": "await client.users.getUsers();" }, { "lang": "python", "label": "List enterprise users", "source": "client.users.get_users()" } ] }, "post": { "operationId": "post_users", "summary": "Create user", "description": "Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the user.", "type": "string", "example": "Aaron Levie", "maxLength": 50 }, "login": { "description": "The email address the user uses to log in\n\nRequired, unless `is_platform_access_only` is set to `true`.", "type": "string", "example": "boss@box.com" }, "is_platform_access_only": { "description": "Specifies that the user is an app user.", "type": "boolean", "example": true }, "role": { "description": "The user’s enterprise role.", "type": "string", "example": "user", "enum": [ "coadmin", "user" ] }, "language": { "description": "The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format.", "type": "string", "example": "en" }, "is_sync_enabled": { "description": "Whether the user can use Box Sync.", "type": "boolean", "example": true }, "job_title": { "description": "The user’s job title.", "type": "string", "example": "CEO", "maxLength": 100 }, "phone": { "description": "The user’s phone number.", "type": "string", "example": "6509241374", "maxLength": 100 }, "address": { "description": "The user’s address.", "type": "string", "example": "900 Jefferson Ave, Redwood City, CA 94063", "maxLength": 255 }, "space_amount": { "description": "The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage.", "type": "integer", "format": "int64", "example": 11345156112 }, "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.", "type": "array", "items": { "$ref": "#/components/schemas/TrackingCode" } }, "can_see_managed_users": { "description": "Whether the user can see other enterprise users in their contact list.", "type": "boolean", "example": true }, "timezone": { "description": "The user's timezone.", "type": "string", "format": "timezone", "example": "Africa/Bujumbura" }, "is_external_collab_restricted": { "description": "Whether the user is allowed to collaborate with users outside their enterprise.", "type": "boolean", "example": true }, "is_exempt_from_device_limits": { "description": "Whether to exempt the user from enterprise device limits.", "type": "boolean", "example": true }, "is_exempt_from_login_verification": { "description": "Whether the user must use two-factor authentication.", "type": "boolean", "example": true }, "status": { "description": "The user's account status.", "type": "string", "example": "active", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ] }, "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.", "type": "string", "example": "my-user-1234" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Returns a user object for the newly created user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "users", "tags": [ "Users" ], "x-codeSamples": [ { "lang": "curl", "label": "Create user", "source": "curl -i -X POST \"https://api.box.com/2.0/users\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"login\": \"ceo@example.com\",\n \"name\": \"Aaron Levie\"\n }'" }, { "lang": "dotnet", "label": "Create user", "source": "await client.Users.CreateUserAsync(requestBody: new CreateUserRequestBody(name: userName) { Login = userLogin, IsPlatformAccessOnly = true });" }, { "lang": "swift", "label": "Create user", "source": "try await client.users.createUser(requestBody: CreateUserRequestBody(name: userName, login: userLogin, isPlatformAccessOnly: true))" }, { "lang": "java", "label": "Create user", "source": "client.getUsers().createUser(new CreateUserRequestBody.Builder(userName).login(userLogin).isPlatformAccessOnly(true).build())" }, { "lang": "node", "label": "Create user", "source": "await client.users.createUser({\n name: userName,\n login: userLogin,\n isPlatformAccessOnly: true,\n} satisfies CreateUserRequestBody);" }, { "lang": "python", "label": "Create user", "source": "client.users.create_user(user_name, login=user_login, is_platform_access_only=True)" } ] } }, "/users/me": { "get": { "operationId": "get_users_me", "summary": "Get current user", "description": "Retrieves information about the user who is currently authenticated.\n\nIn the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app.\n\nIn the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default.\n\nUse the `As-User` header to change who this API call is made on behalf of.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns a single user object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "users", "tags": [ "Users" ], "x-codeSamples": [ { "lang": "curl", "label": "Get current user", "source": "curl -i -X GET \"https://api.box.com/2.0/users/me\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get current user", "source": "await client.Users.GetUserMeAsync();" }, { "lang": "swift", "label": "Get current user", "source": "try await client.users.getUserMe()" }, { "lang": "java", "label": "Get current user", "source": "client.getUsers().getUserMe()" }, { "lang": "node", "label": "Get current user", "source": "await client.users.getUserMe();" }, { "lang": "python", "label": "Get current user", "source": "client.users.get_user_me()" } ] } }, "/users/terminate_sessions": { "post": { "operationId": "post_users_terminate_sessions", "summary": "Create jobs to terminate users session", "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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_ids": { "description": "A list of user IDs.", "type": "array", "items": { "type": "string" }, "example": [ "123456", "456789" ] }, "user_logins": { "description": "A list of user logins.", "type": "array", "items": { "type": "string" }, "example": [ "user@sample.com", "user2@sample.com" ] } }, "required": [ "user_ids", "user_logins" ] } } } }, "responses": { "202": { "description": "Returns a message about the request status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTerminationMessage" } } } }, "400": { "description": "Returns an error if some of the parameters are not valid.\n\n- `Users can not be NULL or EMPTY` when no value is provided.\n- `User id format is string` when the provided user id format is incorrect.\n- `Supported payload format is JSON` when the provided payload format is incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if there are insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returns an error if the rate limit is exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error if there is an internal server issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error if the request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "session_termination", "tags": [ "Session termination" ], "x-codeSamples": [ { "lang": "curl", "label": "Create jobs to terminate users session", "source": "curl -i -X POST \"https://api.box.com/2.0/users/terminate_sessions\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -H \"accept: application/json\" \\\n -d\n {\n user_ids: [\"6178859178\", \"4824866571\"]\n user_logins: [\"user@example.com\", \"user2@example.com\",]\n }" }, { "lang": "dotnet", "label": "Create jobs to terminate users session", "source": "await client.SessionTermination.TerminateUsersSessionsAsync(requestBody: new TerminateUsersSessionsRequestBody(userIds: Array.AsReadOnly(new [] {Utils.GetEnvVar(\"USER_ID\")}), userLogins: Array.AsReadOnly(new [] {NullableUtils.Unwrap(user.Login)})));" }, { "lang": "swift", "label": "Create jobs to terminate users session", "source": "try await client.sessionTermination.terminateUsersSessions(requestBody: TerminateUsersSessionsRequestBody(userIds: [Utils.getEnvironmentVariable(name: \"USER_ID\")], userLogins: [user.login!]))" }, { "lang": "java", "label": "Create jobs to terminate users session", "source": "client.getSessionTermination().terminateUsersSessions(new TerminateUsersSessionsRequestBody(Arrays.asList(getEnvVar(\"USER_ID\")), Arrays.asList(user.getLogin())))" }, { "lang": "node", "label": "Create jobs to terminate users session", "source": "await client.sessionTermination.terminateUsersSessions({\n userIds: [getEnvVar('USER_ID')],\n userLogins: [user.login!],\n} satisfies TerminateUsersSessionsRequestBody);" }, { "lang": "python", "label": "Create jobs to terminate users session", "source": "client.session_termination.terminate_users_sessions(\n [get_env_var(\"USER_ID\")], [user.login]\n)" } ] } }, "/users/{user_id}": { "get": { "operationId": "get_users_id", "summary": "Get user", "description": "Retrieves information about a user in the enterprise.\n\nThe application and the authenticated user need to have the permission to look up users in the entire enterprise.\n\nThis 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.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns a single user object.\n\nNot all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields using the [fields](#parameter-fields) parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "users", "tags": [ "Users" ], "x-codeSamples": [ { "lang": "curl", "label": "Get user", "source": "curl -i -X GET \"https://api.box.com/2.0/users/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get user", "source": "await client.Users.GetUserByIdAsync(userId: user.Id);" }, { "lang": "swift", "label": "Get user", "source": "try await client.users.getUserById(userId: user.id)" }, { "lang": "java", "label": "Get user", "source": "client.getUsers().getUserById(user.getId())" }, { "lang": "node", "label": "Get user", "source": "await client.users.getUserById(user.id);" }, { "lang": "python", "label": "Get user", "source": "client.users.get_user_by_id(user.id)" } ] }, "put": { "operationId": "put_users_id", "summary": "Update user", "description": "Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enterprise": { "description": "Set this to `null` to roll the user out of the enterprise and make them a free user.", "type": "string", "example": null, "nullable": true }, "notify": { "description": "Whether the user should receive an email when they are rolled out of an enterprise.", "type": "boolean", "example": true }, "name": { "description": "The name of the user.", "type": "string", "example": "Aaron Levie", "maxLength": 50 }, "login": { "description": "The email address the user uses to log in\n\nNote: If the target user's email is not confirmed, then the primary login address cannot be changed.", "type": "string", "example": "somename@box.com" }, "role": { "description": "The user’s enterprise role.", "type": "string", "example": "user", "enum": [ "coadmin", "user" ] }, "language": { "description": "The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format.", "type": "string", "example": "en" }, "is_sync_enabled": { "description": "Whether the user can use Box Sync.", "type": "boolean", "example": true }, "job_title": { "description": "The user’s job title.", "type": "string", "example": "CEO", "maxLength": 100 }, "phone": { "description": "The user’s phone number.", "type": "string", "example": "6509241374", "maxLength": 100 }, "address": { "description": "The user’s address.", "type": "string", "example": "900 Jefferson Ave, Redwood City, CA 94063", "maxLength": 255 }, "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.", "type": "array", "items": { "$ref": "#/components/schemas/TrackingCode" } }, "can_see_managed_users": { "description": "Whether the user can see other enterprise users in their contact list.", "type": "boolean", "example": true }, "timezone": { "description": "The user's timezone.", "type": "string", "format": "timezone", "example": "Africa/Bujumbura" }, "is_external_collab_restricted": { "description": "Whether the user is allowed to collaborate with users outside their enterprise.", "type": "boolean", "example": true }, "is_exempt_from_device_limits": { "description": "Whether to exempt the user from enterprise device limits.", "type": "boolean", "example": true }, "is_exempt_from_login_verification": { "description": "Whether the user must use two-factor authentication.", "type": "boolean", "example": true }, "is_password_reset_required": { "description": "Whether the user is required to reset their password.", "type": "boolean", "example": true }, "status": { "description": "The user's account status.", "type": "string", "example": "active", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ] }, "space_amount": { "description": "The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage.", "type": "integer", "format": "int64", "example": 11345156112 }, "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.\n\nSet this value to `null` to remove the notification email.", "type": "object", "nullable": true, "properties": { "email": { "description": "The email address to send the notifications to.", "type": "string", "example": "notifications@example.com" } } }, "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.\n\nNote: In order to update this field, you need to request a token using the application that created the app user.", "type": "string", "example": "my-user-1234" } } } } } }, "responses": { "200": { "description": "Returns the updated user object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User--Full" } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `invalid_parameter` when a parameter is formatted incorrectly, for example when the `notification_email` has an incorrectly formatted email address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the user is not allowed to make the changes.\n\n- `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.\n- `denied_by_policy` when the user does not have the right permissions due to the information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "users", "tags": [ "Users" ], "x-codeSamples": [ { "lang": "curl", "label": "Update user", "source": "curl -i -X PUT \"https://api.box.com/2.0/users/12345\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"Aaron Levie\"\n }'" }, { "lang": "dotnet", "label": "Update user", "source": "await client.Users.UpdateUserByIdAsync(userId: user.Id, requestBody: new UpdateUserByIdRequestBody() { Name = updatedUserName });" }, { "lang": "swift", "label": "Update user", "source": "try await client.users.updateUserById(userId: user.id, requestBody: UpdateUserByIdRequestBody(name: updatedUserName))" }, { "lang": "java", "label": "Update user", "source": "client.getUsers().updateUserById(user.getId(), new UpdateUserByIdRequestBody.Builder().name(updatedUserName).build())" }, { "lang": "node", "label": "Update user", "source": "await client.users.updateUserById(user.id, {\n requestBody: { name: updatedUserName } satisfies UpdateUserByIdRequestBody,\n} satisfies UpdateUserByIdOptionalsInput);" }, { "lang": "python", "label": "Update user", "source": "client.users.update_user_by_id(user.id, name=updated_user_name)" } ] }, "delete": { "operationId": "delete_users_id", "summary": "Delete user", "description": "Deletes a user. By default, this operation fails if the user still owns any content. To proceed, move their owned content first, or use the `force` parameter to delete the user and their files.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "notify", "in": "query", "description": "Whether the user will receive email notification of the deletion.", "schema": { "type": "boolean" }, "example": true }, { "name": "force", "in": "query", "description": "Specifies whether to delete the user even if they still own files.", "schema": { "type": "boolean" }, "example": true } ], "responses": { "204": { "description": "Removes the user and returns an empty response." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "users", "tags": [ "Users" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete user", "source": "curl -i -X DELETE \"https://api.box.com/2.0/users/12345\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete user", "source": "await client.Users.DeleteUserByIdAsync(userId: user.Id);" }, { "lang": "swift", "label": "Delete user", "source": "try await client.users.deleteUserById(userId: user.id)" }, { "lang": "java", "label": "Delete user", "source": "client.getUsers().deleteUserById(user.getId())" }, { "lang": "node", "label": "Delete user", "source": "await client.users.deleteUserById(user.id);" }, { "lang": "python", "label": "Delete user", "source": "client.users.delete_user_by_id(user.id)" } ] } }, "/users/{user_id}/avatar": { "get": { "operationId": "get_users_id_avatar", "summary": "Get user avatar", "description": "Retrieves an image of a the user's avatar.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "When an avatar can be found for the user the image data will be returned in the body of the response.", "content": { "image/jpg": { "schema": { "description": "The avatar.", "type": "string", "format": "binary" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "avatars", "tags": [ "User avatars" ], "x-codeSamples": [ { "lang": "curl", "label": "Get user avatar", "source": "curl -i -X GET \"https://api.box.com/2.0/users/12345/avatar\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get user avatar", "source": "await client.Avatars.GetUserAvatarAsync(userId: user.Id);" }, { "lang": "swift", "label": "Get user avatar", "source": "try await client.avatars.getUserAvatar(userId: user.id, downloadDestinationUrl: destinationPath)" }, { "lang": "java", "label": "Get user avatar", "source": "client.getAvatars().getUserAvatar(user.getId())" }, { "lang": "node", "label": "Get user avatar", "source": "await client.avatars.getUserAvatar(user.id);" }, { "lang": "python", "label": "Get user avatar", "source": "client.avatars.get_user_avatar(user.id)" } ] }, "post": { "operationId": "post_users_id_avatar", "summary": "Add or update user avatar", "description": "Adds or updates a user avatar.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "pic": { "description": "The image file to be uploaded to Box. Accepted file extensions are `.jpg` or `.png`. The maximum file size is 1MB.", "type": "string", "format": "binary" } }, "required": [ "pic" ] } } } }, "responses": { "200": { "description": "`ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvatar" } } } }, "201": { "description": "`created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAvatar" } } } }, "400": { "description": "`bad_request`: Returns an error when:\n\n- An image is not included in the request\n- The uploaded file is empty\n- The image size exceeds 1024 \\* 1024 pixels or 1MB\n- The file extension is other than `.jpg` or `.png`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "`forbidden`: Returns an error if the user does not have permissions necessary to upload an avatar or is not activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "`not_found`: Returns an error if the user does not exist or cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "avatars", "tags": [ "User avatars" ], "x-codeSamples": [ { "lang": "curl", "label": "Add or update user avatar", "source": "curl -i -L -X POST \"https://api.box.net/2.0/users/12345/avatar\" \\\n -H \"authorization: Bearer \" \\\n --form 'pic=@\"path/to/file/file.jpeg\"'" }, { "lang": "dotnet", "label": "Add or update user avatar", "source": "await client.Avatars.CreateUserAvatarAsync(userId: user.Id, requestBody: new CreateUserAvatarRequestBody(pic: Utils.DecodeBase64ByteStream(data: \"iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==\")) { PicContentType = \"image/png\", PicFileName = \"avatar.png\" });" }, { "lang": "swift", "label": "Add or update user avatar", "source": "try await client.avatars.createUserAvatar(userId: user.id, requestBody: CreateUserAvatarRequestBody(pic: Utils.decodeBase64ByteStream(data: \"iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==\"), picContentType: \"image/png\", picFileName: \"avatar.png\"))" }, { "lang": "java", "label": "Add or update user avatar", "source": "client.getAvatars().createUserAvatar(user.getId(), new CreateUserAvatarRequestBody.Builder(decodeBase64ByteStream(\"iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==\")).picFileName(\"avatar.png\").picContentType(\"image/png\").build())" }, { "lang": "node", "label": "Add or update user avatar", "source": "await client.avatars.createUserAvatar(user.id, {\n pic: decodeBase64ByteStream(\n 'iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==',\n ),\n picContentType: 'image/png',\n picFileName: 'avatar.png',\n} satisfies CreateUserAvatarRequestBody);" }, { "lang": "python", "label": "Add or update user avatar", "source": "client.avatars.create_user_avatar(\n user.id,\n decode_base_64_byte_stream(\n \"iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAAA1BMVEW10NBjBBbqAAAAH0lEQVRoge3BAQ0AAADCoPdPbQ43oAAAAAAAAAAAvg0hAAABmmDh1QAAAABJRU5ErkJggg==\"\n ),\n pic_file_name=\"avatar.png\",\n pic_content_type=\"image/png\",\n)" } ] }, "delete": { "operationId": "delete_users_id_avatar", "summary": "Delete user avatar", "description": "Removes an existing user avatar. You cannot reverse this operation.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "204": { "description": "`no_content`: Removes the avatar and returns an empty response." }, "403": { "description": "`forbidden`: Returned if the user does not have necessary permissions or is not activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "`not_found`: Returned if the user or user avatar does not exist or cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "avatars", "tags": [ "User avatars" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete user avatar", "source": "curl -i -X DELETE -L \"https://api.box.net/2.0/users/12345/avatar\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete user avatar", "source": "await client.Avatars.DeleteUserAvatarAsync(userId: user.Id);" }, { "lang": "swift", "label": "Delete user avatar", "source": "try await client.avatars.deleteUserAvatar(userId: user.id)" }, { "lang": "java", "label": "Delete user avatar", "source": "client.getAvatars().deleteUserAvatar(user.getId())" }, { "lang": "node", "label": "Delete user avatar", "source": "await client.avatars.deleteUserAvatar(user.id);" }, { "lang": "python", "label": "Delete user avatar", "source": "client.avatars.delete_user_avatar(user.id)" } ] } }, "/users/{user_id}/folders/0": { "put": { "operationId": "put_users_id_folders_0", "summary": "Transfer owned folders", "description": "Move all of the items (files, folders and workflows) owned by a user into another user's account.\n\nOnly the root folder (`0`) can be transferred.\n\nFolders can only be moved across users by users with administrative permissions.\n\nAll 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.\n\nIf the user has a large number of items across all folders, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running.\n\nIf the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously.\n\nThere is currently no way to check for when this operation is finished.\n\nThe destination folder's name will be in the format `{User}'s Files and Folders`, where `{User}` is the display name of the user.\n\nTo make this API call your application will need to have the \"Read and write all files and folders stored in Box\" scope enabled.\n\nPlease 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.\n\nAdmins will receive an email when the operation is completed.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "notify", "in": "query", "description": "Determines if users should receive email notification for the action performed.", "required": false, "schema": { "type": "boolean" }, "example": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "owned_by": { "description": "The user who the folder will be transferred to.", "type": "object", "properties": { "id": { "description": "The ID of the user who the folder will be transferred to.", "type": "string", "example": "1232234" } }, "required": [ "id" ] } }, "required": [ "owned_by" ] } } } }, "responses": { "200": { "description": "Returns the information for the newly created destination folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder--Full" } } } }, "403": { "description": "Returns an error when folder ownership cannot be transferred to another user.\n\n- `forbidden_by_policy`: Returned if ownership transfer is forbidden due to information barrier restrictions.\n- `Cannot transfer files from/to higher privileged accounts`: You can only transfer content to or from managed users or your own account, not other co-admins or admins. Admins can transfer content between any users, including co-admins and managed users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "transfer", "tags": [ "Transfer folders" ], "x-codeSamples": [ { "lang": "curl", "label": "Transfer owned folders", "source": "curl -i -X PUT \"https://api.box.com/2.0/users/12345/folders/0\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"owned_by\": {\n \"id\": \"1232234\"\n }\n }'" }, { "lang": "dotnet", "label": "Transfer owned folders", "source": "await client.Transfer.TransferOwnedFolderAsync(userId: sourceUser.Id, requestBody: new TransferOwnedFolderRequestBody(ownedBy: new TransferOwnedFolderRequestBodyOwnedByField(id: targetUser.Id)), queryParams: new TransferOwnedFolderQueryParams() { Notify = false });" }, { "lang": "swift", "label": "Transfer owned folders", "source": "try await client.transfer.transferOwnedFolder(userId: sourceUser.id, requestBody: TransferOwnedFolderRequestBody(ownedBy: TransferOwnedFolderRequestBodyOwnedByField(id: targetUser.id)), queryParams: TransferOwnedFolderQueryParams(notify: false))" }, { "lang": "java", "label": "Transfer owned folders", "source": "client.getTransfer().transferOwnedFolder(sourceUser.getId(), new TransferOwnedFolderRequestBody(new TransferOwnedFolderRequestBodyOwnedByField(targetUser.getId())), new TransferOwnedFolderQueryParams.Builder().notify(false).build())" }, { "lang": "node", "label": "Transfer owned folders", "source": "await client.transfer.transferOwnedFolder(\n sourceUser.id,\n {\n ownedBy: {\n id: targetUser.id,\n } satisfies TransferOwnedFolderRequestBodyOwnedByField,\n } satisfies TransferOwnedFolderRequestBody,\n {\n queryParams: { notify: false } satisfies TransferOwnedFolderQueryParams,\n } satisfies TransferOwnedFolderOptionalsInput,\n);" }, { "lang": "python", "label": "Transfer owned folders", "source": "client.transfer.transfer_owned_folder(\n source_user.id, TransferOwnedFolderOwnedBy(id=target_user.id), notify=False\n)" } ] } }, "/users/{user_id}/email_aliases": { "get": { "operationId": "get_users_id_email_aliases", "summary": "List user's email aliases", "description": "Retrieves all email aliases for a user. The collection does not include the primary login for the user.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "responses": { "200": { "description": "Returns a collection of email aliases.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAliases" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "email_aliases", "tags": [ "Email aliases" ], "x-codeSamples": [ { "lang": "curl", "label": "List user's email aliases", "source": "curl -i -X GET \"https://api.box.com/2.0/users/12345/email_aliases\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List user's email aliases", "source": "await client.EmailAliases.GetUserEmailAliasesAsync(userId: newUser.Id);" }, { "lang": "swift", "label": "List user's email aliases", "source": "try await client.emailAliases.getUserEmailAliases(userId: newUser.id)" }, { "lang": "java", "label": "List user's email aliases", "source": "client.getEmailAliases().getUserEmailAliases(newUser.getId())" }, { "lang": "node", "label": "List user's email aliases", "source": "await client.emailAliases.getUserEmailAliases(newUser.id);" }, { "lang": "python", "label": "List user's email aliases", "source": "client.email_aliases.get_user_email_aliases(new_user.id)" } ] }, "post": { "operationId": "post_users_id_email_aliases", "summary": "Create email alias", "description": "Adds a new email alias to a user account..", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The email address to add to the account as an alias.\n\nNote: 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.", "type": "string", "example": "alias@example.com" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Returns the newly created email alias object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAlias" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "email_aliases", "tags": [ "Email aliases" ], "x-codeSamples": [ { "lang": "curl", "label": "Create email alias", "source": "curl -i -X POST \"https://api.box.com/2.0/users/12345/email_aliases\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"email\": \"alias@example.com\"\n }'" }, { "lang": "dotnet", "label": "Create email alias", "source": "await client.EmailAliases.CreateUserEmailAliasAsync(userId: newUser.Id, requestBody: new CreateUserEmailAliasRequestBody(email: newAliasEmail));" }, { "lang": "swift", "label": "Create email alias", "source": "try await client.emailAliases.createUserEmailAlias(userId: newUser.id, requestBody: CreateUserEmailAliasRequestBody(email: newAliasEmail))" }, { "lang": "java", "label": "Create email alias", "source": "client.getEmailAliases().createUserEmailAlias(newUser.getId(), new CreateUserEmailAliasRequestBody(newAliasEmail))" }, { "lang": "node", "label": "Create email alias", "source": "await client.emailAliases.createUserEmailAlias(newUser.id, {\n email: newAliasEmail,\n} satisfies CreateUserEmailAliasRequestBody);" }, { "lang": "python", "label": "Create email alias", "source": "client.email_aliases.create_user_email_alias(new_user.id, new_alias_email)" } ] } }, "/users/{user_id}/email_aliases/{email_alias_id}": { "delete": { "operationId": "delete_users_id_email_aliases_id", "summary": "Remove email alias", "description": "Removes an email alias from a user.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "email_alias_id", "in": "path", "description": "The ID of the email alias.", "required": true, "schema": { "type": "string" }, "example": "23432" } ], "responses": { "204": { "description": "Removes the alias and returns an empty response." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "email_aliases", "tags": [ "Email aliases" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove email alias", "source": "curl -i -X DELETE \"https://api.box.com/2.0/users/12345/email_aliases/23432\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove email alias", "source": "await client.EmailAliases.DeleteUserEmailAliasByIdAsync(userId: newUser.Id, emailAliasId: NullableUtils.Unwrap(newAlias.Id));" }, { "lang": "swift", "label": "Remove email alias", "source": "try await client.emailAliases.deleteUserEmailAliasById(userId: newUser.id, emailAliasId: newAlias.id!)" }, { "lang": "java", "label": "Remove email alias", "source": "client.getEmailAliases().deleteUserEmailAliasById(newUser.getId(), newAlias.getId())" }, { "lang": "node", "label": "Remove email alias", "source": "await client.emailAliases.deleteUserEmailAliasById(newUser.id, newAlias.id!);" }, { "lang": "python", "label": "Remove email alias", "source": "client.email_aliases.delete_user_email_alias_by_id(new_user.id, new_alias.id)" } ] } }, "/users/{user_id}/memberships": { "get": { "operationId": "get_users_id_memberships", "summary": "List user's groups", "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.", "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of membership objects. If there are no memberships, an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberships" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "memberships", "tags": [ "Group memberships" ], "x-codeSamples": [ { "lang": "curl", "label": "List user's groups", "source": "curl -i -X GET \"https://api.box.com/2.0/users/12345/memberships\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List user's groups", "source": "await client.Memberships.GetUserMembershipsAsync(userId: user.Id);" }, { "lang": "swift", "label": "List user's groups", "source": "try await client.memberships.getUserMemberships(userId: user.id)" }, { "lang": "java", "label": "List user's groups", "source": "client.getMemberships().getUserMemberships(user.getId())" }, { "lang": "node", "label": "List user's groups", "source": "await client.memberships.getUserMemberships(user.id);" }, { "lang": "python", "label": "List user's groups", "source": "client.memberships.get_user_memberships(user.id)" } ] } }, "/invites": { "post": { "operationId": "post_invites", "summary": "Create user invite", "description": "Invites an existing external user to join an enterprise.\n\nThe 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.\n\nThis method requires the \"Manage An Enterprise\" scope enabled for the application, which can be enabled within the developer console.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enterprise": { "description": "The enterprise to invite the user to.", "type": "object", "properties": { "id": { "description": "The ID of the enterprise.", "type": "string", "example": "1232234" } }, "required": [ "id" ] }, "actionable_by": { "description": "The user to invite.", "type": "object", "properties": { "login": { "description": "The login of the invited user.", "type": "string", "example": "john@example.com" } }, "required": [ "id" ] } }, "required": [ "enterprise", "actionable_by" ] } } } }, "responses": { "200": { "description": "Returns a new invite object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "404": { "description": "Returns `not_found` when user was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "invites", "tags": [ "Invites" ], "x-codeSamples": [ { "lang": "curl", "label": "Create user invite", "source": "curl -i -X POST \"https://api.box.com/2.0/invites\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"enterprise\": {\n \"id\": \"1232234\"\n },\n \"actionable_by\": {\n \"login\" : \"freeuser@box.com\"\n }\n }'" }, { "lang": "dotnet", "label": "Create user invite", "source": "await client.Invites.CreateInviteAsync(requestBody: new CreateInviteRequestBody(enterprise: new CreateInviteRequestBodyEnterpriseField(id: NullableUtils.Unwrap(NullableUtils.Unwrap(currentUser.Enterprise).Id)), actionableBy: new CreateInviteRequestBodyActionableByField() { Login = email }));" }, { "lang": "swift", "label": "Create user invite", "source": "try await client.invites.createInvite(requestBody: CreateInviteRequestBody(enterprise: CreateInviteRequestBodyEnterpriseField(id: currentUser.enterprise!.id!), actionableBy: CreateInviteRequestBodyActionableByField(login: email)))" }, { "lang": "java", "label": "Create user invite", "source": "client.getInvites().createInvite(new CreateInviteRequestBody(new CreateInviteRequestBodyEnterpriseField(currentUser.getEnterprise().getId()), new CreateInviteRequestBodyActionableByField.Builder().login(email).build()))" }, { "lang": "node", "label": "Create user invite", "source": "await client.invites.createInvite({\n enterprise: {\n id: currentUser.enterprise!.id!,\n } satisfies CreateInviteRequestBodyEnterpriseField,\n actionableBy: {\n login: email,\n } satisfies CreateInviteRequestBodyActionableByField,\n} satisfies CreateInviteRequestBody);" }, { "lang": "python", "label": "Create user invite", "source": "client.invites.create_invite(\n CreateInviteEnterprise(id=current_user.enterprise.id),\n CreateInviteActionableBy(login=email),\n)" } ] } }, "/invites/{invite_id}": { "get": { "operationId": "get_invites_id", "summary": "Get user invite status", "description": "Returns the status of a user invite.", "parameters": [ { "name": "invite_id", "in": "path", "description": "The ID of an invite.", "required": true, "schema": { "type": "string" }, "example": "213723" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns an invite object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "invites", "tags": [ "Invites" ], "x-codeSamples": [ { "lang": "curl", "label": "Get user invite status", "source": "curl -i -X GET \"https://api.box.com/2.0/invites/213723\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get user invite status", "source": "await client.Invites.GetInviteByIdAsync(inviteId: invitation.Id);" }, { "lang": "swift", "label": "Get user invite status", "source": "try await client.invites.getInviteById(inviteId: invitation.id)" }, { "lang": "java", "label": "Get user invite status", "source": "client.getInvites().getInviteById(invitation.getId())" }, { "lang": "node", "label": "Get user invite status", "source": "await client.invites.getInviteById(invitation.id);" }, { "lang": "python", "label": "Get user invite status", "source": "client.invites.get_invite_by_id(invitation.id)" } ] } }, "/groups": { "get": { "operationId": "get_groups", "summary": "List groups for enterprise", "description": "Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups.", "parameters": [ { "name": "filter_term", "in": "query", "description": "Limits the results to only groups whose `name` starts with the search term.", "required": false, "schema": { "type": "string" }, "example": "Engineering" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of group objects. If there are no groups, an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Groups" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "groups", "tags": [ "Groups" ], "x-codeSamples": [ { "lang": "curl", "label": "List groups for enterprise", "source": "curl -i -X GET \"https://api.box.com/2.0/groups\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List groups for enterprise", "source": "await client.Groups.GetGroupsAsync();" }, { "lang": "swift", "label": "List groups for enterprise", "source": "try await client.groups.getGroups()" }, { "lang": "java", "label": "List groups for enterprise", "source": "client.getGroups().getGroups()" }, { "lang": "node", "label": "List groups for enterprise", "source": "await client.groups.getGroups();" }, { "lang": "python", "label": "List groups for enterprise", "source": "client.groups.get_groups()" } ] }, "post": { "operationId": "post_groups", "summary": "Create group", "description": "Creates a new group of users in an enterprise. Only users with admin permissions can create new groups.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the new group to be created. This name must be unique within the enterprise.", "type": "string", "example": "Customer Support" }, "provenance": { "description": "Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`.\n\nSetting this will also prevent Box admins from editing the group name and its members directly via the Box web application.\n\nThis is desirable for one-way syncing of groups.", "type": "string", "example": "Active Directory", "maxLength": 255 }, "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.\n\nExample values of this field could be an **Active Directory Object ID** or a **Google Group ID**.\n\nWe recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems.", "type": "string", "example": "AD:123456" }, "description": { "description": "A human readable description of the group.", "type": "string", "example": "\"Customer Support Group - as imported from Active Directory\"", "maxLength": 255 }, "invitability_level": { "description": "Specifies who can invite the group to collaborate on folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed above and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the enterprise can invite the group.", "type": "string", "example": "admins_only", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "member_viewability_level": { "description": "Specifies who can see the members of the group.\n\n- `admins_only` - the enterprise admin, co-admins, group's group admin.\n- `admins_and_members` - all admins and group members.\n- `all_managed_users` - all managed users in the enterprise.", "type": "string", "example": "admins_only", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Returns the new group object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group--Full" } } } }, "409": { "description": "Returns an error a conflict is stopping the group from being created.\n\n- `invalid_parameter`: Often returned if the group name is not unique in the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "groups", "tags": [ "Groups" ], "x-codeSamples": [ { "lang": "curl", "label": "Create group", "source": "curl -i -X POST \"https://api.box.com/2.0/groups\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"Customer Support\"\n }'" }, { "lang": "dotnet", "label": "Create group", "source": "await client.Groups.CreateGroupAsync(requestBody: new CreateGroupRequestBody(name: groupName) { Description = groupDescription });" }, { "lang": "swift", "label": "Create group", "source": "try await client.groups.createGroup(requestBody: CreateGroupRequestBody(name: groupName, description: groupDescription))" }, { "lang": "java", "label": "Create group", "source": "client.getGroups().createGroup(new CreateGroupRequestBody.Builder(groupName).description(groupDescription).build())" }, { "lang": "node", "label": "Create group", "source": "await client.groups.createGroup({\n name: groupName,\n description: groupDescription,\n} satisfies CreateGroupRequestBody);" }, { "lang": "python", "label": "Create group", "source": "client.groups.create_group(group_name, description=group_description)" } ] } }, "/groups/terminate_sessions": { "post": { "operationId": "post_groups_terminate_sessions", "summary": "Create jobs to terminate user group session", "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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "group_ids": { "description": "A list of group IDs.", "type": "array", "items": { "type": "string" }, "example": [ "123456", "456789" ] } }, "required": [ "group_ids" ] } } } }, "responses": { "202": { "description": "Returns a message about the request status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTerminationMessage" } } } }, "400": { "description": "Returns an error if some of the parameters are not valid.\n\n- `Groups can not be NULL or EMPTY` when no value is provided.\n- `group id format is string` when the provided group id format is incorrect.\n- `Supported payload format is JSON` when the provided payload format is incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if there are insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returns an error if the request limit is exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "Returns an error if there is an internal server issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "503": { "description": "Returns an error if the request timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "session_termination", "tags": [ "Session termination" ], "x-codeSamples": [ { "lang": "curl", "label": "Create jobs to terminate user group session", "source": "curl -i -X POST \"https://api.box.com/2.0/groups/terminate_sessions\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -H \"accept: application/json\" \\\n -d\n {\n   \"group_ids\": [\"6178859178\", \"4824866571\"],\n }" }, { "lang": "dotnet", "label": "Create jobs to terminate user group session", "source": "await client.SessionTermination.TerminateGroupsSessionsAsync(requestBody: new TerminateGroupsSessionsRequestBody(groupIds: Array.AsReadOnly(new [] {group.Id})));" }, { "lang": "swift", "label": "Create jobs to terminate user group session", "source": "try await client.sessionTermination.terminateGroupsSessions(requestBody: TerminateGroupsSessionsRequestBody(groupIds: [group.id]))" }, { "lang": "java", "label": "Create jobs to terminate user group session", "source": "client.getSessionTermination().terminateGroupsSessions(new TerminateGroupsSessionsRequestBody(Arrays.asList(group.getId())))" }, { "lang": "node", "label": "Create jobs to terminate user group session", "source": "await client.sessionTermination.terminateGroupsSessions({\n groupIds: [group.id],\n} satisfies TerminateGroupsSessionsRequestBody);" }, { "lang": "python", "label": "Create jobs to terminate user group session", "source": "client.session_termination.terminate_groups_sessions([group.id])" } ] } }, "/groups/{group_id}": { "get": { "operationId": "get_groups_id", "summary": "Get group", "description": "Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API.", "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group.", "required": true, "schema": { "type": "string" }, "example": "57645" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the group object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group--Full" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "groups", "tags": [ "Groups" ], "x-codeSamples": [ { "lang": "curl", "label": "Get group", "source": "curl -i -X GET \"https://api.box.com/2.0/groups/57645\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get group", "source": "await client.Groups.GetGroupByIdAsync(groupId: group.Id, queryParams: new GetGroupByIdQueryParams() { Fields = Array.AsReadOnly(new [] {\"id\",\"name\",\"description\",\"group_type\"}) });" }, { "lang": "swift", "label": "Get group", "source": "try await client.groups.getGroupById(groupId: group.id, queryParams: GetGroupByIdQueryParams(fields: [\"id\", \"name\", \"description\", \"group_type\"]))" }, { "lang": "java", "label": "Get group", "source": "client.getGroups().getGroupById(group.getId(), new GetGroupByIdQueryParams.Builder().fields(Arrays.asList(\"id\", \"name\", \"description\", \"group_type\")).build())" }, { "lang": "node", "label": "Get group", "source": "await client.groups.getGroupById(group.id, {\n queryParams: {\n fields: ['id', 'name', 'description', 'group_type'],\n } satisfies GetGroupByIdQueryParams,\n} satisfies GetGroupByIdOptionalsInput);" }, { "lang": "python", "label": "Get group", "source": "client.groups.get_group_by_id(\n group.id, fields=[\"id\", \"name\", \"description\", \"group_type\"]\n)" } ] }, "put": { "operationId": "put_groups_id", "summary": "Update group", "description": "Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API.", "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group.", "required": true, "schema": { "type": "string" }, "example": "57645" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the new group to be created. Must be unique within the enterprise.", "type": "string", "example": "Customer Support" }, "provenance": { "description": "Keeps track of which external source this group is coming, for example `Active Directory`, or `Okta`.\n\nSetting this will also prevent Box admins from editing the group name and its members directly via the Box web application.\n\nThis is desirable for one-way syncing of groups.", "type": "string", "example": "Active Directory", "maxLength": 255 }, "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.\n\nExample values of this field could be an **Active Directory Object ID** or a **Google Group ID**.\n\nWe recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems.", "type": "string", "example": "AD:123456" }, "description": { "description": "A human readable description of the group.", "type": "string", "example": "\"Customer Support Group - as imported from Active Directory\"", "maxLength": 255 }, "invitability_level": { "description": "Specifies who can invite the group to collaborate on folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed above and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the enterprise can invite the group.", "type": "string", "example": "admins_only", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "member_viewability_level": { "description": "Specifies who can see the members of the group.\n\n- `admins_only` - the enterprise admin, co-admins, group's group admin.\n- `admins_and_members` - all admins and group members.\n- `all_managed_users` - all managed users in the enterprise.", "type": "string", "example": "admins_only", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] } } } } } }, "responses": { "200": { "description": "Returns the updated group object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group--Full" } } } }, "409": { "description": "Returns an error a conflict is stopping the group from being created.\n\n- `invalid_parameter`: Often returned if the group name is not unique in the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "groups", "tags": [ "Groups" ], "x-codeSamples": [ { "lang": "curl", "label": "Update group", "source": "curl -i -X PUT \"https://api.box.com/2.0/groups/57645\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"Customer Support\"\n }'" }, { "lang": "dotnet", "label": "Update group", "source": "await client.Groups.UpdateGroupByIdAsync(groupId: group.Id, requestBody: new UpdateGroupByIdRequestBody() { Name = updatedGroupName });" }, { "lang": "swift", "label": "Update group", "source": "try await client.groups.updateGroupById(groupId: group.id, requestBody: UpdateGroupByIdRequestBody(name: updatedGroupName))" }, { "lang": "java", "label": "Update group", "source": "client.getGroups().updateGroupById(group.getId(), new UpdateGroupByIdRequestBody.Builder().name(updatedGroupName).build())" }, { "lang": "node", "label": "Update group", "source": "await client.groups.updateGroupById(group.id, {\n requestBody: { name: updatedGroupName } satisfies UpdateGroupByIdRequestBody,\n} satisfies UpdateGroupByIdOptionalsInput);" }, { "lang": "python", "label": "Update group", "source": "client.groups.update_group_by_id(group.id, name=updated_group_name)" } ] }, "delete": { "operationId": "delete_groups_id", "summary": "Remove group", "description": "Permanently deletes a group. Only users with admin-level permissions will be able to use this API.", "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group.", "required": true, "schema": { "type": "string" }, "example": "57645" } ], "responses": { "204": { "description": "A blank response is returned if the group was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "groups", "tags": [ "Groups" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove group", "source": "curl -i -X DELETE \"https://api.box.com/2.0/groups/57645\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove group", "source": "await client.Groups.DeleteGroupByIdAsync(groupId: group.Id);" }, { "lang": "swift", "label": "Remove group", "source": "try await client.groups.deleteGroupById(groupId: group.id)" }, { "lang": "java", "label": "Remove group", "source": "client.getGroups().deleteGroupById(group.getId())" }, { "lang": "node", "label": "Remove group", "source": "await client.groups.deleteGroupById(group.id);" }, { "lang": "python", "label": "Remove group", "source": "client.groups.delete_group_by_id(group.id)" } ] } }, "/groups/{group_id}/memberships": { "get": { "operationId": "get_groups_id_memberships", "summary": "List members of group", "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.", "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group.", "required": true, "schema": { "type": "string" }, "example": "57645" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of membership objects. If there are no memberships, an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberships" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "memberships", "tags": [ "Group memberships" ], "x-codeSamples": [ { "lang": "curl", "label": "List members of group", "source": "curl -i -X GET \"https://api.box.com/2.0/groups/57645/memberships\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List members of group", "source": "await client.Memberships.GetGroupMembershipsAsync(groupId: group.Id);" }, { "lang": "swift", "label": "List members of group", "source": "try await client.memberships.getGroupMemberships(groupId: group.id)" }, { "lang": "java", "label": "List members of group", "source": "client.getMemberships().getGroupMemberships(group.getId())" }, { "lang": "node", "label": "List members of group", "source": "await client.memberships.getGroupMemberships(group.id);" }, { "lang": "python", "label": "List members of group", "source": "client.memberships.get_group_memberships(group.id)" } ] } }, "/groups/{group_id}/collaborations": { "get": { "operationId": "get_groups_id_collaborations", "summary": "List group collaborations", "description": "Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups.\n\nEach collaboration object has details on which files or folders the group has access to and with what role.", "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group.", "required": true, "schema": { "type": "string" }, "example": "57645" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationsOffsetPaginated" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "list_collaborations", "tags": [ "Collaborations (List)" ], "x-codeSamples": [ { "lang": "curl", "label": "List group collaborations", "source": "curl -i -X GET \"https://api.box.com/2.0/groups/57645/collaborations\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List group collaborations", "source": "await client.ListCollaborations.GetGroupCollaborationsAsync(groupId: group.Id);" }, { "lang": "swift", "label": "List group collaborations", "source": "try await client.listCollaborations.getGroupCollaborations(groupId: group.id)" }, { "lang": "java", "label": "List group collaborations", "source": "client.getListCollaborations().getGroupCollaborations(group.getId())" }, { "lang": "node", "label": "List group collaborations", "source": "await client.listCollaborations.getGroupCollaborations(group.id);" }, { "lang": "python", "label": "List group collaborations", "source": "client.list_collaborations.get_group_collaborations(group.id)" } ] } }, "/group_memberships": { "post": { "operationId": "post_group_memberships", "summary": "Add user to group", "description": "Creates a group membership. Only users with admin-level permissions will be able to use this API.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "description": "The user to add to the group.", "type": "object", "properties": { "id": { "description": "The ID of the user to add to the group.", "type": "string", "example": "1434325" } }, "required": [ "id" ] }, "group": { "description": "The group to add the user to.", "type": "object", "properties": { "id": { "description": "The ID of the group to add the user to.", "type": "string", "example": "4545523" } }, "required": [ "id" ] }, "role": { "description": "The role of the user in the group.", "type": "string", "example": "member", "enum": [ "member", "admin" ] }, "configurable_permissions": { "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`.\n\nSetting these permissions overwrites the default access levels of an admin.\n\nSpecifying 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.", "type": "object", "example": { "can_run_reports": true }, "additionalProperties": { "type": "boolean", "description": "A key value pair of custom permissions.", "example": true, "x-box-example-key": "can_run_reports" }, "nullable": true } }, "required": [ "user", "group" ] } } } }, "responses": { "201": { "description": "Returns a new group membership object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembership" } } } }, "403": { "description": "Returns an error when the user cannot be added to a group.\n\n- `forbidden_by_policy`: Adding a user to a group is forbidden due to information barrier restrictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "memberships", "tags": [ "Group memberships" ], "x-codeSamples": [ { "lang": "curl", "label": "Add user to group", "source": "curl -i -X POST \"https://api.box.com/2.0/group_memberships\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"user\": {\n \"id\": \"1434325\"\n },\n \"group\": {\n \"id\": \"4545523\"\n }\n }'" }, { "lang": "dotnet", "label": "Add user to group", "source": "await client.Memberships.CreateGroupMembershipAsync(requestBody: new CreateGroupMembershipRequestBody(user: new CreateGroupMembershipRequestBodyUserField(id: user.Id), group: new CreateGroupMembershipRequestBodyGroupField(id: group.Id)));" }, { "lang": "swift", "label": "Add user to group", "source": "try await client.memberships.createGroupMembership(requestBody: CreateGroupMembershipRequestBody(user: CreateGroupMembershipRequestBodyUserField(id: user.id), group: CreateGroupMembershipRequestBodyGroupField(id: group.id)))" }, { "lang": "java", "label": "Add user to group", "source": "client.getMemberships().createGroupMembership(new CreateGroupMembershipRequestBody(new CreateGroupMembershipRequestBodyUserField(user.getId()), new CreateGroupMembershipRequestBodyGroupField(group.getId())))" }, { "lang": "node", "label": "Add user to group", "source": "await client.memberships.createGroupMembership({\n user: { id: user.id } satisfies CreateGroupMembershipRequestBodyUserField,\n group: { id: group.id } satisfies CreateGroupMembershipRequestBodyGroupField,\n} satisfies CreateGroupMembershipRequestBody);" }, { "lang": "python", "label": "Add user to group", "source": "client.memberships.create_group_membership(\n CreateGroupMembershipUser(id=user.id), CreateGroupMembershipGroup(id=group.id)\n)" } ] } }, "/group_memberships/{group_membership_id}": { "get": { "operationId": "get_group_memberships_id", "summary": "Get group membership", "description": "Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API.", "parameters": [ { "name": "group_membership_id", "in": "path", "description": "The ID of the group membership.", "required": true, "schema": { "type": "string" }, "example": "434534" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the group membership object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembership" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "memberships", "tags": [ "Group memberships" ], "x-codeSamples": [ { "lang": "curl", "label": "Get group membership", "source": "curl -i -X GET \"https://api.box.com/2.0/group_memberships/434534\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get group membership", "source": "await client.Memberships.GetGroupMembershipByIdAsync(groupMembershipId: NullableUtils.Unwrap(groupMembership.Id));" }, { "lang": "swift", "label": "Get group membership", "source": "try await client.memberships.getGroupMembershipById(groupMembershipId: groupMembership.id!)" }, { "lang": "java", "label": "Get group membership", "source": "client.getMemberships().getGroupMembershipById(groupMembership.getId())" }, { "lang": "node", "label": "Get group membership", "source": "await client.memberships.getGroupMembershipById(groupMembership.id!);" }, { "lang": "python", "label": "Get group membership", "source": "client.memberships.get_group_membership_by_id(group_membership.id)" } ] }, "put": { "operationId": "put_group_memberships_id", "summary": "Update group membership", "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.", "parameters": [ { "name": "group_membership_id", "in": "path", "description": "The ID of the group membership.", "required": true, "schema": { "type": "string" }, "example": "434534" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "description": "The role of the user in the group.", "type": "string", "example": "member", "enum": [ "member", "admin" ] }, "configurable_permissions": { "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`.\n\nSetting these permissions overwrites the default access levels of an admin.\n\nSpecifying 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.", "type": "object", "example": { "can_run_reports": true }, "additionalProperties": { "type": "boolean", "description": "A key value pair of custom permissions.", "example": true, "x-box-example-key": "can_run_reports" }, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns a new group membership object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMembership" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "memberships", "tags": [ "Group memberships" ], "x-codeSamples": [ { "lang": "curl", "label": "Update group membership", "source": "curl -i -X PUT \"https://api.box.com/2.0/group_memberships/434534\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"role\": \"admin\"\n }'" }, { "lang": "dotnet", "label": "Update group membership", "source": "await client.Memberships.UpdateGroupMembershipByIdAsync(groupMembershipId: NullableUtils.Unwrap(groupMembership.Id), requestBody: new UpdateGroupMembershipByIdRequestBody() { Role = UpdateGroupMembershipByIdRequestBodyRoleField.Admin });" }, { "lang": "swift", "label": "Update group membership", "source": "try await client.memberships.updateGroupMembershipById(groupMembershipId: groupMembership.id!, requestBody: UpdateGroupMembershipByIdRequestBody(role: UpdateGroupMembershipByIdRequestBodyRoleField.admin))" }, { "lang": "java", "label": "Update group membership", "source": "client.getMemberships().updateGroupMembershipById(groupMembership.getId(), new UpdateGroupMembershipByIdRequestBody.Builder().role(UpdateGroupMembershipByIdRequestBodyRoleField.ADMIN).build())" }, { "lang": "node", "label": "Update group membership", "source": "await client.memberships.updateGroupMembershipById(groupMembership.id!, {\n requestBody: {\n role: 'admin' as UpdateGroupMembershipByIdRequestBodyRoleField,\n } satisfies UpdateGroupMembershipByIdRequestBody,\n} satisfies UpdateGroupMembershipByIdOptionalsInput);" }, { "lang": "python", "label": "Update group membership", "source": "client.memberships.update_group_membership_by_id(\n group_membership.id, role=UpdateGroupMembershipByIdRole.ADMIN\n)" } ] }, "delete": { "operationId": "delete_group_memberships_id", "summary": "Remove user from group", "description": "Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API.", "parameters": [ { "name": "group_membership_id", "in": "path", "description": "The ID of the group membership.", "required": true, "schema": { "type": "string" }, "example": "434534" } ], "responses": { "204": { "description": "A blank response is returned if the membership was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "memberships", "tags": [ "Group memberships" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove user from group", "source": "curl -i -X DELETE \"https://api.box.com/2.0/group_memberships/434534\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove user from group", "source": "await client.Memberships.DeleteGroupMembershipByIdAsync(groupMembershipId: NullableUtils.Unwrap(groupMembership.Id));" }, { "lang": "swift", "label": "Remove user from group", "source": "try await client.memberships.deleteGroupMembershipById(groupMembershipId: groupMembership.id!)" }, { "lang": "java", "label": "Remove user from group", "source": "client.getMemberships().deleteGroupMembershipById(groupMembership.getId())" }, { "lang": "node", "label": "Remove user from group", "source": "await client.memberships.deleteGroupMembershipById(groupMembership.id!);" }, { "lang": "python", "label": "Remove user from group", "source": "client.memberships.delete_group_membership_by_id(group_membership.id)" } ] } }, "/webhooks": { "get": { "operationId": "get_webhooks", "summary": "List all webhooks", "description": "Returns all defined webhooks for the requesting application.\n\nThis 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.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhooks" } } } }, "403": { "description": "Returns an error if the application does not have the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "webhooks", "tags": [ "Webhooks" ], "x-codeSamples": [ { "lang": "curl", "label": "List all webhooks", "source": "curl -i -X GET \"https://api.box.com/2.0/webhooks\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List all webhooks", "source": "await client.Webhooks.GetWebhooksAsync();" }, { "lang": "swift", "label": "List all webhooks", "source": "try await client.webhooks.getWebhooks()" }, { "lang": "java", "label": "List all webhooks", "source": "client.getWebhooks().getWebhooks()" }, { "lang": "node", "label": "List all webhooks", "source": "await client.webhooks.getWebhooks();" }, { "lang": "python", "label": "List all webhooks", "source": "client.webhooks.get_webhooks()" } ] }, "post": { "operationId": "post_webhooks", "summary": "Create webhook", "description": "Creates a webhook.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "description": "The item that will trigger the webhook.", "type": "object", "properties": { "id": { "description": "The ID of the item to trigger a webhook.", "type": "string", "example": "1231232" }, "type": { "description": "The type of item to trigger a webhook.", "type": "string", "example": "file", "enum": [ "file", "folder" ] } } }, "address": { "description": "The URL that is notified by this webhook.", "type": "string", "example": "https://example.com/webhooks" }, "triggers": { "description": "An array of event names that this webhook is to be triggered for.", "type": "array", "items": { "title": "Webhook Trigger", "example": "FILE.UPLOADED", "type": "string", "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", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED", "SIGN_REQUEST.SIGN_SIGNER_SIGNED", "SIGN_REQUEST.SIGN_DOCUMENT_CREATED", "SIGN_REQUEST.SIGN_ERROR_FINALIZING" ] }, "example": [ "FILE.UPLOADED" ] } }, "required": [ "target", "triggers", "address" ] } } } }, "responses": { "201": { "description": "Returns the new webhook object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Returns an error if the parameters were incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the application does not have the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the target item could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the a webhook for this combination of target, application, and user already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "webhooks", "tags": [ "Webhooks" ], "x-codeSamples": [ { "lang": "curl", "label": "Create webhook", "source": "curl -i -X POST \"https://api.box.com/2.0/webhooks\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"target\": {\n \"id\": \"21322\",\n \"type\": \"file\"\n },\n \"address\": \"https://example.com/webhooks\",\n \"triggers\": [\n \"FILE.PREVIEWED\"\n ]\n }'" }, { "lang": "dotnet", "label": "Create webhook", "source": "await client.Webhooks.CreateWebhookAsync(requestBody: new CreateWebhookRequestBody(target: new CreateWebhookRequestBodyTargetField() { Id = folder.Id, Type = CreateWebhookRequestBodyTargetTypeField.Folder }, address: \"https://example.com/new-webhook\", triggers: Array.AsReadOnly(new [] {new StringEnum(CreateWebhookRequestBodyTriggersField.FileUploaded)})));" }, { "lang": "swift", "label": "Create webhook", "source": "try await client.webhooks.createWebhook(requestBody: CreateWebhookRequestBody(target: CreateWebhookRequestBodyTargetField(id: folder.id, type: CreateWebhookRequestBodyTargetTypeField.folder), address: \"https://example.com/new-webhook\", triggers: [CreateWebhookRequestBodyTriggersField.fileUploaded]))" }, { "lang": "java", "label": "Create webhook", "source": "client.getWebhooks().createWebhook(new CreateWebhookRequestBody(new CreateWebhookRequestBodyTargetField.Builder().id(folder.getId()).type(CreateWebhookRequestBodyTargetTypeField.FOLDER).build(), \"https://example.com/new-webhook\", Arrays.asList(CreateWebhookRequestBodyTriggersField.FILE_UPLOADED)))" }, { "lang": "node", "label": "Create webhook", "source": "await client.webhooks.createWebhook({\n target: {\n id: folder.id,\n type: 'folder' as CreateWebhookRequestBodyTargetTypeField,\n } satisfies CreateWebhookRequestBodyTargetField,\n address: 'https://example.com/new-webhook',\n triggers: ['FILE.UPLOADED' as CreateWebhookRequestBodyTriggersField],\n} satisfies CreateWebhookRequestBody);" }, { "lang": "python", "label": "Create webhook", "source": "client.webhooks.create_webhook(\n CreateWebhookTarget(id=folder.id, type=CreateWebhookTargetTypeField.FOLDER),\n \"https://example.com/new-webhook\",\n [CreateWebhookTriggers.FILE_UPLOADED],\n)" } ] } }, "/webhooks/{webhook_id}": { "get": { "operationId": "get_webhooks_id", "summary": "Get webhook", "description": "Retrieves a specific webhook.", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The ID of the webhook.", "required": true, "schema": { "type": "string" }, "example": "3321123" } ], "responses": { "200": { "description": "Returns a webhook object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "403": { "description": "Returns an error if the application does not have the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the webhook could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "webhooks", "tags": [ "Webhooks" ], "x-codeSamples": [ { "lang": "curl", "label": "Get webhook", "source": "curl -i -X GET \"https://api.box.com/2.0/webhooks/3321123\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get webhook", "source": "await client.Webhooks.GetWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id));" }, { "lang": "swift", "label": "Get webhook", "source": "try await client.webhooks.getWebhookById(webhookId: webhook.id!)" }, { "lang": "java", "label": "Get webhook", "source": "client.getWebhooks().getWebhookById(webhook.getId())" }, { "lang": "node", "label": "Get webhook", "source": "await client.webhooks.getWebhookById(webhook.id!);" }, { "lang": "python", "label": "Get webhook", "source": "client.webhooks.get_webhook_by_id(webhook.id)" } ] }, "put": { "operationId": "put_webhooks_id", "summary": "Update webhook", "description": "Updates a webhook.", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The ID of the webhook.", "required": true, "schema": { "type": "string" }, "example": "3321123" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "description": "The item that will trigger the webhook.", "type": "object", "properties": { "id": { "description": "The ID of the item to trigger a webhook.", "type": "string", "example": "1231232" }, "type": { "description": "The type of item to trigger a webhook.", "type": "string", "example": "file", "enum": [ "file", "folder" ] } } }, "address": { "description": "The URL that is notified by this webhook.", "type": "string", "example": "https://example.com/webhooks" }, "triggers": { "description": "An array of event names that this webhook is to be triggered for.", "type": "array", "items": { "title": "Webhook Trigger", "example": "FILE.UPLOADED", "type": "string", "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", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED", "SIGN_REQUEST.SIGN_SIGNER_SIGNED", "SIGN_REQUEST.SIGN_DOCUMENT_CREATED", "SIGN_REQUEST.SIGN_ERROR_FINALIZING" ] }, "example": [ "FILE.UPLOADED" ] } } } } } }, "responses": { "200": { "description": "Returns the new webhook object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Returns an error if the parameters were incorrect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if the application does not have the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the target item or webhook could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if the a webhook for this combination of target, application, and user already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "webhooks", "tags": [ "Webhooks" ], "x-codeSamples": [ { "lang": "curl", "label": "Update webhook", "source": "curl -i -X PUT \"https://api.box.com/2.0/webhooks/3321123\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"triggers\": [\n \"FILE.DOWNLOADED\"\n ]\n }'" }, { "lang": "dotnet", "label": "Update webhook", "source": "await client.Webhooks.UpdateWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id), requestBody: new UpdateWebhookByIdRequestBody() { Address = \"https://example.com/updated-webhook\" });" }, { "lang": "swift", "label": "Update webhook", "source": "try await client.webhooks.updateWebhookById(webhookId: webhook.id!, requestBody: UpdateWebhookByIdRequestBody(address: \"https://example.com/updated-webhook\"))" }, { "lang": "java", "label": "Update webhook", "source": "client.getWebhooks().updateWebhookById(webhook.getId(), new UpdateWebhookByIdRequestBody.Builder().address(\"https://example.com/updated-webhook\").build())" }, { "lang": "node", "label": "Update webhook", "source": "await client.webhooks.updateWebhookById(webhook.id!, {\n requestBody: {\n address: 'https://example.com/updated-webhook',\n } satisfies UpdateWebhookByIdRequestBody,\n} satisfies UpdateWebhookByIdOptionalsInput);" }, { "lang": "python", "label": "Update webhook", "source": "client.webhooks.update_webhook_by_id(\n webhook.id, address=\"https://example.com/updated-webhook\"\n)" } ] }, "delete": { "operationId": "delete_webhooks_id", "summary": "Remove webhook", "description": "Deletes a webhook.", "parameters": [ { "name": "webhook_id", "in": "path", "description": "The ID of the webhook.", "required": true, "schema": { "type": "string" }, "example": "3321123" } ], "responses": { "204": { "description": "An empty response will be returned when the webhook was successfully deleted." }, "403": { "description": "Returns an error if the application does not have the permission to manage webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the webhook could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "webhooks", "tags": [ "Webhooks" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove webhook", "source": "curl -i -X DELETE \"https://api.box.com/2.0/webhooks/3321123\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove webhook", "source": "await client.Webhooks.DeleteWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id));" }, { "lang": "swift", "label": "Remove webhook", "source": "try await client.webhooks.deleteWebhookById(webhookId: webhook.id!)" }, { "lang": "java", "label": "Remove webhook", "source": "client.getWebhooks().deleteWebhookById(webhook.getId())" }, { "lang": "node", "label": "Remove webhook", "source": "await client.webhooks.deleteWebhookById(webhook.id!);" }, { "lang": "python", "label": "Remove webhook", "source": "client.webhooks.delete_webhook_by_id(webhook.id)" } ] } }, "/skill_invocations/{skill_id}": { "put": { "operationId": "put_skill_invocations_id", "summary": "Update all Box Skill cards on file", "description": "An alternative method that can be used to overwrite and update all Box Skill metadata cards on a file.", "parameters": [ { "name": "skill_id", "in": "path", "description": "The ID of the skill to apply this metadata for.", "required": true, "schema": { "type": "string" }, "example": "33243242" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Defines the status of this invocation. Set this to `success` when setting Skill cards.", "type": "string", "example": "success", "enum": [ "invoked", "processing", "success", "transient_failure", "permanent_failure" ] }, "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.", "type": "object", "properties": { "cards": { "description": "A list of Box Skill cards to apply to this file.", "type": "array", "items": { "$ref": "#/components/schemas/SkillCard" } } } }, "file": { "description": "The file to assign the cards to.", "type": "object", "properties": { "type": { "description": "The value will always be `file`.", "type": "string", "example": "file", "enum": [ "file" ] }, "id": { "description": "The ID of the file.", "type": "string", "example": "3243244" } } }, "file_version": { "description": "The optional file version to assign the cards to.", "type": "object", "properties": { "type": { "description": "The value will always be `file_version`.", "type": "string", "example": "file_version", "enum": [ "file_version" ] }, "id": { "description": "The ID of the file version.", "type": "string", "example": "731381601045" } } }, "usage": { "description": "A descriptor that defines what items are affected by this call.\n\nSet this to the default values when setting a card to a `success` state, and leave it out in most other situations.", "type": "object", "properties": { "unit": { "description": "The value will always be `file`.", "type": "string", "example": "file" }, "value": { "description": "Number of resources affected.", "type": "number", "example": 1 } } } }, "required": [ "status", "metadata", "file" ] } } } }, "responses": { "200": { "description": "Returns an empty response when the card has been successfully updated." }, "400": { "description": "Returns an error when the request body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the file could not be found or the user does not have access.\n\n- `not_found` - The file could not be found, or the user does not have access to the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "skills", "tags": [ "Skills" ], "x-codeSamples": [ { "lang": "curl", "label": "Update all Box Skill cards on file", "source": "curl -i -X PUT \"https://api.box.com/2.0/skill_invocations/33243242\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"status\": \"success\",\n \"metadata\": {\n \"cards\": [{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"keyword\",\n \"skill_card_title\": {\n \"code\": \"license-plates\",\n \"message\": \"Licence Plates\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"license-plates-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"license-plates-service-123\"\n },\n \"entries\": [\n { \"text\": \"DD-26-YT\" },\n { \"text\": \"DN86 BOX\" }\n ]\n },{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"transcript\",\n \"skill_card_title\": {\n \"code\": \"video-transcription\",\n \"message\": \"Video Transcription\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"video-transcription-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"video-transcription-service-123\"\n },\n \"duration\": 1000,\n \"entries\": [\n {\n \"text\": \"Hi John, have I told you about Box recently?\",\n \"appears\": [{ \"start\": 0 }]\n },\n {\n \"text\": \"No Aaron, you have not. Tell me more!\",\n \"appears\": [{ \"start\": 5 }]\n }\n ]\n },{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"timeline\",\n \"skill_card_title\": {\n \"code\": \"face-detection\",\n \"message\": \"Faces\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"face-detection-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"face-detection-service-123\"\n },\n \"duration\": 1000,\n \"entries\": [\n {\n \"text\": \"John\",\n \"appears\": [{ \"start\": 0, \"end\": 5 }, { \"start\": 10, \"end\": 15 }],\n \"image_url\": \"https://example.com/john.png\"\n },\n {\n \"text\": \"Aaron\",\n \"appears\": [{ \"start\": 5, \"end\": 10 }],\n \"image_url\": \"https://example.com/aaron.png\"\n }\n ]\n },{\n \"type\": \"skill_card\",\n \"skill_card_type\": \"status\",\n \"skill_card_title\": {\n \"code\": \"hold\",\n \"message\": \"Please hold...\"\n },\n \"skill\": {\n \"type\": \"service\",\n \"id\": \"face-detection-service\"\n },\n \"invocation\": {\n \"type\": \"skill_invocation\",\n \"id\": \"face-detection-service-123\"\n },\n \"status\": {\n \"code\": \"processing\",\n \"message\": \"We are processing this file right now.\"\n }\n }]\n },\n \"file\": {\n \"id\": \"12345\"\n },\n \"usage\": {\n \"unit\": \"file\",\n \"value\": 1\n }\n }'" } ] } }, "/events": { "options": { "operationId": "options_events", "summary": "Get events long poll endpoint", "tags": [ "Events" ], "x-box-tag": "events", "description": "Returns a list of real-time servers that can be used for long-polling updates to the [event stream](/reference/get-events).\n\nLong 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.\n\nLong polling the event stream can only be used for user events, not for enterprise events.\n\nTo 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.\n\nWhen 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](/reference/get-events) with the last known `stream_position`.\n\nAfter the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again.\n\nIf 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.\n\nIf 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.\n\nFinally, 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.", "responses": { "200": { "description": "Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealtimeServers" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Get events long poll endpoint", "source": "curl -i -X OPTIONS \"https://api.box.com/2.0/events\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get events long poll endpoint", "source": "await client.Events.GetEventsWithLongPollingAsync();" }, { "lang": "swift", "label": "Get events long poll endpoint", "source": "try await client.events.getEventsWithLongPolling()" }, { "lang": "java", "label": "Get events long poll endpoint", "source": "client.getEvents().getEventsWithLongPolling()" }, { "lang": "node", "label": "Get events long poll endpoint", "source": "await client.events.getEventsWithLongPolling();" }, { "lang": "python", "label": "Get events long poll endpoint", "source": "client.events.get_events_with_long_polling()" } ] }, "get": { "operationId": "get_events", "summary": "List user and enterprise events", "description": "Returns up to a year of past events for a given user or for the entire enterprise.\n\nBy 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.", "parameters": [ { "name": "stream_type", "in": "query", "description": "Defines the type of events that are returned\n\n- `all` returns everything for a user and is the default\n- `changes` returns events that may cause file tree changes such as file updates or collaborations.\n- `sync` is similar to `changes` but only applies to synced folders\n- `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`.\n- `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.", "schema": { "type": "string", "default": "all", "enum": [ "all", "changes", "sync", "admin_logs", "admin_logs_streaming" ] }, "example": "all" }, { "name": "stream_position", "in": "query", "description": "The location in the event stream to start receiving events from.\n\n- `now` will return an empty list events and the latest stream position for initialization.\n- `0` or `null` will return all events.", "schema": { "type": "string" }, "example": "1348790499819" }, { "name": "limit", "in": "query", "description": "Limits the number of events returned.\n\nNote: 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.", "schema": { "type": "integer", "format": "int64", "default": 100, "maximum": 500 }, "example": 50 }, { "name": "event_type", "in": "query", "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.", "schema": { "type": "array", "items": { "type": "string", "description": "An event type that can be filtered by.", "enum": [ "ACCESS_GRANTED", "ACCESS_REVOKED", "ADD_DEVICE_ASSOCIATION", "ADD_LOGIN_ACTIVITY_DEVICE", "ADMIN_LOGIN", "ADVANCED_FOLDER_SETTINGS_UPDATE", "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", "COMMENT_EDIT", "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_PRIMARY", "EMAIL_ALIAS_REMOVE", "EMAIL_UPLOAD_DISABLED", "EMAIL_UPLOAD_ENABLED", "ENTERPRISE_APP_AUTHORIZATION_UPDATE", "EXTERNAL_COLLAB_SECURITY_SETTINGS", "FAILED_LOGIN", "FAVORITE", "FILE_MARKED_MALICIOUS", "FILE_REQUEST_CREATE", "FILE_REQUEST_DELETE", "FILE_REQUEST_UPDATE", "FILE_VERSION_RESTORE", "FILE_WATERMARKED_DOWNLOAD", "GROUP_ADD_ITEM", "GROUP_ADD_USER", "GROUP_CREATION", "GROUP_DELETION", "GROUP_EDITED", "GROUP_REMOVE_ITEM", "GROUP_REMOVE_USER", "ILLEGAL_ITEM_OWNERSHIP_TRANSFER_BY_USER", "ITEM_EMAIL_SEND", "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_CASCADE_POLICY_APPLY", "METADATA_CASCADE_POLICY_CREATE", "METADATA_INSTANCE_COPY", "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", "OAUTH2_REFRESH_TOKEN_REVOKE", "PREVIEW", "REMOVE_DEVICE_ASSOCIATION", "REMOVE_LOGIN_ACTIVITY_DEVICE", "RENAME", "RETENTION_POLICY_ASSIGNMENT_ADD", "SHARE", "SHARED_LINK_SEND", "SHARE_EXPIRATION", "SHIELD_ALERT", "SHIELD_DOWNLOAD_BLOCKED", "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", "SHIELD_PREVIEW_BLOCKED", "SHIELD_SHARED_LINK_ACCESS_BLOCKED", "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE", "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE", "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", "UNFAVORITE", "UNLOCK", "UNSHARE", "UPDATE_COLLABORATION_EXPIRATION", "UPDATE_SHARE_EXPIRATION", "UPLOAD", "USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE", "WATERMARK_LABEL_CREATE", "WATERMARK_LABEL_DELETE", "WORKFLOW_AUTOMATION_CREATE", "WORKFLOW_AUTOMATION_DELETE", "WORKFLOW_AUTOMATION_UPDATE" ] } }, "example": [ "ACCESS_GRANTED" ], "explode": false }, { "name": "created_after", "in": "query", "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.", "schema": { "type": "string", "format": "date-time" }, "example": "2012-12-12T10:53:43-08:00" }, { "name": "created_before", "in": "query", "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.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2013-12-12T10:53:43-08:00" } ], "responses": { "200": { "description": "Returns a list of event objects.\n\nEvents 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Events" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "events", "tags": [ "Events" ], "x-codeSamples": [ { "lang": "curl", "label": "List user and enterprise events", "source": "curl -i -X GET \"https://api.box.com/2.0/events\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List user and enterprise events", "source": "await client.Events.GetEventsAsync();" }, { "lang": "swift", "label": "List user and enterprise events", "source": "try await client.events.getEvents()" }, { "lang": "java", "label": "List user and enterprise events", "source": "client.getEvents().getEvents()" }, { "lang": "node", "label": "List user and enterprise events", "source": "await client.events.getEvents();" }, { "lang": "python", "label": "List user and enterprise events", "source": "client.events.get_events()" } ] } }, "/collections": { "get": { "operationId": "get_collections", "summary": "List all collections", "description": "Retrieves all collections for a given user.\n\nCurrently, only the `favorites` collection is supported.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns all collections for the given user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collections" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collections", "tags": [ "Collections" ], "x-codeSamples": [ { "lang": "curl", "label": "List all collections", "source": "curl -i -X GET \"https://api.box.com/2.0/collections\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List all collections", "source": "await client.Collections.GetCollectionsAsync();" }, { "lang": "swift", "label": "List all collections", "source": "try await client.collections.getCollections()" }, { "lang": "node", "label": "List all collections", "source": "await client.collections.getCollections();" }, { "lang": "python", "label": "List all collections", "source": "client.collections.get_collections()" } ] } }, "/collections/{collection_id}/items": { "get": { "operationId": "get_collections_id_items", "summary": "List collection items", "description": "Retrieves the files and/or folders contained within this collection.", "parameters": [ { "name": "collection_id", "in": "path", "description": "The ID of the collection.", "required": true, "schema": { "type": "string" }, "example": "926489" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "offset", "in": "query", "description": "The offset of the item at which to begin the response.\n\nQueries with offset parameter value exceeding 10000 will be rejected with a 400 response.", "required": false, "schema": { "type": "integer", "format": "int64", "default": 0 }, "example": 1000 }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns an array of items in the collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemsOffsetPaginated" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collections", "tags": [ "Collections" ], "x-codeSamples": [ { "lang": "curl", "label": "List collection items", "source": "curl -i -X GET \"https://api.box.com/2.0/collections/926489/items\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List collection items", "source": "await client.Collections.GetCollectionItemsAsync(collectionId: NullableUtils.Unwrap(favouriteCollection.Id));" }, { "lang": "swift", "label": "List collection items", "source": "try await client.collections.getCollectionItems(collectionId: favouriteCollection.id!)" }, { "lang": "node", "label": "List collection items", "source": "await client.collections.getCollectionItems(favouriteCollection.id!);" }, { "lang": "python", "label": "List collection items", "source": "client.collections.get_collection_items(favourite_collection.id)" } ] } }, "/collections/{collection_id}": { "get": { "operationId": "get_collections_id", "summary": "Get collection by ID", "description": "Retrieves a collection by its ID.", "parameters": [ { "name": "collection_id", "in": "path", "description": "The ID of the collection.", "required": true, "schema": { "type": "string" }, "example": "926489" } ], "responses": { "200": { "description": "Returns an array of items in the collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collections", "tags": [ "Collections" ], "x-codeSamples": [ { "lang": "curl", "label": "Get collection by ID", "source": "curl -i -X GET \"https://api.box.com/2.0/collections/926489\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get collection by ID", "source": "await client.Collections.GetCollectionByIdAsync(collectionId: NullableUtils.Unwrap(NullableUtils.Unwrap(collections.Entries)[0].Id));" }, { "lang": "swift", "label": "Get collection by ID", "source": "try await client.collections.getCollectionById(collectionId: collections.entries![0].id!)" }, { "lang": "node", "label": "Get collection by ID", "source": "await client.collections.getCollectionById(collections.entries![0].id!);" }, { "lang": "python", "label": "Get collection by ID", "source": "client.collections.get_collection_by_id(collections.entries[0].id)" } ] } }, "/recent_items": { "get": { "operationId": "get_recent_items", "summary": "List recently accessed items", "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.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { "200": { "description": "Returns a list recent items access by a user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentItems" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "recent_items", "tags": [ "Recent items" ], "x-codeSamples": [ { "lang": "curl", "label": "List recently accessed items", "source": "curl -i -X GET \"https://api.box.com/2.0/recent_items\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List recently accessed items", "source": "await client.RecentItems.GetRecentItemsAsync();" }, { "lang": "swift", "label": "List recently accessed items", "source": "try await client.recentItems.getRecentItems()" }, { "lang": "java", "label": "List recently accessed items", "source": "client.getRecentItems().getRecentItems()" }, { "lang": "node", "label": "List recently accessed items", "source": "await client.recentItems.getRecentItems();" }, { "lang": "python", "label": "List recently accessed items", "source": "client.recent_items.get_recent_items()" } ] } }, "/retention_policies": { "get": { "operationId": "get_retention_policies", "summary": "List retention policies", "description": "Retrieves all of the retention policies for an enterprise.", "parameters": [ { "name": "policy_name", "in": "query", "description": "Filters results by a case sensitive prefix of the name of retention policies.", "required": false, "schema": { "type": "string" }, "example": "Sales Policy" }, { "name": "policy_type", "in": "query", "description": "Filters results by the type of retention policy.", "required": false, "schema": { "type": "string", "enum": [ "finite", "indefinite" ] }, "example": "finite" }, { "name": "created_by_user_id", "in": "query", "description": "Filters results by the ID of the user who created policy.", "required": false, "schema": { "type": "string" }, "example": "21312321" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { "200": { "description": "Returns a list retention policies in the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicies" } } } }, "400": { "description": "Returns a `bad_request` if a non existent `policy_type` was specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the user specified in `created_by_user_id` does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policies", "tags": [ "Retention policies" ], "x-codeSamples": [ { "lang": "curl", "label": "List retention policies", "source": "curl -i -X GET \"https://api.box.com/2.0/retention_policies\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List retention policies", "source": "await client.RetentionPolicies.GetRetentionPoliciesAsync();" }, { "lang": "swift", "label": "List retention policies", "source": "try await client.retentionPolicies.getRetentionPolicies()" }, { "lang": "java", "label": "List retention policies", "source": "client.getRetentionPolicies().getRetentionPolicies()" }, { "lang": "node", "label": "List retention policies", "source": "await client.retentionPolicies.getRetentionPolicies();" }, { "lang": "python", "label": "List retention policies", "source": "client.retention_policies.get_retention_policies()" } ] }, "post": { "operationId": "post_retention_policies", "summary": "Create retention policy", "description": "Creates a retention policy.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_name": { "description": "The name for the retention policy.", "type": "string", "example": "Some Policy Name" }, "description": { "description": "The additional text description of the retention policy.", "type": "string", "example": "Policy to retain all reports for at least one month" }, "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.", "type": "string", "example": "finite", "enum": [ "finite", "indefinite" ] }, "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.", "type": "string", "example": "permanently_delete", "enum": [ "permanently_delete", "remove_retention" ] }, "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", "oneOf": [ { "type": "string", "format": "int32", "nullable": true }, { "type": "number", "format": "int32", "nullable": false } ] }, "retention_type": { "description": "Specifies the retention type:\n\n- `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.\n\n- `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.", "type": "string", "example": "modifiable", "enum": [ "modifiable", "non_modifiable" ] }, "can_owner_extend_retention": { "description": "Whether the owner of a file will be allowed to extend the retention.", "type": "boolean", "example": true }, "max_extension_length": { "$ref": "#/components/schemas/RetentionPolicyMaxExtensionLengthRequest" }, "are_owners_notified": { "description": "Whether owner and co-owners of a file are notified when the policy nears expiration.", "type": "boolean", "example": true }, "custom_notification_recipients": { "description": "A list of users notified when the retention policy duration is about to end.", "type": "array", "items": { "$ref": "#/components/schemas/User--Mini" } } }, "required": [ "policy_name", "policy_type", "disposition_action" ] } } } }, "responses": { "201": { "description": "Returns a new retention policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } }, "400": { "description": "Returns a `bad_request` error when the `retention_length` was specified for an `indefinite` retention policy, an incorrect `disposition_action` was set, `max_extension_length` is not allowed for the given policy type or disposition action, or description exceeds maximum length of 500 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a retention policy with the given name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policies", "tags": [ "Retention policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Create retention policy", "source": "curl -i -X POST \"https://api.box.com/2.0/retention_policies\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"policy_name\": \"Some Policy Name\",\n \"policy_type\": \"finite\",\n \"retention_length\": 365,\n \"disposition_action\": \"permanently_delete\"\n }'" }, { "lang": "dotnet", "label": "Create retention policy", "source": "await client.RetentionPolicies.CreateRetentionPolicyAsync(requestBody: new CreateRetentionPolicyRequestBody(policyName: retentionPolicyName, policyType: CreateRetentionPolicyRequestBodyPolicyTypeField.Finite, dispositionAction: CreateRetentionPolicyRequestBodyDispositionActionField.RemoveRetention) { AreOwnersNotified = true, CanOwnerExtendRetention = true, Description = retentionDescription, RetentionLength = \"1\", RetentionType = CreateRetentionPolicyRequestBodyRetentionTypeField.Modifiable });" }, { "lang": "swift", "label": "Create retention policy", "source": "try await client.retentionPolicies.createRetentionPolicy(requestBody: CreateRetentionPolicyRequestBody(policyName: retentionPolicyName, policyType: CreateRetentionPolicyRequestBodyPolicyTypeField.finite, areOwnersNotified: true, canOwnerExtendRetention: true, description: retentionDescription, dispositionAction: CreateRetentionPolicyRequestBodyDispositionActionField.removeRetention, retentionLength: .string(\"1\"), retentionType: CreateRetentionPolicyRequestBodyRetentionTypeField.modifiable))" }, { "lang": "java", "label": "Create retention policy", "source": "client.getRetentionPolicies().createRetentionPolicy(new CreateRetentionPolicyRequestBody.Builder(retentionPolicyName, CreateRetentionPolicyRequestBodyPolicyTypeField.FINITE, CreateRetentionPolicyRequestBodyDispositionActionField.REMOVE_RETENTION).description(retentionDescription).retentionLength(\"1\").retentionType(CreateRetentionPolicyRequestBodyRetentionTypeField.MODIFIABLE).canOwnerExtendRetention(true).areOwnersNotified(true).build())" }, { "lang": "node", "label": "Create retention policy", "source": "await client.retentionPolicies.createRetentionPolicy({\n policyName: retentionPolicyName,\n policyType: 'finite' as CreateRetentionPolicyRequestBodyPolicyTypeField,\n areOwnersNotified: true,\n canOwnerExtendRetention: true,\n description: retentionDescription,\n dispositionAction:\n 'remove_retention' as CreateRetentionPolicyRequestBodyDispositionActionField,\n retentionLength: '1',\n retentionType:\n 'modifiable' as CreateRetentionPolicyRequestBodyRetentionTypeField,\n} satisfies CreateRetentionPolicyRequestBody);" }, { "lang": "python", "label": "Create retention policy", "source": "client.retention_policies.create_retention_policy(\n retention_policy_name,\n CreateRetentionPolicyPolicyType.FINITE,\n CreateRetentionPolicyDispositionAction.REMOVE_RETENTION,\n description=retention_description,\n retention_length=\"1\",\n retention_type=CreateRetentionPolicyRetentionType.MODIFIABLE,\n can_owner_extend_retention=True,\n are_owners_notified=True,\n)" } ] } }, "/retention_policies/{retention_policy_id}": { "get": { "operationId": "get_retention_policies_id", "summary": "Get retention policy", "description": "Retrieves a retention policy.", "parameters": [ { "name": "retention_policy_id", "in": "path", "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" }, "example": "982312" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the retention policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policies", "tags": [ "Retention policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Get retention policy", "source": "curl -i -X GET \"https://api.box.com/2.0/retention_policies/982312\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get retention policy", "source": "await client.RetentionPolicies.GetRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id);" }, { "lang": "swift", "label": "Get retention policy", "source": "try await client.retentionPolicies.getRetentionPolicyById(retentionPolicyId: retentionPolicy.id)" }, { "lang": "java", "label": "Get retention policy", "source": "client.getRetentionPolicies().getRetentionPolicyById(retentionPolicy.getId())" }, { "lang": "node", "label": "Get retention policy", "source": "await client.retentionPolicies.getRetentionPolicyById(retentionPolicy.id);" }, { "lang": "python", "label": "Get retention policy", "source": "client.retention_policies.get_retention_policy_by_id(retention_policy.id)" } ] }, "put": { "operationId": "put_retention_policies_id", "summary": "Update retention policy", "description": "Updates a retention policy.", "parameters": [ { "name": "retention_policy_id", "in": "path", "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" }, "example": "982312" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_name": { "description": "The name for the retention policy.", "type": "string", "example": "Some Policy Name", "nullable": true }, "description": { "description": "The additional text description of the retention policy.", "type": "string", "example": "Policy to retain all reports for at least one month", "nullable": true }, "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. You can use `null` if you don't want to change `disposition_action`.", "example": "permanently_delete", "anyOf": [ { "type": "string", "enum": [ "permanently_delete", "remove_retention" ] }, { "type": "string", "pattern": ".^", "nullable": true } ] }, "retention_type": { "description": "Specifies the retention type:\n\n- `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.\n- `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.\n\nWhen 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.", "type": "string", "example": "non-modifiable", "nullable": true }, "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", "oneOf": [ { "type": "string", "format": "int32", "nullable": true }, { "type": "number", "format": "int32", "nullable": false } ] }, "status": { "description": "Used to retire a retention policy.\n\nIf not retiring a policy, do not include this parameter or set it to `null`.", "type": "string", "example": "retired", "nullable": true }, "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.", "type": "boolean", "example": false, "nullable": true }, "max_extension_length": { "$ref": "#/components/schemas/RetentionPolicyMaxExtensionLengthRequest" }, "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.", "type": "boolean", "example": false, "nullable": true }, "custom_notification_recipients": { "description": "A list of users notified when the retention duration is about to end.", "type": "array", "items": { "$ref": "#/components/schemas/User--Base" }, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns the updated retention policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicy" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect `disposition_action` was set, `max_extension_length` is not allowed for the given policy type or disposition action, or description exceeds maximum length of 500 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a retention policy with the given name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policies", "tags": [ "Retention policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Update retention policy", "source": "curl -i -X PUT \"https://api.box.com/2.0/retention_policies/982312\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"disposition_action\": \"permanently_delete\"\n }'" }, { "lang": "dotnet", "label": "Update retention policy", "source": "await client.RetentionPolicies.UpdateRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id, requestBody: new UpdateRetentionPolicyByIdRequestBody() { PolicyName = updatedRetentionPolicyName });" }, { "lang": "swift", "label": "Update retention policy", "source": "try await client.retentionPolicies.updateRetentionPolicyById(retentionPolicyId: retentionPolicy.id, requestBody: UpdateRetentionPolicyByIdRequestBody(policyName: updatedRetentionPolicyName))" }, { "lang": "java", "label": "Update retention policy", "source": "client.getRetentionPolicies().updateRetentionPolicyById(retentionPolicy.getId(), new UpdateRetentionPolicyByIdRequestBody.Builder().policyName(updatedRetentionPolicyName).build())" }, { "lang": "node", "label": "Update retention policy", "source": "await client.retentionPolicies.updateRetentionPolicyById(retentionPolicy.id, {\n requestBody: {\n policyName: updatedRetentionPolicyName,\n } satisfies UpdateRetentionPolicyByIdRequestBody,\n} satisfies UpdateRetentionPolicyByIdOptionalsInput);" }, { "lang": "python", "label": "Update retention policy", "source": "client.retention_policies.update_retention_policy_by_id(\n retention_policy.id, policy_name=updated_retention_policy_name\n)" } ] }, "delete": { "operationId": "delete_retention_policies_id", "summary": "Delete retention policy", "description": "Permanently deletes a retention policy.", "parameters": [ { "name": "retention_policy_id", "in": "path", "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" }, "example": "982312" } ], "responses": { "204": { "description": "Returns an empty response when the policy has been deleted." }, "403": { "description": "Returns an error if the policy is non-modifiable or the user does not have the required access to perform the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the policy is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policies", "tags": [ "Retention policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete retention policy", "source": "curl -i -X DELETE \"https://api.box.com/2.0/retention_policies/982312\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete retention policy", "source": "await client.RetentionPolicies.DeleteRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id);" }, { "lang": "swift", "label": "Delete retention policy", "source": "try await client.retentionPolicies.deleteRetentionPolicyById(retentionPolicyId: retentionPolicy.id)" }, { "lang": "java", "label": "Delete retention policy", "source": "client.getRetentionPolicies().deleteRetentionPolicyById(retentionPolicy.getId())" }, { "lang": "node", "label": "Delete retention policy", "source": "await client.retentionPolicies.deleteRetentionPolicyById(retentionPolicy.id);" }, { "lang": "python", "label": "Delete retention policy", "source": "client.retention_policies.delete_retention_policy_by_id(retention_policy.id)" } ] } }, "/retention_policies/{retention_policy_id}/assignments": { "get": { "operationId": "get_retention_policies_id_assignments", "summary": "List retention policy assignments", "description": "Returns a list of all retention policy assignments associated with a specified retention policy.", "parameters": [ { "name": "retention_policy_id", "in": "path", "description": "The ID of the retention policy.", "required": true, "schema": { "type": "string" }, "example": "982312" }, { "name": "type", "in": "query", "description": "The type of the retention policy assignment to retrieve.", "required": false, "schema": { "type": "string", "enum": [ "folder", "enterprise", "metadata_template" ] }, "example": "metadata_template" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of the retention policy assignments associated with the specified retention policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyAssignments" } } } }, "400": { "description": "Returns an error if an unknown `type` is specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policy_assignments", "tags": [ "Retention policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "List retention policy assignments", "source": "curl -i -X GET \"https://api.box.com/2.0/retention_policies/982312/assignments\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List retention policy assignments", "source": "await client.RetentionPolicyAssignments.GetRetentionPolicyAssignmentsAsync(retentionPolicyId: retentionPolicy.Id);" }, { "lang": "swift", "label": "List retention policy assignments", "source": "try await client.retentionPolicyAssignments.getRetentionPolicyAssignments(retentionPolicyId: retentionPolicy.id)" }, { "lang": "java", "label": "List retention policy assignments", "source": "client.getRetentionPolicyAssignments().getRetentionPolicyAssignments(retentionPolicy.getId())" }, { "lang": "node", "label": "List retention policy assignments", "source": "await client.retentionPolicyAssignments.getRetentionPolicyAssignments(\n retentionPolicy.id,\n);" }, { "lang": "python", "label": "List retention policy assignments", "source": "client.retention_policy_assignments.get_retention_policy_assignments(\n retention_policy.id\n)" } ] } }, "/retention_policy_assignments": { "post": { "operationId": "post_retention_policy_assignments", "summary": "Assign retention policy", "description": "Assigns a retention policy to an item.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "description": "The ID of the retention policy to assign.", "type": "string", "example": "173463" }, "assign_to": { "description": "The item to assign the policy to.", "type": "object", "properties": { "type": { "description": "The type of item to assign the policy to.", "type": "string", "example": "metadata_template", "enum": [ "enterprise", "folder", "metadata_template" ] }, "id": { "description": "The ID of item to assign the policy to. Set to `null` or omit when `type` is set to `enterprise`.", "type": "string", "example": "6564564", "nullable": true } }, "required": [ "type" ] }, "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.", "type": "array", "items": { "type": "object", "properties": { "field": { "description": "The metadata attribute key id.", "type": "string", "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4" }, "value": { "description": "The metadata attribute field id. For value, only enum and multiselect types are supported.", "type": "string", "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e" } } } }, "start_date_field": { "description": "The date the retention policy assignment begins.\n\nIf the `assigned_to` type is `metadata_template`, this field can be a date field's metadata attribute key id.", "type": "string", "example": "upload_date" } }, "required": [ "policy_id", "assign_to" ] } } } }, "responses": { "201": { "description": "Returns a new retention policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyAssignment" } } } }, "400": { "description": "Returns an error if an `id` is specified while assigning the retention policy to an enterprise.\n\nReturns an error if `start_date_field` is present but `assign_to.type` is not `metadata_template`\n\nReturns an error if `start_date_field` is present, but belongs to a different metadata template than the one specified in `assign_to.id`\n\nReturns an error if `start_date_field` is present, but the `retention_policy` has a `retention_length` of \"indefinite\"\n\nReturns an error if `start_date_field` is present, but cannot be resolved to a valid metadata date field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if no retention policy with the given `policy_id` exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a retention policy of equal or greater length has already been assigned to this item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policy_assignments", "tags": [ "Retention policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Assign retention policy", "source": "curl -i -X POST \"https://api.box.com/2.0/retention_policy_assignments\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"policy_id\": \"173463\",\n \"assign_to\": {\n \"type\": \"folder\",\n \"id\": \"6564564\"\n }\n }'" }, { "lang": "dotnet", "label": "Assign retention policy", "source": "await client.RetentionPolicyAssignments.CreateRetentionPolicyAssignmentAsync(requestBody: new CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.Id, assignTo: new CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.Folder) { Id = folder.Id }));" }, { "lang": "swift", "label": "Assign retention policy", "source": "try await client.retentionPolicyAssignments.createRetentionPolicyAssignment(requestBody: CreateRetentionPolicyAssignmentRequestBody(policyId: retentionPolicy.id, assignTo: CreateRetentionPolicyAssignmentRequestBodyAssignToField(type: CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.folder, id: folder.id)))" }, { "lang": "java", "label": "Assign retention policy", "source": "client.getRetentionPolicyAssignments().createRetentionPolicyAssignment(new CreateRetentionPolicyAssignmentRequestBody(retentionPolicy.getId(), new CreateRetentionPolicyAssignmentRequestBodyAssignToField.Builder(CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField.FOLDER).id(folder.getId()).build()))" }, { "lang": "node", "label": "Assign retention policy", "source": "await client.retentionPolicyAssignments.createRetentionPolicyAssignment({\n policyId: retentionPolicy.id,\n assignTo: {\n type: 'folder' as CreateRetentionPolicyAssignmentRequestBodyAssignToTypeField,\n id: folder.id,\n } satisfies CreateRetentionPolicyAssignmentRequestBodyAssignToField,\n} satisfies CreateRetentionPolicyAssignmentRequestBody);" }, { "lang": "python", "label": "Assign retention policy", "source": "client.retention_policy_assignments.create_retention_policy_assignment(\n retention_policy.id,\n CreateRetentionPolicyAssignmentAssignTo(\n type=CreateRetentionPolicyAssignmentAssignToTypeField.FOLDER, id=folder.id\n ),\n)" } ] } }, "/retention_policy_assignments/{retention_policy_assignment_id}": { "get": { "operationId": "get_retention_policy_assignments_id", "summary": "Get retention policy assignment", "description": "Retrieves a retention policy assignment.", "parameters": [ { "name": "retention_policy_assignment_id", "in": "path", "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" }, "example": "1233123" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the retention policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionPolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policy_assignments", "tags": [ "Retention policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get retention policy assignment", "source": "curl -i -X GET \"https://api.box.com/2.0/retention_policy_assignments/1233123\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get retention policy assignment", "source": "await client.RetentionPolicyAssignments.GetRetentionPolicyAssignmentByIdAsync(retentionPolicyAssignmentId: retentionPolicyAssignment.Id);" }, { "lang": "swift", "label": "Get retention policy assignment", "source": "try await client.retentionPolicyAssignments.getRetentionPolicyAssignmentById(retentionPolicyAssignmentId: retentionPolicyAssignment.id)" }, { "lang": "java", "label": "Get retention policy assignment", "source": "client.getRetentionPolicyAssignments().getRetentionPolicyAssignmentById(retentionPolicyAssignment.getId())" }, { "lang": "node", "label": "Get retention policy assignment", "source": "await client.retentionPolicyAssignments.getRetentionPolicyAssignmentById(\n retentionPolicyAssignment.id,\n);" }, { "lang": "python", "label": "Get retention policy assignment", "source": "client.retention_policy_assignments.get_retention_policy_assignment_by_id(\n retention_policy_assignment.id\n)" } ] }, "delete": { "operationId": "delete_retention_policy_assignments_id", "summary": "Remove retention policy assignment", "description": "Removes a retention policy assignment applied to content.", "parameters": [ { "name": "retention_policy_assignment_id", "in": "path", "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" }, "example": "1233123" } ], "responses": { "204": { "description": "Returns an empty response when the policy assignment is successfully deleted." }, "403": { "description": "Returns an error when the assignment relates to a retention policy that cannot be modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when the retention policy assignment does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policy_assignments", "tags": [ "Retention policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove retention policy assignment", "source": "curl -i -X DELETE \"https://api.box.com/2.0/retention_policy_assignments/1233123\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove retention policy assignment", "source": "await client.RetentionPolicyAssignments.DeleteRetentionPolicyAssignmentByIdAsync(retentionPolicyAssignmentId: retentionPolicyAssignment.Id);" }, { "lang": "swift", "label": "Remove retention policy assignment", "source": "try await client.retentionPolicyAssignments.deleteRetentionPolicyAssignmentById(retentionPolicyAssignmentId: retentionPolicyAssignment.id)" }, { "lang": "java", "label": "Remove retention policy assignment", "source": "client.getRetentionPolicyAssignments().deleteRetentionPolicyAssignmentById(retentionPolicyAssignment.getId())" }, { "lang": "node", "label": "Remove retention policy assignment", "source": "await client.retentionPolicyAssignments.deleteRetentionPolicyAssignmentById(\n retentionPolicyAssignment.id,\n);" }, { "lang": "python", "label": "Remove retention policy assignment", "source": "client.retention_policy_assignments.delete_retention_policy_assignment_by_id(\n retention_policy_assignment.id\n)" } ] } }, "/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention": { "get": { "operationId": "get_retention_policy_assignments_id_files_under_retention", "summary": "Get files under retention", "description": "Returns a list of files under retention for a retention policy assignment.", "parameters": [ { "name": "retention_policy_assignment_id", "in": "path", "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" }, "example": "1233123" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of files under retention that are associated with the specified retention policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesUnderRetention" } } } }, "400": { "description": "Returns an error if `retention_policy_assignment_id` is not specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policy_assignments", "tags": [ "Retention policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get files under retention", "source": "curl -i -X GET \"https://app.box.com/api/2.0/retention_policy_assignments/3424234/files_under_retention\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get files under retention", "source": "await client.RetentionPolicyAssignments.GetFilesUnderRetentionPolicyAssignmentAsync(retentionPolicyAssignmentId: retentionPolicyAssignment.Id);" }, { "lang": "swift", "label": "Get files under retention", "source": "try await client.retentionPolicyAssignments.getFilesUnderRetentionPolicyAssignment(retentionPolicyAssignmentId: retentionPolicyAssignment.id)" }, { "lang": "java", "label": "Get files under retention", "source": "client.getRetentionPolicyAssignments().getFilesUnderRetentionPolicyAssignment(retentionPolicyAssignment.getId())" }, { "lang": "node", "label": "Get files under retention", "source": "await client.retentionPolicyAssignments.getFilesUnderRetentionPolicyAssignment(\n retentionPolicyAssignment.id,\n);" }, { "lang": "python", "label": "Get files under retention", "source": "client.retention_policy_assignments.get_files_under_retention_policy_assignment(\n retention_policy_assignment.id\n)" } ] } }, "/retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention": { "get": { "operationId": "get_retention_policy_assignments_id_file_versions_under_retention", "summary": "Get file versions under retention", "description": "Returns a list of file versions under retention for a retention policy assignment.", "parameters": [ { "name": "retention_policy_assignment_id", "in": "path", "description": "The ID of the retention policy assignment.", "required": true, "schema": { "type": "string" }, "example": "1233123" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of file versions under retention that are associated with the specified retention policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesUnderRetention" } } } }, "400": { "description": "Returns an error if `retention_policy_assignment_id` is not specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "retention_policy_assignments", "tags": [ "Retention policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get file versions under retention", "source": "curl -i -X GET \"https://app.box.com/api/2.0/retention_policy_assignments/3424234/file_versions_under_retention\" \\\n -H \"authorization: Bearer \"" } ] } }, "/legal_hold_policies": { "get": { "operationId": "get_legal_hold_policies", "summary": "List all legal hold policies", "description": "Retrieves a list of legal hold policies that belong to an enterprise.", "parameters": [ { "name": "policy_name", "in": "query", "description": "Limits results to policies for which the names start with this search term. This is a case-insensitive prefix.", "required": false, "schema": { "type": "string" }, "example": "Sales Policy" }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of legal hold policies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicies" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policies", "tags": [ "Legal hold policies" ], "x-codeSamples": [ { "lang": "curl", "label": "List all legal hold policies", "source": "curl -i -X GET \"https://api.box.com/2.0/legal_hold_policies\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List all legal hold policies", "source": "await client.LegalHoldPolicies.GetLegalHoldPoliciesAsync();" }, { "lang": "swift", "label": "List all legal hold policies", "source": "try await client.legalHoldPolicies.getLegalHoldPolicies()" }, { "lang": "java", "label": "List all legal hold policies", "source": "client.getLegalHoldPolicies().getLegalHoldPolicies()" }, { "lang": "node", "label": "List all legal hold policies", "source": "await client.legalHoldPolicies.getLegalHoldPolicies();" }, { "lang": "python", "label": "List all legal hold policies", "source": "client.legal_hold_policies.get_legal_hold_policies()" } ] }, "post": { "operationId": "post_legal_hold_policies", "summary": "Create legal hold policy", "description": "Create a new legal hold policy.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_name": { "description": "The name of the policy.", "type": "string", "example": "Sales Policy", "maxLength": 254 }, "description": { "description": "A description for the policy.", "type": "string", "example": "A custom policy for the sales team", "maxLength": 500 }, "filter_started_at": { "description": "The filter start date.\n\nWhen 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.\n\nRequired if `is_ongoing` is set to `false`.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "maxLength": 500 }, "filter_ended_at": { "description": "The filter end date.\n\nWhen 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.\n\nRequired if `is_ongoing` is set to `false`.", "type": "string", "format": "date-time", "example": "2012-12-18T10:53:43-08:00", "maxLength": 500 }, "is_ongoing": { "description": "Whether new assignments under this policy should continue applying to files even after initialization.\n\nWhen 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.\n\nFor 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.\n\nRequired if no filter dates are set.", "type": "boolean", "example": true } }, "required": [ "policy_name" ] } } } }, "responses": { "201": { "description": "Returns a new legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicy" } } } }, "400": { "description": "Returns an error if required parameters are missing, or neither `is_ongoing` or filter dates are specified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if a policy with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policies", "tags": [ "Legal hold policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Create legal hold policy", "source": "curl -i -X POST \"https://api.box.com/2.0/legal_hold_policies\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"policy_name\": \"Policy 3\",\n \"description\": \"Automatic created policy\"\n }'" }, { "lang": "dotnet", "label": "Create legal hold policy", "source": "await client.LegalHoldPolicies.CreateLegalHoldPolicyAsync(requestBody: new CreateLegalHoldPolicyRequestBody(policyName: legalHoldPolicyName) { Description = legalHoldDescription, IsOngoing = false, FilterStartedAt = filterStartedAt, FilterEndedAt = filterEndedAt });" }, { "lang": "swift", "label": "Create legal hold policy", "source": "try await client.legalHoldPolicies.createLegalHoldPolicy(requestBody: CreateLegalHoldPolicyRequestBody(policyName: legalHoldPolicyName, description: legalHoldDescription, isOngoing: false, filterStartedAt: filterStartedAt, filterEndedAt: filterEndedAt))" }, { "lang": "java", "label": "Create legal hold policy", "source": "client.getLegalHoldPolicies().createLegalHoldPolicy(new CreateLegalHoldPolicyRequestBody.Builder(legalHoldPolicyName).description(legalHoldDescription).filterStartedAt(filterStartedAt).filterEndedAt(filterEndedAt).isOngoing(false).build())" }, { "lang": "node", "label": "Create legal hold policy", "source": "await client.legalHoldPolicies.createLegalHoldPolicy({\n policyName: legalHoldPolicyName,\n description: legalHoldDescription,\n isOngoing: false,\n filterStartedAt: filterStartedAt,\n filterEndedAt: filterEndedAt,\n} satisfies CreateLegalHoldPolicyRequestBody);" }, { "lang": "python", "label": "Create legal hold policy", "source": "client.legal_hold_policies.create_legal_hold_policy(\n legal_hold_policy_name,\n description=legal_hold_description,\n filter_started_at=filter_started_at,\n filter_ended_at=filter_ended_at,\n is_ongoing=False,\n)" } ] } }, "/legal_hold_policies/{legal_hold_policy_id}": { "get": { "operationId": "get_legal_hold_policies_id", "summary": "Get legal hold policy", "description": "Retrieve a legal hold policy.", "parameters": [ { "name": "legal_hold_policy_id", "in": "path", "description": "The ID of the legal hold policy.", "required": true, "schema": { "type": "string" }, "example": "324432" } ], "responses": { "200": { "description": "Returns a legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicy" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policies", "tags": [ "Legal hold policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Get legal hold policy", "source": "curl -i -X GET \"https://api.box.com/2.0/legal_hold_policies/324432\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get legal hold policy", "source": "await client.LegalHoldPolicies.GetLegalHoldPolicyByIdAsync(legalHoldPolicyId: legalHoldPolicyId);" }, { "lang": "swift", "label": "Get legal hold policy", "source": "try await client.legalHoldPolicies.getLegalHoldPolicyById(legalHoldPolicyId: legalHoldPolicyId)" }, { "lang": "java", "label": "Get legal hold policy", "source": "client.getLegalHoldPolicies().getLegalHoldPolicyById(legalHoldPolicyId)" }, { "lang": "node", "label": "Get legal hold policy", "source": "await client.legalHoldPolicies.getLegalHoldPolicyById(legalHoldPolicyId);" }, { "lang": "python", "label": "Get legal hold policy", "source": "client.legal_hold_policies.get_legal_hold_policy_by_id(legal_hold_policy_id)" } ] }, "put": { "operationId": "put_legal_hold_policies_id", "summary": "Update legal hold policy", "description": "Update legal hold policy.", "parameters": [ { "name": "legal_hold_policy_id", "in": "path", "description": "The ID of the legal hold policy.", "required": true, "schema": { "type": "string" }, "example": "324432" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_name": { "description": "The name of the policy.", "type": "string", "example": "Sales Policy", "maxLength": 254 }, "description": { "description": "A description for the policy.", "type": "string", "example": "A custom policy for the sales team", "maxLength": 500 }, "release_notes": { "description": "Notes around why the policy was released.", "type": "string", "example": "Required for GDPR", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Returns a new legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicy" } } } }, "409": { "description": "Returns an error if a policy with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policies", "tags": [ "Legal hold policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Update legal hold policy", "source": "curl -i -X PUT \"https://api.box.com/2.0/legal_hold_policies/324432\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"policy_name\": \"Policy 4\"\n }'" }, { "lang": "dotnet", "label": "Update legal hold policy", "source": "await client.LegalHoldPolicies.UpdateLegalHoldPolicyByIdAsync(legalHoldPolicyId: legalHoldPolicyId, requestBody: new UpdateLegalHoldPolicyByIdRequestBody() { PolicyName = updatedLegalHoldPolicyName });" }, { "lang": "swift", "label": "Update legal hold policy", "source": "try await client.legalHoldPolicies.updateLegalHoldPolicyById(legalHoldPolicyId: legalHoldPolicyId, requestBody: UpdateLegalHoldPolicyByIdRequestBody(policyName: updatedLegalHoldPolicyName))" }, { "lang": "java", "label": "Update legal hold policy", "source": "client.getLegalHoldPolicies().updateLegalHoldPolicyById(legalHoldPolicyId, new UpdateLegalHoldPolicyByIdRequestBody.Builder().policyName(updatedLegalHoldPolicyName).build())" }, { "lang": "node", "label": "Update legal hold policy", "source": "await client.legalHoldPolicies.updateLegalHoldPolicyById(legalHoldPolicyId, {\n requestBody: {\n policyName: updatedLegalHoldPolicyName,\n } satisfies UpdateLegalHoldPolicyByIdRequestBody,\n} satisfies UpdateLegalHoldPolicyByIdOptionalsInput);" }, { "lang": "python", "label": "Update legal hold policy", "source": "client.legal_hold_policies.update_legal_hold_policy_by_id(\n legal_hold_policy_id, policy_name=updated_legal_hold_policy_name\n)" } ] }, "delete": { "operationId": "delete_legal_hold_policies_id", "summary": "Remove legal hold policy", "description": "Delete an existing legal hold policy.\n\nThis is an asynchronous process. The policy will not be fully deleted yet when the response returns.", "parameters": [ { "name": "legal_hold_policy_id", "in": "path", "description": "The ID of the legal hold policy.", "required": true, "schema": { "type": "string" }, "example": "324432" } ], "responses": { "202": { "description": "A blank response is returned if the policy was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policies", "tags": [ "Legal hold policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove legal hold policy", "source": "curl -i -X DELETE \"https://api.box.com/2.0/legal_hold_policies/324432\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove legal hold policy", "source": "await client.LegalHoldPolicies.DeleteLegalHoldPolicyByIdAsync(legalHoldPolicyId: legalHoldPolicy.Id);" }, { "lang": "swift", "label": "Remove legal hold policy", "source": "try await client.legalHoldPolicies.deleteLegalHoldPolicyById(legalHoldPolicyId: legalHoldPolicy.id)" }, { "lang": "java", "label": "Remove legal hold policy", "source": "client.getLegalHoldPolicies().deleteLegalHoldPolicyById(legalHoldPolicy.getId())" }, { "lang": "node", "label": "Remove legal hold policy", "source": "await client.legalHoldPolicies.deleteLegalHoldPolicyById(legalHoldPolicy.id);" }, { "lang": "python", "label": "Remove legal hold policy", "source": "client.legal_hold_policies.delete_legal_hold_policy_by_id(legal_hold_policy.id)" } ] } }, "/legal_hold_policy_assignments": { "get": { "operationId": "get_legal_hold_policy_assignments", "summary": "List legal hold policy assignments", "description": "Retrieves a list of items a legal hold policy has been assigned to.", "parameters": [ { "name": "policy_id", "in": "query", "description": "The ID of the legal hold policy.", "required": true, "schema": { "type": "string" }, "example": "324432" }, { "name": "assign_to_type", "in": "query", "description": "Filters the results by the type of item the policy was applied to.", "schema": { "type": "string", "enum": [ "file", "file_version", "folder", "user", "ownership", "interactions" ] }, "example": "file" }, { "name": "assign_to_id", "in": "query", "description": "Filters the results by the ID of item the policy was applied to.", "schema": { "type": "string" }, "example": "1234323" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns a list of legal hold policy assignments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicyAssignments" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "List legal hold policy assignments", "source": "curl -i -X GET \"https://api.box.com/2.0/legal_hold_policy_assignments?policy_id=324432\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List legal hold policy assignments", "source": "await client.LegalHoldPolicyAssignments.GetLegalHoldPolicyAssignmentsAsync(queryParams: new GetLegalHoldPolicyAssignmentsQueryParams(policyId: legalHoldPolicyId));" }, { "lang": "swift", "label": "List legal hold policy assignments", "source": "try await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignments(queryParams: GetLegalHoldPolicyAssignmentsQueryParams(policyId: legalHoldPolicyId))" }, { "lang": "java", "label": "List legal hold policy assignments", "source": "client.getLegalHoldPolicyAssignments().getLegalHoldPolicyAssignments(new GetLegalHoldPolicyAssignmentsQueryParams(legalHoldPolicyId))" }, { "lang": "node", "label": "List legal hold policy assignments", "source": "await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignments({\n policyId: legalHoldPolicyId,\n} satisfies GetLegalHoldPolicyAssignmentsQueryParams);" }, { "lang": "python", "label": "List legal hold policy assignments", "source": "client.legal_hold_policy_assignments.get_legal_hold_policy_assignments(\n legal_hold_policy_id\n)" } ] }, "post": { "operationId": "post_legal_hold_policy_assignments", "summary": "Assign legal hold policy", "description": "Assign a legal hold to an item type of: file, file version, folder, user, ownership, or interactions.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "description": "The ID of the policy to assign.", "type": "string", "example": "123244" }, "assign_to": { "description": "The item to assign the policy to.", "type": "object", "properties": { "type": { "description": "The type of item to assign the policy to.", "type": "string", "example": "folder", "enum": [ "file", "file_version", "folder", "user", "ownership", "interactions" ] }, "id": { "description": "The ID of item to assign the policy to.", "type": "string", "example": "6564564" } }, "required": [ "type", "id" ] } }, "required": [ "policy_id", "assign_to" ] } } } }, "responses": { "201": { "description": "Returns a new legal hold policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Assign legal hold policy", "source": "curl -i -X POST \"https://api.box.com/2.0/legal_hold_policy_assignments\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"policy_id\": \"123244\",\n \"assign_to\": {\n \"type\": \"folder\",\n \"id\": \"6564564\"\n }\n }'" }, { "lang": "dotnet", "label": "Assign legal hold policy", "source": "await client.LegalHoldPolicyAssignments.CreateLegalHoldPolicyAssignmentAsync(requestBody: new CreateLegalHoldPolicyAssignmentRequestBody(policyId: legalHoldPolicyId, assignTo: new CreateLegalHoldPolicyAssignmentRequestBodyAssignToField(type: CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField.File, id: fileId)));" }, { "lang": "swift", "label": "Assign legal hold policy", "source": "try await client.legalHoldPolicyAssignments.createLegalHoldPolicyAssignment(requestBody: CreateLegalHoldPolicyAssignmentRequestBody(policyId: legalHoldPolicyId, assignTo: CreateLegalHoldPolicyAssignmentRequestBodyAssignToField(type: CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField.file, id: fileId)))" }, { "lang": "java", "label": "Assign legal hold policy", "source": "client.getLegalHoldPolicyAssignments().createLegalHoldPolicyAssignment(new CreateLegalHoldPolicyAssignmentRequestBody(legalHoldPolicyId, new CreateLegalHoldPolicyAssignmentRequestBodyAssignToField(CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField.FILE, fileId)))" }, { "lang": "node", "label": "Assign legal hold policy", "source": "await client.legalHoldPolicyAssignments.createLegalHoldPolicyAssignment({\n policyId: legalHoldPolicyId,\n assignTo: {\n type: 'file' as CreateLegalHoldPolicyAssignmentRequestBodyAssignToTypeField,\n id: fileId,\n } satisfies CreateLegalHoldPolicyAssignmentRequestBodyAssignToField,\n} satisfies CreateLegalHoldPolicyAssignmentRequestBody);" }, { "lang": "python", "label": "Assign legal hold policy", "source": "client.legal_hold_policy_assignments.create_legal_hold_policy_assignment(\n legal_hold_policy_id,\n CreateLegalHoldPolicyAssignmentAssignTo(\n type=CreateLegalHoldPolicyAssignmentAssignToTypeField.FILE, id=file_id\n ),\n)" } ] } }, "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}": { "get": { "operationId": "get_legal_hold_policy_assignments_id", "summary": "Get legal hold policy assignment", "description": "Retrieve a legal hold policy assignment.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "in": "path", "description": "The ID of the legal hold policy assignment.", "required": true, "schema": { "type": "string" }, "example": "753465" } ], "responses": { "200": { "description": "Returns a legal hold policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldPolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get legal hold policy assignment", "source": "curl -i -X GET \"https://api.box.com/2.0/legal_hold_policy_assignments/753465\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get legal hold policy assignment", "source": "await client.LegalHoldPolicyAssignments.GetLegalHoldPolicyAssignmentByIdAsync(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId);" }, { "lang": "swift", "label": "Get legal hold policy assignment", "source": "try await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignmentById(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId)" }, { "lang": "java", "label": "Get legal hold policy assignment", "source": "client.getLegalHoldPolicyAssignments().getLegalHoldPolicyAssignmentById(legalHoldPolicyAssignmentId)" }, { "lang": "node", "label": "Get legal hold policy assignment", "source": "await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignmentById(\n legalHoldPolicyAssignmentId,\n);" }, { "lang": "python", "label": "Get legal hold policy assignment", "source": "client.legal_hold_policy_assignments.get_legal_hold_policy_assignment_by_id(\n legal_hold_policy_assignment_id\n)" } ] }, "delete": { "operationId": "delete_legal_hold_policy_assignments_id", "summary": "Unassign legal hold policy", "description": "Remove a legal hold from an item.\n\nThis is an asynchronous process. The policy will not be fully removed yet when the response returns.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "in": "path", "description": "The ID of the legal hold policy assignment.", "required": true, "schema": { "type": "string" }, "example": "753465" } ], "responses": { "202": { "description": "A blank response is returned if the assignment was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Unassign legal hold policy", "source": "curl -i -X DELETE \"https://api.box.com/2.0/legal_hold_policy_assignments/753465\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Unassign legal hold policy", "source": "await client.LegalHoldPolicyAssignments.DeleteLegalHoldPolicyAssignmentByIdAsync(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId);" }, { "lang": "swift", "label": "Unassign legal hold policy", "source": "try await client.legalHoldPolicyAssignments.deleteLegalHoldPolicyAssignmentById(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId)" }, { "lang": "java", "label": "Unassign legal hold policy", "source": "client.getLegalHoldPolicyAssignments().deleteLegalHoldPolicyAssignmentById(legalHoldPolicyAssignmentId)" }, { "lang": "node", "label": "Unassign legal hold policy", "source": "await client.legalHoldPolicyAssignments.deleteLegalHoldPolicyAssignmentById(\n legalHoldPolicyAssignmentId,\n);" }, { "lang": "python", "label": "Unassign legal hold policy", "source": "client.legal_hold_policy_assignments.delete_legal_hold_policy_assignment_by_id(\n legal_hold_policy_assignment_id\n)" } ] } }, "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold": { "get": { "operationId": "get_legal_hold_policy_assignments_id_files_on_hold", "summary": "List files with current file versions for legal hold policy assignment", "description": "Get a list of files with current file versions for a legal hold assignment.\n\nIn 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.\n\nDue 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.\n\nThis endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "in": "path", "description": "The ID of the legal hold policy assignment.", "required": true, "schema": { "type": "string" }, "example": "753465" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the list of current file versions held under legal hold for a specific legal hold policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesOnHold" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "List files with current file versions for legal hold policy assignment", "source": "curl -i -X GET \"https://api.box.com/2.0/legal_hold_policy_assignments/753465/files_on_hold\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List files with current file versions for legal hold policy assignment", "source": "await client.LegalHoldPolicyAssignments.GetLegalHoldPolicyAssignmentFileOnHoldAsync(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId);" }, { "lang": "swift", "label": "List files with current file versions for legal hold policy assignment", "source": "try await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignmentFileOnHold(legalHoldPolicyAssignmentId: legalHoldPolicyAssignmentId)" }, { "lang": "java", "label": "List files with current file versions for legal hold policy assignment", "source": "client.getLegalHoldPolicyAssignments().getLegalHoldPolicyAssignmentFileOnHold(legalHoldPolicyAssignmentId)" }, { "lang": "node", "label": "List files with current file versions for legal hold policy assignment", "source": "await client.legalHoldPolicyAssignments.getLegalHoldPolicyAssignmentFileOnHold(\n legalHoldPolicyAssignmentId,\n);" }, { "lang": "python", "label": "List files with current file versions for legal hold policy assignment", "source": "client.legal_hold_policy_assignments.get_legal_hold_policy_assignment_file_on_hold(\n legal_hold_policy_assignment_id\n)" } ] } }, "/file_version_retentions": { "get": { "operationId": "get_file_version_retentions", "summary": "List file version retentions", "description": "Retrieves all file version retentions for the given enterprise.\n\n**Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", "parameters": [ { "name": "file_id", "in": "query", "description": "Filters results by files with this ID.", "required": false, "schema": { "type": "string" }, "example": "43123123" }, { "name": "file_version_id", "in": "query", "description": "Filters results by file versions with this ID.", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "policy_id", "in": "query", "description": "Filters results by the retention policy with this ID.", "required": false, "schema": { "type": "string" }, "example": "982312" }, { "name": "disposition_action", "in": "query", "description": "Filters results by the retention policy with this disposition action.", "required": false, "schema": { "type": "string", "enum": [ "permanently_delete", "remove_retention" ] }, "example": "permanently_delete" }, { "name": "disposition_before", "in": "query", "description": "Filters results by files that will have their disposition come into effect before this date.", "required": false, "schema": { "type": "string" }, "example": "2012-12-12T10:53:43-08:00" }, { "name": "disposition_after", "in": "query", "description": "Filters results by files that will have their disposition come into effect after this date.", "required": false, "schema": { "type": "string" }, "example": "2012-12-19T10:34:23-08:00" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { "200": { "description": "Returns a list of all file version retentions for the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionRetentions" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_version_retentions", "tags": [ "File version retentions" ], "x-codeSamples": [ { "lang": "curl", "label": "List file version retentions", "source": "curl -i -X GET \"https://api.box.com/2.0/file_version_retentions\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List file version retentions", "source": "await client.FileVersionRetentions.GetFileVersionRetentionsAsync();" }, { "lang": "swift", "label": "List file version retentions", "source": "try await client.fileVersionRetentions.getFileVersionRetentions()" }, { "lang": "java", "label": "List file version retentions", "source": "client.getFileVersionRetentions().getFileVersionRetentions()" }, { "lang": "node", "label": "List file version retentions", "source": "await client.fileVersionRetentions.getFileVersionRetentions();" }, { "lang": "python", "label": "List file version retentions", "source": "client.file_version_retentions.get_file_version_retentions()" } ] } }, "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold": { "get": { "operationId": "get_legal_hold_policy_assignments_id_file_versions_on_hold", "summary": "List previous file versions for legal hold policy assignment", "description": "Get a list of previous file versions for a legal hold assignment.\n\nIn 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.\n\nDue 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.\n\nThis endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "in": "path", "description": "The ID of the legal hold policy assignment.", "required": true, "schema": { "type": "string" }, "example": "753465" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false } ], "responses": { "200": { "description": "Returns the list of previous file versions held under legal hold for a specific legal hold policy assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionsOnHold" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "legal_hold_policy_assignments", "tags": [ "Legal hold policy assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "List previous file versions for legal hold policy assignment", "source": "curl -i -X GET \"https://api.box.com/2.0/legal_hold_policy_assignments/753465/file_versions_on_hold\" \\\n -H \"authorization: Bearer \"" } ] } }, "/file_version_retentions/{file_version_retention_id}": { "get": { "operationId": "get_file_version_retentions_id", "summary": "Get retention on file", "description": "Returns information about a file version retention.\n\n**Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", "parameters": [ { "name": "file_version_retention_id", "in": "path", "description": "The ID of the file version retention.", "required": true, "schema": { "type": "string" }, "example": "3424234" } ], "responses": { "200": { "description": "Returns a file version retention object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionRetention" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_version_retentions", "tags": [ "File version retentions" ], "x-codeSamples": [ { "lang": "curl", "label": "Get retention on file", "source": "curl -i -X GET \"https://api.box.com/2.0/file_version_retentions/3424234\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get retention on file", "source": "await client.FileVersionRetentions.GetFileVersionRetentionByIdAsync(fileVersionRetentionId: NullableUtils.Unwrap(fileVersionRetention.Id));" }, { "lang": "swift", "label": "Get retention on file", "source": "try await client.fileVersionRetentions.getFileVersionRetentionById(fileVersionRetentionId: fileVersionRetention.id!)" }, { "lang": "java", "label": "Get retention on file", "source": "client.getFileVersionRetentions().getFileVersionRetentionById(fileVersionRetention.getId())" }, { "lang": "node", "label": "Get retention on file", "source": "await client.fileVersionRetentions.getFileVersionRetentionById(\n fileVersionRetention.id!,\n);" }, { "lang": "python", "label": "Get retention on file", "source": "client.file_version_retentions.get_file_version_retention_by_id(\n file_version_retention.id\n)" } ] } }, "/file_version_legal_holds/{file_version_legal_hold_id}": { "get": { "operationId": "get_file_version_legal_holds_id", "summary": "Get file version legal hold", "description": "Retrieves information about the legal hold policies assigned to a file version.", "parameters": [ { "name": "file_version_legal_hold_id", "in": "path", "description": "The ID of the file version legal hold.", "required": true, "schema": { "type": "string" }, "example": "2348213" } ], "responses": { "200": { "description": "Returns the legal hold policy assignments for the file version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionLegalHold" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_version_legal_holds", "tags": [ "File version legal holds" ], "x-codeSamples": [ { "lang": "curl", "label": "Get file version legal hold", "source": "curl -i -X GET \"https://api.box.com/2.0/file_version_legal_holds/2348213\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get file version legal hold", "source": "await client.FileVersionLegalHolds.GetFileVersionLegalHoldByIdAsync(fileVersionLegalHoldId: fileVersionLegalHoldId);" }, { "lang": "swift", "label": "Get file version legal hold", "source": "try await client.fileVersionLegalHolds.getFileVersionLegalHoldById(fileVersionLegalHoldId: fileVersionLegalHoldId)" }, { "lang": "java", "label": "Get file version legal hold", "source": "client.getFileVersionLegalHolds().getFileVersionLegalHoldById(fileVersionLegalHoldId)" }, { "lang": "node", "label": "Get file version legal hold", "source": "await client.fileVersionLegalHolds.getFileVersionLegalHoldById(\n fileVersionLegalHoldId,\n);" }, { "lang": "python", "label": "Get file version legal hold", "source": "client.file_version_legal_holds.get_file_version_legal_hold_by_id(\n file_version_legal_hold_id\n)" } ] } }, "/file_version_legal_holds": { "get": { "operationId": "get_file_version_legal_holds", "summary": "List file version legal holds", "description": "Get a list of file versions on legal hold for a legal hold assignment.\n\nDue to ongoing re-architecture efforts this API might not return all file versions for this policy ID.\n\nInstead, 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.\n\nFor 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.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID.\n\nOnce the re-architecture is completed this API will be deprecated.", "parameters": [ { "name": "policy_id", "in": "query", "description": "The ID of the legal hold policy to get the file version legal holds for.", "required": true, "schema": { "type": "string" }, "example": "133870" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns the list of file version legal holds for a specific legal hold policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionLegalHolds" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "file_version_legal_holds", "tags": [ "File version legal holds" ], "x-codeSamples": [ { "lang": "curl", "label": "List file version legal holds", "source": "curl -i -X GET \"https://api.box.com/2.0/file_version_legal_holds?policy_id=133870\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List file version legal holds", "source": "await client.FileVersionLegalHolds.GetFileVersionLegalHoldsAsync(queryParams: new GetFileVersionLegalHoldsQueryParams(policyId: policyId));" }, { "lang": "swift", "label": "List file version legal holds", "source": "try await client.fileVersionLegalHolds.getFileVersionLegalHolds(queryParams: GetFileVersionLegalHoldsQueryParams(policyId: policyId))" }, { "lang": "java", "label": "List file version legal holds", "source": "client.getFileVersionLegalHolds().getFileVersionLegalHolds(new GetFileVersionLegalHoldsQueryParams(policyId))" }, { "lang": "node", "label": "List file version legal holds", "source": "await client.fileVersionLegalHolds.getFileVersionLegalHolds({\n policyId: policyId,\n} satisfies GetFileVersionLegalHoldsQueryParams);" }, { "lang": "python", "label": "List file version legal holds", "source": "client.file_version_legal_holds.get_file_version_legal_holds(policy_id)" } ] } }, "/shield_information_barriers/{shield_information_barrier_id}": { "get": { "operationId": "get_shield_information_barriers_id", "summary": "Get shield information barrier with specified ID", "description": "Get shield information barrier based on provided ID.", "parameters": [ { "name": "shield_information_barrier_id", "in": "path", "description": "The ID of the shield information barrier.", "required": true, "schema": { "type": "string" }, "example": "1910967" } ], "responses": { "200": { "description": "Returns the shield information barrier object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barriers", "tags": [ "Shield information barriers" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shield information barrier with specified ID", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barriers/1910967\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shield information barrier with specified ID", "source": "await client.ShieldInformationBarriers.GetShieldInformationBarrierByIdAsync(shieldInformationBarrierId: barrierId);" }, { "lang": "swift", "label": "Get shield information barrier with specified ID", "source": "try await client.shieldInformationBarriers.getShieldInformationBarrierById(shieldInformationBarrierId: barrierId)" }, { "lang": "java", "label": "Get shield information barrier with specified ID", "source": "client.getShieldInformationBarriers().getShieldInformationBarrierById(barrierId)" }, { "lang": "node", "label": "Get shield information barrier with specified ID", "source": "await client.shieldInformationBarriers.getShieldInformationBarrierById(\n barrierId,\n);" }, { "lang": "python", "label": "Get shield information barrier with specified ID", "source": "client.shield_information_barriers.get_shield_information_barrier_by_id(barrier_id)" } ] } }, "/shield_information_barriers/change_status": { "post": { "operationId": "post_shield_information_barriers_change_status", "summary": "Add changed status of shield information barrier with specified ID", "description": "Change status of shield information barrier with the specified ID.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the shield information barrier.", "type": "string", "example": "1910967" }, "status": { "description": "The desired status for the shield information barrier.", "type": "string", "example": "pending", "enum": [ "pending", "disabled" ] } }, "required": [ "id", "status" ] } } } }, "responses": { "200": { "description": "Returns the updated shield information barrier object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there exists Conflicts with existing information barriers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barriers", "tags": [ "Shield information barriers" ], "x-codeSamples": [ { "lang": "curl", "label": "Add changed status of shield information barrier with specified ID", "source": "curl -i -X POST \"https://api.box.com/2.0/shield_information_barriers/change_status\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"id\": \"1910967\",\n \"status\": \"pending\"\n }'" }, { "lang": "dotnet", "label": "Add changed status of shield information barrier with specified ID", "source": "await client.ShieldInformationBarriers.UpdateShieldInformationBarrierStatusAsync(requestBody: new UpdateShieldInformationBarrierStatusRequestBody(id: barrierId, status: UpdateShieldInformationBarrierStatusRequestBodyStatusField.Disabled));" }, { "lang": "swift", "label": "Add changed status of shield information barrier with specified ID", "source": "try await client.shieldInformationBarriers.updateShieldInformationBarrierStatus(requestBody: UpdateShieldInformationBarrierStatusRequestBody(id: barrierId, status: UpdateShieldInformationBarrierStatusRequestBodyStatusField.disabled))" }, { "lang": "java", "label": "Add changed status of shield information barrier with specified ID", "source": "client.getShieldInformationBarriers().updateShieldInformationBarrierStatus(new UpdateShieldInformationBarrierStatusRequestBody(barrierId, UpdateShieldInformationBarrierStatusRequestBodyStatusField.DISABLED))" }, { "lang": "node", "label": "Add changed status of shield information barrier with specified ID", "source": "await client.shieldInformationBarriers.updateShieldInformationBarrierStatus({\n id: barrierId,\n status:\n 'disabled' as UpdateShieldInformationBarrierStatusRequestBodyStatusField,\n} satisfies UpdateShieldInformationBarrierStatusRequestBody);" }, { "lang": "python", "label": "Add changed status of shield information barrier with specified ID", "source": "client.shield_information_barriers.update_shield_information_barrier_status(\n barrier_id, UpdateShieldInformationBarrierStatusStatus.DISABLED\n)" } ] } }, "/shield_information_barriers": { "get": { "operationId": "get_shield_information_barriers", "summary": "List shield information barriers", "description": "Retrieves a list of shield information barrier objects for the enterprise of JWT.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shield information barrier objects, empty list if currently no barrier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarriers" } } } }, "404": { "description": "Returns a `not_found` error if could not find an enterprise using JWT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barriers", "tags": [ "Shield information barriers" ], "x-codeSamples": [ { "lang": "curl", "label": "List shield information barriers", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barriers\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List shield information barriers", "source": "await client.ShieldInformationBarriers.GetShieldInformationBarriersAsync();" }, { "lang": "swift", "label": "List shield information barriers", "source": "try await client.shieldInformationBarriers.getShieldInformationBarriers()" }, { "lang": "java", "label": "List shield information barriers", "source": "client.getShieldInformationBarriers().getShieldInformationBarriers()" }, { "lang": "node", "label": "List shield information barriers", "source": "await client.shieldInformationBarriers.getShieldInformationBarriers();" }, { "lang": "python", "label": "List shield information barriers", "source": "client.shield_information_barriers.get_shield_information_barriers()" } ] }, "post": { "operationId": "post_shield_information_barriers", "summary": "Create shield information barrier", "description": "Creates a shield information barrier to separate individuals/groups within the same firm and prevents confidential information passing between them.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enterprise": { "description": "The `type` and `id` of enterprise this barrier is under.", "allOf": [ { "$ref": "#/components/schemas/Enterprise--Base" } ] } }, "required": [ "enterprise" ] } } } }, "responses": { "201": { "description": "Returns a new shield information barrier object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } }, "400": { "description": "Returns an error if the enterprise is missing from the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error when an incorrect or null enterprise is present in the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barriers", "tags": [ "Shield information barriers" ], "x-codeSamples": [ { "lang": "curl", "label": "Create shield information barrier", "source": "curl -i -X POST \"https://api.box.com/2.0/shield_information_barriers\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"enterprise\": {\n \"id\": \"1910967\",\n \"type\": \"enterprise\"\n }\n }'" }, { "lang": "dotnet", "label": "Create shield information barrier", "source": "await client.ShieldInformationBarriers.CreateShieldInformationBarrierAsync(requestBody: new CreateShieldInformationBarrierRequestBody(enterprise: new EnterpriseBase() { Id = enterpriseId }));" }, { "lang": "swift", "label": "Create shield information barrier", "source": "try await client.shieldInformationBarriers.createShieldInformationBarrier(requestBody: CreateShieldInformationBarrierRequestBody(enterprise: EnterpriseBase(id: enterpriseId)))" }, { "lang": "java", "label": "Create shield information barrier", "source": "client.getShieldInformationBarriers().createShieldInformationBarrier(new CreateShieldInformationBarrierRequestBody(new EnterpriseBase.Builder().id(enterpriseId).build()))" }, { "lang": "node", "label": "Create shield information barrier", "source": "await client.shieldInformationBarriers.createShieldInformationBarrier({\n enterprise: { id: enterpriseId } satisfies EnterpriseBase,\n} satisfies CreateShieldInformationBarrierRequestBody);" }, { "lang": "python", "label": "Create shield information barrier", "source": "client.shield_information_barriers.create_shield_information_barrier(\n EnterpriseBase(id=enterprise_id)\n)" } ] } }, "/shield_information_barrier_reports": { "get": { "operationId": "get_shield_information_barrier_reports", "summary": "List shield information barrier reports", "description": "Lists shield information barrier reports.", "parameters": [ { "name": "shield_information_barrier_id", "in": "query", "description": "The ID of the shield information barrier.", "required": true, "schema": { "type": "string" }, "example": "1910967" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shield information barrier report objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierReports" } } } }, "404": { "description": "Returns a `not_found` error if the Shield Information Barrier could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_reports", "tags": [ "Shield information barrier reports" ], "x-codeSamples": [ { "lang": "curl", "label": "List shield information barrier reports", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_reports?shield_information_barrier_id=1910967\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List shield information barrier reports", "source": "await client.ShieldInformationBarrierReports.GetShieldInformationBarrierReportsAsync(queryParams: new GetShieldInformationBarrierReportsQueryParams(shieldInformationBarrierId: barrierId));" }, { "lang": "swift", "label": "List shield information barrier reports", "source": "try await client.shieldInformationBarrierReports.getShieldInformationBarrierReports(queryParams: GetShieldInformationBarrierReportsQueryParams(shieldInformationBarrierId: barrierId))" }, { "lang": "java", "label": "List shield information barrier reports", "source": "client.getShieldInformationBarrierReports().getShieldInformationBarrierReports(new GetShieldInformationBarrierReportsQueryParams(barrierId))" }, { "lang": "node", "label": "List shield information barrier reports", "source": "await client.shieldInformationBarrierReports.getShieldInformationBarrierReports(\n {\n shieldInformationBarrierId: barrierId,\n } satisfies GetShieldInformationBarrierReportsQueryParams,\n);" }, { "lang": "python", "label": "List shield information barrier reports", "source": "client.shield_information_barrier_reports.get_shield_information_barrier_reports(\n barrier_id\n)" } ] }, "post": { "operationId": "post_shield_information_barrier_reports", "summary": "Create shield information barrier report", "description": "Creates a shield information barrier report for a given barrier.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierReference" } } } }, "responses": { "201": { "description": "Returns the shield information barrier report information object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierReport" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier report was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns a `conflict` error if a shield information barrier report is currently being created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_reports", "tags": [ "Shield information barrier reports" ], "x-codeSamples": [ { "lang": "curl", "label": "Create shield information barrier report", "source": "curl -i -X POST \"https://api.box.com/2.0/shield_information_barrier_reports\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"shield_information_barrier\": {\n \"id\": \"11446498\",\n \"type\": \"shield_information_barrier\"\n }\n }'" }, { "lang": "dotnet", "label": "Create shield information barrier report", "source": "await client.ShieldInformationBarrierReports.CreateShieldInformationBarrierReportAsync(requestBody: new ShieldInformationBarrierReference() { ShieldInformationBarrier = new ShieldInformationBarrierBase() { Id = barrierId, Type = ShieldInformationBarrierBaseTypeField.ShieldInformationBarrier } });" }, { "lang": "swift", "label": "Create shield information barrier report", "source": "try await client.shieldInformationBarrierReports.createShieldInformationBarrierReport(requestBody: ShieldInformationBarrierReference(shieldInformationBarrier: ShieldInformationBarrierBase(id: barrierId, type: ShieldInformationBarrierBaseTypeField.shieldInformationBarrier)))" }, { "lang": "java", "label": "Create shield information barrier report", "source": "client.getShieldInformationBarrierReports().createShieldInformationBarrierReport(new ShieldInformationBarrierReference.Builder().shieldInformationBarrier(new ShieldInformationBarrierBase.Builder().id(barrierId).type(ShieldInformationBarrierBaseTypeField.SHIELD_INFORMATION_BARRIER).build()).build())" }, { "lang": "node", "label": "Create shield information barrier report", "source": "await client.shieldInformationBarrierReports.createShieldInformationBarrierReport(\n {\n shieldInformationBarrier: {\n id: barrierId,\n type: 'shield_information_barrier' as ShieldInformationBarrierBaseTypeField,\n } satisfies ShieldInformationBarrierBase,\n } satisfies ShieldInformationBarrierReference,\n);" }, { "lang": "python", "label": "Create shield information barrier report", "source": "client.shield_information_barrier_reports.create_shield_information_barrier_report(\n shield_information_barrier=ShieldInformationBarrierBase(\n id=barrier_id,\n type=ShieldInformationBarrierBaseTypeField.SHIELD_INFORMATION_BARRIER,\n )\n)" } ] } }, "/shield_information_barrier_reports/{shield_information_barrier_report_id}": { "get": { "operationId": "get_shield_information_barrier_reports_id", "summary": "Get shield information barrier report by ID", "description": "Retrieves a shield information barrier report by its ID.", "parameters": [ { "name": "shield_information_barrier_report_id", "in": "path", "description": "The ID of the shield information barrier Report.", "required": true, "schema": { "type": "string" }, "example": "3423" } ], "responses": { "200": { "description": "Returns the shield information barrier report object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierReport" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier Report was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_reports", "tags": [ "Shield information barrier reports" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shield information barrier report by ID", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_reports/3423\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shield information barrier report by ID", "source": "await client.ShieldInformationBarrierReports.GetShieldInformationBarrierReportByIdAsync(shieldInformationBarrierReportId: NullableUtils.Unwrap(createdReport.Id));" }, { "lang": "swift", "label": "Get shield information barrier report by ID", "source": "try await client.shieldInformationBarrierReports.getShieldInformationBarrierReportById(shieldInformationBarrierReportId: createdReport.id!)" }, { "lang": "java", "label": "Get shield information barrier report by ID", "source": "client.getShieldInformationBarrierReports().getShieldInformationBarrierReportById(createdReport.getId())" }, { "lang": "node", "label": "Get shield information barrier report by ID", "source": "await client.shieldInformationBarrierReports.getShieldInformationBarrierReportById(\n createdReport.id!,\n);" }, { "lang": "python", "label": "Get shield information barrier report by ID", "source": "client.shield_information_barrier_reports.get_shield_information_barrier_report_by_id(\n created_report.id\n)" } ] } }, "/shield_information_barrier_segments/{shield_information_barrier_segment_id}": { "get": { "operationId": "get_shield_information_barrier_segments_id", "summary": "Get shield information barrier segment with specified ID", "description": "Retrieves shield information barrier segment based on provided ID..", "parameters": [ { "name": "shield_information_barrier_segment_id", "in": "path", "description": "The ID of the shield information barrier segment.", "required": true, "schema": { "type": "string" }, "example": "3423" } ], "responses": { "200": { "description": "Returns the shield information barrier segment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segments", "tags": [ "Shield information barrier segments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shield information barrier segment with specified ID", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_segments/3423\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shield information barrier segment with specified ID", "source": "await client.ShieldInformationBarrierSegments.GetShieldInformationBarrierSegmentByIdAsync(shieldInformationBarrierSegmentId: segmentId);" }, { "lang": "swift", "label": "Get shield information barrier segment with specified ID", "source": "try await client.shieldInformationBarrierSegments.getShieldInformationBarrierSegmentById(shieldInformationBarrierSegmentId: segmentId)" }, { "lang": "java", "label": "Get shield information barrier segment with specified ID", "source": "client.getShieldInformationBarrierSegments().getShieldInformationBarrierSegmentById(segmentId)" }, { "lang": "node", "label": "Get shield information barrier segment with specified ID", "source": "await client.shieldInformationBarrierSegments.getShieldInformationBarrierSegmentById(\n segmentId,\n);" }, { "lang": "python", "label": "Get shield information barrier segment with specified ID", "source": "client.shield_information_barrier_segments.get_shield_information_barrier_segment_by_id(\n segment_id\n)" } ] }, "delete": { "operationId": "delete_shield_information_barrier_segments_id", "summary": "Delete shield information barrier segment", "description": "Deletes the shield information barrier segment based on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_id", "in": "path", "description": "The ID of the shield information barrier segment.", "required": true, "schema": { "type": "string" }, "example": "3423" } ], "responses": { "204": { "description": "Empty body in response." }, "404": { "description": "Returns a `not_found` error if the shield information barrier segment with specified ID was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segments", "tags": [ "Shield information barrier segments" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete shield information barrier segment", "source": "curl -i -X DELETE \"https://api.box.com/2.0/shield_information_barrier_segments/3423\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete shield information barrier segment", "source": "await client.ShieldInformationBarrierSegments.DeleteShieldInformationBarrierSegmentByIdAsync(shieldInformationBarrierSegmentId: segmentId);" }, { "lang": "swift", "label": "Delete shield information barrier segment", "source": "try await client.shieldInformationBarrierSegments.deleteShieldInformationBarrierSegmentById(shieldInformationBarrierSegmentId: segmentId)" }, { "lang": "java", "label": "Delete shield information barrier segment", "source": "client.getShieldInformationBarrierSegments().deleteShieldInformationBarrierSegmentById(segmentId)" }, { "lang": "node", "label": "Delete shield information barrier segment", "source": "await client.shieldInformationBarrierSegments.deleteShieldInformationBarrierSegmentById(\n segmentId,\n);" }, { "lang": "python", "label": "Delete shield information barrier segment", "source": "client.shield_information_barrier_segments.delete_shield_information_barrier_segment_by_id(\n segment_id\n)" } ] }, "put": { "operationId": "put_shield_information_barrier_segments_id", "summary": "Update shield information barrier segment with specified ID", "description": "Updates the shield information barrier segment based on provided ID..", "parameters": [ { "name": "shield_information_barrier_segment_id", "in": "path", "description": "The ID of the shield information barrier segment.", "required": true, "schema": { "type": "string" }, "example": "3423" } ], "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.", "type": "object", "properties": { "name": { "description": "The updated name for the shield information barrier segment.", "type": "string", "example": "Investment Banking", "pattern": "\\S+" }, "description": { "description": "The updated description for the shield information barrier segment.", "type": "string", "example": "'Corporate division that engages in advisory_based\nfinancial transactions on behalf of individuals,\ncorporations, and governments.'", "nullable": true } } } } } }, "responses": { "200": { "description": "Returns the updated shield information barrier segment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } }, "404": { "description": "Returns a `not_found` error if the shield information Barrier Segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there exists a shield information Barrier Segment with the same name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segments", "tags": [ "Shield information barrier segments" ], "x-codeSamples": [ { "lang": "curl", "label": "Update shield information barrier segment with specified ID", "source": "curl -i -X PUT \"https://api.box.com/2.0/shield_information_barrier_segments/3423\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"name\": \"Investment Banking\",\n \"description\": \"Corporate division that engages in advisory-based financial transactions on behalf of individuals, corporations, and governments.\"\n }'" }, { "lang": "dotnet", "label": "Update shield information barrier segment with specified ID", "source": "await client.ShieldInformationBarrierSegments.UpdateShieldInformationBarrierSegmentByIdAsync(shieldInformationBarrierSegmentId: segmentId, requestBody: new UpdateShieldInformationBarrierSegmentByIdRequestBody() { Description = updatedSegmentDescription });" }, { "lang": "swift", "label": "Update shield information barrier segment with specified ID", "source": "try await client.shieldInformationBarrierSegments.updateShieldInformationBarrierSegmentById(shieldInformationBarrierSegmentId: segmentId, requestBody: UpdateShieldInformationBarrierSegmentByIdRequestBody(description: updatedSegmentDescription))" }, { "lang": "java", "label": "Update shield information barrier segment with specified ID", "source": "client.getShieldInformationBarrierSegments().updateShieldInformationBarrierSegmentById(segmentId, new UpdateShieldInformationBarrierSegmentByIdRequestBody.Builder().description(updatedSegmentDescription).build())" }, { "lang": "node", "label": "Update shield information barrier segment with specified ID", "source": "await client.shieldInformationBarrierSegments.updateShieldInformationBarrierSegmentById(\n segmentId,\n {\n requestBody: {\n description: updatedSegmentDescription,\n } satisfies UpdateShieldInformationBarrierSegmentByIdRequestBody,\n } satisfies UpdateShieldInformationBarrierSegmentByIdOptionalsInput,\n);" }, { "lang": "python", "label": "Update shield information barrier segment with specified ID", "source": "client.shield_information_barrier_segments.update_shield_information_barrier_segment_by_id(\n segment_id, description=updated_segment_description\n)" } ] } }, "/shield_information_barrier_segments": { "get": { "operationId": "get_shield_information_barrier_segments", "summary": "List shield information barrier segments", "description": "Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID.", "parameters": [ { "name": "shield_information_barrier_id", "in": "query", "description": "The ID of the shield information barrier.", "required": true, "schema": { "type": "string" }, "example": "1910967" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shield information barrier segment objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegments" } } } }, "404": { "description": "Returns a `not_found` error if the shield information Barrier of given ID was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segments", "tags": [ "Shield information barrier segments" ], "x-codeSamples": [ { "lang": "curl", "label": "List shield information barrier segments", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_segments?shield_information_barrier_id=1910967\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List shield information barrier segments", "source": "await client.ShieldInformationBarrierSegments.GetShieldInformationBarrierSegmentsAsync(queryParams: new GetShieldInformationBarrierSegmentsQueryParams(shieldInformationBarrierId: barrierId));" }, { "lang": "swift", "label": "List shield information barrier segments", "source": "try await client.shieldInformationBarrierSegments.getShieldInformationBarrierSegments(queryParams: GetShieldInformationBarrierSegmentsQueryParams(shieldInformationBarrierId: barrierId))" }, { "lang": "java", "label": "List shield information barrier segments", "source": "client.getShieldInformationBarrierSegments().getShieldInformationBarrierSegments(new GetShieldInformationBarrierSegmentsQueryParams(barrierId))" }, { "lang": "node", "label": "List shield information barrier segments", "source": "await client.shieldInformationBarrierSegments.getShieldInformationBarrierSegments(\n {\n shieldInformationBarrierId: barrierId,\n } satisfies GetShieldInformationBarrierSegmentsQueryParams,\n);" }, { "lang": "python", "label": "List shield information barrier segments", "source": "client.shield_information_barrier_segments.get_shield_information_barrier_segments(\n barrier_id\n)" } ] }, "post": { "operationId": "post_shield_information_barrier_segments", "summary": "Create shield information barrier segment", "description": "Creates a shield information barrier segment.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "name": { "description": "Name of the shield information barrier segment.", "type": "string", "example": "Investment Banking" }, "description": { "description": "Description of the shield information barrier segment.", "type": "string", "example": "'Corporate division that engages in\n advisory_based financial\ntransactions on behalf of individuals,\ncorporations, and governments.'" } }, "required": [ "shield_information_barrier", "name" ] } } } }, "responses": { "201": { "description": "Returns a new shield information barrier segment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } }, "404": { "description": "Returns an error if the shield information barrier was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "409": { "description": "Returns an error if there exists an shield information barrier segment with same name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segments", "tags": [ "Shield information barrier segments" ], "x-codeSamples": [ { "lang": "curl", "label": "Create shield information barrier segment", "source": "curl -i -X POST \"https://api.box.com/2.0/shield_information_barrier_segments\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"shield_information_barrier\": {\n \"id\": \"11446498\",\n \"type\": \"shield_information_barrier\"\n },\n \"name\": \"Investment Banking\"\n }'" }, { "lang": "dotnet", "label": "Create shield information barrier segment", "source": "await client.ShieldInformationBarrierSegments.CreateShieldInformationBarrierSegmentAsync(requestBody: new CreateShieldInformationBarrierSegmentRequestBody(shieldInformationBarrier: new ShieldInformationBarrierBase() { Id = barrierId, Type = ShieldInformationBarrierBaseTypeField.ShieldInformationBarrier }, name: segmentName) { Description = segmentDescription });" }, { "lang": "swift", "label": "Create shield information barrier segment", "source": "try await client.shieldInformationBarrierSegments.createShieldInformationBarrierSegment(requestBody: CreateShieldInformationBarrierSegmentRequestBody(shieldInformationBarrier: ShieldInformationBarrierBase(id: barrierId, type: ShieldInformationBarrierBaseTypeField.shieldInformationBarrier), name: segmentName, description: segmentDescription))" }, { "lang": "java", "label": "Create shield information barrier segment", "source": "client.getShieldInformationBarrierSegments().createShieldInformationBarrierSegment(new CreateShieldInformationBarrierSegmentRequestBody.Builder(new ShieldInformationBarrierBase.Builder().id(barrierId).type(ShieldInformationBarrierBaseTypeField.SHIELD_INFORMATION_BARRIER).build(), segmentName).description(segmentDescription).build())" }, { "lang": "node", "label": "Create shield information barrier segment", "source": "await client.shieldInformationBarrierSegments.createShieldInformationBarrierSegment(\n {\n shieldInformationBarrier: {\n id: barrierId,\n type: 'shield_information_barrier' as ShieldInformationBarrierBaseTypeField,\n } satisfies ShieldInformationBarrierBase,\n name: segmentName,\n description: segmentDescription,\n } satisfies CreateShieldInformationBarrierSegmentRequestBody,\n);" }, { "lang": "python", "label": "Create shield information barrier segment", "source": "client.shield_information_barrier_segments.create_shield_information_barrier_segment(\n ShieldInformationBarrierBase(\n id=barrier_id,\n type=ShieldInformationBarrierBaseTypeField.SHIELD_INFORMATION_BARRIER,\n ),\n segment_name,\n description=segment_description,\n)" } ] } }, "/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}": { "get": { "operationId": "get_shield_information_barrier_segment_members_id", "summary": "Get shield information barrier segment member by ID", "description": "Retrieves a shield information barrier segment member by its ID.", "parameters": [ { "name": "shield_information_barrier_segment_member_id", "in": "path", "description": "The ID of the shield information barrier segment Member.", "required": true, "schema": { "type": "string" }, "example": "7815" } ], "responses": { "200": { "description": "Returns the shield information barrier segment member object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier segment member was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_members", "tags": [ "Shield information barrier segment members" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shield information barrier segment member by ID", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_segment_members/7815\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shield information barrier segment member by ID", "source": "await client.ShieldInformationBarrierSegmentMembers.GetShieldInformationBarrierSegmentMemberByIdAsync(shieldInformationBarrierSegmentMemberId: NullableUtils.Unwrap(segmentMember.Id));" }, { "lang": "swift", "label": "Get shield information barrier segment member by ID", "source": "try await client.shieldInformationBarrierSegmentMembers.getShieldInformationBarrierSegmentMemberById(shieldInformationBarrierSegmentMemberId: segmentMember.id!)" }, { "lang": "java", "label": "Get shield information barrier segment member by ID", "source": "client.getShieldInformationBarrierSegmentMembers().getShieldInformationBarrierSegmentMemberById(segmentMember.getId())" }, { "lang": "node", "label": "Get shield information barrier segment member by ID", "source": "await client.shieldInformationBarrierSegmentMembers.getShieldInformationBarrierSegmentMemberById(\n segmentMember.id!,\n);" }, { "lang": "python", "label": "Get shield information barrier segment member by ID", "source": "client.shield_information_barrier_segment_members.get_shield_information_barrier_segment_member_by_id(\n segment_member.id\n)" } ] }, "delete": { "operationId": "delete_shield_information_barrier_segment_members_id", "summary": "Delete shield information barrier segment member by ID", "description": "Deletes a shield information barrier segment member based on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_member_id", "in": "path", "description": "The ID of the shield information barrier segment Member.", "required": true, "schema": { "type": "string" }, "example": "7815" } ], "responses": { "204": { "description": "Returns an empty response if the segment member was deleted successfully." }, "404": { "description": "Returns a `not_found` error if the shield information barrier segment member was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_members", "tags": [ "Shield information barrier segment members" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete shield information barrier segment member by ID", "source": "curl -i -X DELETE \"https://api.box.com/2.0/shield_information_barrier_segment_members/7815\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete shield information barrier segment member by ID", "source": "await client.ShieldInformationBarrierSegmentMembers.DeleteShieldInformationBarrierSegmentMemberByIdAsync(shieldInformationBarrierSegmentMemberId: NullableUtils.Unwrap(segmentMember.Id));" }, { "lang": "swift", "label": "Delete shield information barrier segment member by ID", "source": "try await client.shieldInformationBarrierSegmentMembers.deleteShieldInformationBarrierSegmentMemberById(shieldInformationBarrierSegmentMemberId: segmentMember.id!)" }, { "lang": "java", "label": "Delete shield information barrier segment member by ID", "source": "client.getShieldInformationBarrierSegmentMembers().deleteShieldInformationBarrierSegmentMemberById(segmentMember.getId())" }, { "lang": "node", "label": "Delete shield information barrier segment member by ID", "source": "await client.shieldInformationBarrierSegmentMembers.deleteShieldInformationBarrierSegmentMemberById(\n segmentMember.id!,\n);" }, { "lang": "python", "label": "Delete shield information barrier segment member by ID", "source": "client.shield_information_barrier_segment_members.delete_shield_information_barrier_segment_member_by_id(\n segment_member.id\n)" } ] } }, "/shield_information_barrier_segment_members": { "get": { "operationId": "get_shield_information_barrier_segment_members", "summary": "List shield information barrier segment members", "description": "Lists shield information barrier segment members based on provided segment IDs.", "parameters": [ { "name": "shield_information_barrier_segment_id", "in": "query", "description": "The ID of the shield information barrier segment.", "required": true, "schema": { "type": "string" }, "example": "3423" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shield information barrier segment member objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMembers" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_members", "tags": [ "Shield information barrier segment members" ], "x-codeSamples": [ { "lang": "curl", "label": "List shield information barrier segment members", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_segment_members?shield_information_barrier_segment_id=3423\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List shield information barrier segment members", "source": "await client.ShieldInformationBarrierSegmentMembers.GetShieldInformationBarrierSegmentMembersAsync(queryParams: new GetShieldInformationBarrierSegmentMembersQueryParams(shieldInformationBarrierSegmentId: NullableUtils.Unwrap(segment.Id)));" }, { "lang": "swift", "label": "List shield information barrier segment members", "source": "try await client.shieldInformationBarrierSegmentMembers.getShieldInformationBarrierSegmentMembers(queryParams: GetShieldInformationBarrierSegmentMembersQueryParams(shieldInformationBarrierSegmentId: segment.id!))" }, { "lang": "java", "label": "List shield information barrier segment members", "source": "client.getShieldInformationBarrierSegmentMembers().getShieldInformationBarrierSegmentMembers(new GetShieldInformationBarrierSegmentMembersQueryParams(segment.getId()))" }, { "lang": "node", "label": "List shield information barrier segment members", "source": "await client.shieldInformationBarrierSegmentMembers.getShieldInformationBarrierSegmentMembers(\n {\n shieldInformationBarrierSegmentId: segment.id!,\n } satisfies GetShieldInformationBarrierSegmentMembersQueryParams,\n);" }, { "lang": "python", "label": "List shield information barrier segment members", "source": "client.shield_information_barrier_segment_members.get_shield_information_barrier_segment_members(\n segment.id\n)" } ] }, "post": { "operationId": "post_shield_information_barrier_segment_members", "summary": "Create shield information barrier segment member", "description": "Creates a new shield information barrier segment member.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "A type of the shield barrier segment member.", "type": "string", "example": "shield_information_barrier_segment_member", "enum": [ "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.", "type": "object", "properties": { "id": { "description": "The ID reference of the requesting shield information barrier segment.", "type": "string", "example": "432554" }, "type": { "description": "The type of the shield barrier segment for this member.", "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } } }, "user": { "description": "User to which restriction will be applied.", "allOf": [ { "$ref": "#/components/schemas/User--Base" } ] } }, "required": [ "shield_information_barrier_segment", "user" ] } } } }, "responses": { "201": { "description": "Returns a new shield information barrier segment member object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" } } } }, "404": { "description": "Returns an error if the shield information barrier or segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_members", "tags": [ "Shield information barrier segment members" ], "x-codeSamples": [ { "lang": "curl", "label": "Create shield information barrier segment member", "source": "curl -i -X POST \"https://api.box.com/2.0/shield_information_barrier_segment_members\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"shield_information_barrier_segment\": {\n \"id\": \"432554\",\n \"type\": \"shield_information_barrier_segment\"\n },\n \"user\": {\n \"id\": \"11446498\",\n \"type\": \"user\"\n }\n }'" }, { "lang": "dotnet", "label": "Create shield information barrier segment member", "source": "await client.ShieldInformationBarrierSegmentMembers.CreateShieldInformationBarrierSegmentMemberAsync(requestBody: new CreateShieldInformationBarrierSegmentMemberRequestBody(shieldInformationBarrierSegment: new CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentField() { Id = NullableUtils.Unwrap(segment.Id), Type = CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentTypeField.ShieldInformationBarrierSegment }, user: new UserBase(id: Utils.GetEnvVar(name: \"USER_ID\"))));" }, { "lang": "swift", "label": "Create shield information barrier segment member", "source": "try await client.shieldInformationBarrierSegmentMembers.createShieldInformationBarrierSegmentMember(requestBody: CreateShieldInformationBarrierSegmentMemberRequestBody(shieldInformationBarrierSegment: CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentField(id: segment.id!, type: CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentTypeField.shieldInformationBarrierSegment), user: UserBase(id: Utils.getEnvironmentVariable(name: \"USER_ID\"))))" }, { "lang": "java", "label": "Create shield information barrier segment member", "source": "client.getShieldInformationBarrierSegmentMembers().createShieldInformationBarrierSegmentMember(new CreateShieldInformationBarrierSegmentMemberRequestBody(new CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentField.Builder().id(segment.getId()).type(CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT).build(), new UserBase(getEnvVar(\"USER_ID\"))))" }, { "lang": "node", "label": "Create shield information barrier segment member", "source": "await client.shieldInformationBarrierSegmentMembers.createShieldInformationBarrierSegmentMember(\n {\n shieldInformationBarrierSegment: {\n id: segment.id!,\n type: 'shield_information_barrier_segment' as CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentTypeField,\n } satisfies CreateShieldInformationBarrierSegmentMemberRequestBodyShieldInformationBarrierSegmentField,\n user: new UserBase({ id: getEnvVar('USER_ID') }),\n } satisfies CreateShieldInformationBarrierSegmentMemberRequestBody,\n);" }, { "lang": "python", "label": "Create shield information barrier segment member", "source": "client.shield_information_barrier_segment_members.create_shield_information_barrier_segment_member(\n CreateShieldInformationBarrierSegmentMemberShieldInformationBarrierSegment(\n id=segment.id,\n type=CreateShieldInformationBarrierSegmentMemberShieldInformationBarrierSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT,\n ),\n UserBase(id=get_env_var(\"USER_ID\")),\n)" } ] } }, "/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}": { "get": { "operationId": "get_shield_information_barrier_segment_restrictions_id", "summary": "Get shield information barrier segment restriction by ID", "description": "Retrieves a shield information barrier segment restriction based on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_restriction_id", "in": "path", "description": "The ID of the shield information barrier segment Restriction.", "required": true, "schema": { "type": "string" }, "example": "4563" } ], "responses": { "200": { "description": "Returns the shield information barrier segment restriction object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier segment restriction was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_restrictions", "tags": [ "Shield information barrier segment restrictions" ], "x-codeSamples": [ { "lang": "curl", "label": "Get shield information barrier segment restriction by ID", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_segment_restrictions/4563\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get shield information barrier segment restriction by ID", "source": "await client.ShieldInformationBarrierSegmentRestrictions.GetShieldInformationBarrierSegmentRestrictionByIdAsync(shieldInformationBarrierSegmentRestrictionId: segmentRestrictionId);" }, { "lang": "swift", "label": "Get shield information barrier segment restriction by ID", "source": "try await client.shieldInformationBarrierSegmentRestrictions.getShieldInformationBarrierSegmentRestrictionById(shieldInformationBarrierSegmentRestrictionId: segmentRestrictionId)" }, { "lang": "java", "label": "Get shield information barrier segment restriction by ID", "source": "client.getShieldInformationBarrierSegmentRestrictions().getShieldInformationBarrierSegmentRestrictionById(segmentRestrictionId)" }, { "lang": "node", "label": "Get shield information barrier segment restriction by ID", "source": "await client.shieldInformationBarrierSegmentRestrictions.getShieldInformationBarrierSegmentRestrictionById(\n segmentRestrictionId,\n);" }, { "lang": "python", "label": "Get shield information barrier segment restriction by ID", "source": "client.shield_information_barrier_segment_restrictions.get_shield_information_barrier_segment_restriction_by_id(\n segment_restriction_id\n)" } ] }, "delete": { "operationId": "delete_shield_information_barrier_segment_restrictions_id", "summary": "Delete shield information barrier segment restriction by ID", "description": "Delete shield information barrier segment restriction based on provided ID.", "parameters": [ { "name": "shield_information_barrier_segment_restriction_id", "in": "path", "description": "The ID of the shield information barrier segment Restriction.", "required": true, "schema": { "type": "string" }, "example": "4563" } ], "responses": { "204": { "description": "Empty body in response." }, "404": { "description": "Returns a `not_found` error if the shield information barrier segment restriction was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_restrictions", "tags": [ "Shield information barrier segment restrictions" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete shield information barrier segment restriction by ID", "source": "curl -i -X DELETE \"https://api.box.com/2.0/shield_information_barrier_segment_restrictions/4563\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete shield information barrier segment restriction by ID", "source": "await client.ShieldInformationBarrierSegmentRestrictions.DeleteShieldInformationBarrierSegmentRestrictionByIdAsync(shieldInformationBarrierSegmentRestrictionId: segmentRestrictionId);" }, { "lang": "swift", "label": "Delete shield information barrier segment restriction by ID", "source": "try await client.shieldInformationBarrierSegmentRestrictions.deleteShieldInformationBarrierSegmentRestrictionById(shieldInformationBarrierSegmentRestrictionId: segmentRestrictionId)" }, { "lang": "java", "label": "Delete shield information barrier segment restriction by ID", "source": "client.getShieldInformationBarrierSegmentRestrictions().deleteShieldInformationBarrierSegmentRestrictionById(segmentRestrictionId)" }, { "lang": "node", "label": "Delete shield information barrier segment restriction by ID", "source": "await client.shieldInformationBarrierSegmentRestrictions.deleteShieldInformationBarrierSegmentRestrictionById(\n segmentRestrictionId,\n);" }, { "lang": "python", "label": "Delete shield information barrier segment restriction by ID", "source": "client.shield_information_barrier_segment_restrictions.delete_shield_information_barrier_segment_restriction_by_id(\n segment_restriction_id\n)" } ] } }, "/shield_information_barrier_segment_restrictions": { "get": { "operationId": "get_shield_information_barrier_segment_restrictions", "summary": "List shield information barrier segment restrictions", "description": "Lists shield information barrier segment restrictions based on provided segment ID.", "parameters": [ { "name": "shield_information_barrier_segment_id", "in": "query", "description": "The ID of the shield information barrier segment.", "required": true, "schema": { "type": "string" }, "example": "3423" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a paginated list of shield information barrier segment restriction objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestrictions" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_restrictions", "tags": [ "Shield information barrier segment restrictions" ], "x-codeSamples": [ { "lang": "curl", "label": "List shield information barrier segment restrictions", "source": "curl -i -X GET \"https://api.box.com/2.0/shield_information_barrier_segment_restrictions?shield_information_barrier_segment_id=3423\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List shield information barrier segment restrictions", "source": "await client.ShieldInformationBarrierSegmentRestrictions.GetShieldInformationBarrierSegmentRestrictionsAsync(queryParams: new GetShieldInformationBarrierSegmentRestrictionsQueryParams(shieldInformationBarrierSegmentId: segmentId));" }, { "lang": "swift", "label": "List shield information barrier segment restrictions", "source": "try await client.shieldInformationBarrierSegmentRestrictions.getShieldInformationBarrierSegmentRestrictions(queryParams: GetShieldInformationBarrierSegmentRestrictionsQueryParams(shieldInformationBarrierSegmentId: segmentId))" }, { "lang": "java", "label": "List shield information barrier segment restrictions", "source": "client.getShieldInformationBarrierSegmentRestrictions().getShieldInformationBarrierSegmentRestrictions(new GetShieldInformationBarrierSegmentRestrictionsQueryParams(segmentId))" }, { "lang": "node", "label": "List shield information barrier segment restrictions", "source": "await client.shieldInformationBarrierSegmentRestrictions.getShieldInformationBarrierSegmentRestrictions(\n {\n shieldInformationBarrierSegmentId: segmentId,\n } satisfies GetShieldInformationBarrierSegmentRestrictionsQueryParams,\n);" }, { "lang": "python", "label": "List shield information barrier segment restrictions", "source": "client.shield_information_barrier_segment_restrictions.get_shield_information_barrier_segment_restrictions(\n segment_id\n)" } ] }, "post": { "operationId": "post_shield_information_barrier_segment_restrictions", "summary": "Create shield information barrier segment restriction", "description": "Creates a shield information barrier segment restriction object.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "The type of the shield barrier segment restriction for this member.", "type": "string", "example": "shield_information_barrier_segment_restriction", "enum": [ "shield_information_barrier_segment_restriction" ] }, "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "shield_information_barrier_segment": { "description": "The `type` and `id` of the requested shield information barrier segment.", "type": "object", "properties": { "id": { "description": "The ID reference of the requesting shield information barrier segment.", "type": "string", "example": "1910967" }, "type": { "description": "The type of the shield barrier segment for this member.", "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } } }, "restricted_segment": { "description": "The `type` and `id` of the restricted shield information barrier segment.", "type": "object", "properties": { "id": { "description": "The ID reference of the restricted shield information barrier segment.", "type": "string", "example": "1910967" }, "type": { "description": "The type of the restricted shield information barrier segment.", "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } } } }, "required": [ "type", "shield_information_barrier_segment", "restricted_segment" ] } } } }, "responses": { "201": { "description": "Returns the newly created Shield Information Barrier Segment Restriction object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" } } } }, "404": { "description": "Returns a `not_found` error if the shield information barrier or segment was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "shield_information_barrier_segment_restrictions", "tags": [ "Shield information barrier segment restrictions" ], "x-codeSamples": [ { "lang": "curl", "label": "Create shield information barrier segment restriction", "source": "curl -i -X POST \"https://api.box.com/2.0/shield_information_barrier_segment_restrictions\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"type\": \"shield_information_barrier_segment_restriction\",\n \"shield_information_barrier_segment\": {\n \"id\": \"1910967\",\n \"type\": \"shield_information_barrier_segment\"\n },\n \"restricted_segment\": {\n \"id\": \"1910967\",\n \"type\": \"shield_information_barrier_segment\"\n }\n }'" }, { "lang": "dotnet", "label": "Create shield information barrier segment restriction", "source": "await client.ShieldInformationBarrierSegmentRestrictions.CreateShieldInformationBarrierSegmentRestrictionAsync(requestBody: new CreateShieldInformationBarrierSegmentRestrictionRequestBody(restrictedSegment: new CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentField() { Id = segmentToRestrictId, Type = CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentTypeField.ShieldInformationBarrierSegment }, shieldInformationBarrierSegment: new CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentField() { Id = segmentId, Type = CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentTypeField.ShieldInformationBarrierSegment }, type: CreateShieldInformationBarrierSegmentRestrictionRequestBodyTypeField.ShieldInformationBarrierSegmentRestriction));" }, { "lang": "swift", "label": "Create shield information barrier segment restriction", "source": "try await client.shieldInformationBarrierSegmentRestrictions.createShieldInformationBarrierSegmentRestriction(requestBody: CreateShieldInformationBarrierSegmentRestrictionRequestBody(restrictedSegment: CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentField(id: segmentToRestrictId, type: CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentTypeField.shieldInformationBarrierSegment), shieldInformationBarrierSegment: CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentField(id: segmentId, type: CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentTypeField.shieldInformationBarrierSegment), type: CreateShieldInformationBarrierSegmentRestrictionRequestBodyTypeField.shieldInformationBarrierSegmentRestriction))" }, { "lang": "java", "label": "Create shield information barrier segment restriction", "source": "client.getShieldInformationBarrierSegmentRestrictions().createShieldInformationBarrierSegmentRestriction(new CreateShieldInformationBarrierSegmentRestrictionRequestBody.Builder(new CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentField.Builder().id(segmentId).type(CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT).build(), new CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentField.Builder().id(segmentToRestrictId).type(CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT).build()).type(CreateShieldInformationBarrierSegmentRestrictionRequestBodyTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTION).build())" }, { "lang": "node", "label": "Create shield information barrier segment restriction", "source": "await client.shieldInformationBarrierSegmentRestrictions.createShieldInformationBarrierSegmentRestriction(\n {\n restrictedSegment: {\n id: segmentToRestrictId,\n type: 'shield_information_barrier_segment' as CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentTypeField,\n } satisfies CreateShieldInformationBarrierSegmentRestrictionRequestBodyRestrictedSegmentField,\n shieldInformationBarrierSegment: {\n id: segmentId,\n type: 'shield_information_barrier_segment' as CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentTypeField,\n } satisfies CreateShieldInformationBarrierSegmentRestrictionRequestBodyShieldInformationBarrierSegmentField,\n type: 'shield_information_barrier_segment_restriction' as CreateShieldInformationBarrierSegmentRestrictionRequestBodyTypeField,\n } satisfies CreateShieldInformationBarrierSegmentRestrictionRequestBodyInput,\n);" }, { "lang": "python", "label": "Create shield information barrier segment restriction", "source": "client.shield_information_barrier_segment_restrictions.create_shield_information_barrier_segment_restriction(\n CreateShieldInformationBarrierSegmentRestrictionShieldInformationBarrierSegment(\n id=segment_id,\n type=CreateShieldInformationBarrierSegmentRestrictionShieldInformationBarrierSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT,\n ),\n CreateShieldInformationBarrierSegmentRestrictionRestrictedSegment(\n id=segment_to_restrict_id,\n type=CreateShieldInformationBarrierSegmentRestrictionRestrictedSegmentTypeField.SHIELD_INFORMATION_BARRIER_SEGMENT,\n ),\n type=CreateShieldInformationBarrierSegmentRestrictionType.SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTION,\n)" } ] } }, "/device_pinners/{device_pinner_id}": { "get": { "operationId": "get_device_pinners_id", "summary": "Get device pin", "description": "Retrieves information about an individual device pin.", "parameters": [ { "name": "device_pinner_id", "in": "path", "description": "The ID of the device pin.", "required": true, "schema": { "type": "string" }, "example": "2324234" } ], "responses": { "200": { "description": "Returns information about a single device pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePinner" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "device_pinners", "tags": [ "Device pinners" ], "x-codeSamples": [ { "lang": "curl", "label": "Get device pin", "source": "curl -i -X GET \"https://api.box.com/2.0/device_pinners/2324234\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get device pin", "source": "await client.DevicePinners.GetDevicePinnerByIdAsync(devicePinnerId: devicePinnerId);" }, { "lang": "swift", "label": "Get device pin", "source": "try await client.devicePinners.getDevicePinnerById(devicePinnerId: devicePinnerId)" }, { "lang": "java", "label": "Get device pin", "source": "client.getDevicePinners().getDevicePinnerById(devicePinnerId)" }, { "lang": "node", "label": "Get device pin", "source": "await client.devicePinners.getDevicePinnerById(devicePinnerId);" }, { "lang": "python", "label": "Get device pin", "source": "client.device_pinners.get_device_pinner_by_id(device_pinner_id)" } ] }, "delete": { "operationId": "delete_device_pinners_id", "summary": "Remove device pin", "description": "Deletes an individual device pin.", "parameters": [ { "name": "device_pinner_id", "in": "path", "description": "The ID of the device pin.", "required": true, "schema": { "type": "string" }, "example": "2324234" } ], "responses": { "204": { "description": "Returns an empty response when the pin has been deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "device_pinners", "tags": [ "Device pinners" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove device pin", "source": "curl -i -X DELETE \"https://api.box.com/2.0/device_pinners/2324234\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove device pin", "source": "await client.DevicePinners.DeleteDevicePinnerByIdAsync(devicePinnerId: devicePinnerId);" }, { "lang": "swift", "label": "Remove device pin", "source": "try await client.devicePinners.deleteDevicePinnerById(devicePinnerId: devicePinnerId)" }, { "lang": "java", "label": "Remove device pin", "source": "client.getDevicePinners().deleteDevicePinnerById(devicePinnerId)" }, { "lang": "node", "label": "Remove device pin", "source": "await client.devicePinners.deleteDevicePinnerById(devicePinnerId);" }, { "lang": "python", "label": "Remove device pin", "source": "client.device_pinners.delete_device_pinner_by_id(device_pinner_id)" } ] } }, "/enterprises/{enterprise_id}/device_pinners": { "get": { "operationId": "get_enterprises_id_device_pinners", "summary": "List enterprise device pins", "description": "Retrieves all the device pins within an enterprise.\n\nThe user must have admin privileges, and the application needs the \"manage enterprise\" scope to make this call.", "parameters": [ { "name": "enterprise_id", "in": "path", "description": "The ID of the enterprise.", "required": true, "schema": { "type": "string" }, "example": "3442311" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "direction", "in": "query", "description": "The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order.", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" } ], "responses": { "200": { "description": "Returns a list of device pins for a given enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePinners" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "device_pinners", "tags": [ "Device pinners" ], "x-codeSamples": [ { "lang": "curl", "label": "List enterprise device pins", "source": "curl -i -X GET \"https://api.box.com/2.0/enterprises/3442311/device_pinners\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List enterprise device pins", "source": "await client.DevicePinners.GetEnterpriseDevicePinnersAsync(enterpriseId: enterpriseId);" }, { "lang": "swift", "label": "List enterprise device pins", "source": "try await client.devicePinners.getEnterpriseDevicePinners(enterpriseId: enterpriseId)" }, { "lang": "java", "label": "List enterprise device pins", "source": "client.getDevicePinners().getEnterpriseDevicePinners(enterpriseId)" }, { "lang": "node", "label": "List enterprise device pins", "source": "await client.devicePinners.getEnterpriseDevicePinners(enterpriseId);" }, { "lang": "python", "label": "List enterprise device pins", "source": "client.device_pinners.get_enterprise_device_pinners(enterprise_id)" } ] } }, "/terms_of_services": { "get": { "operationId": "get_terms_of_services", "summary": "List terms of services", "description": "Returns the current terms of service text and settings for the enterprise.", "parameters": [ { "name": "tos_type", "in": "query", "description": "Limits the results to the terms of service of the given type.", "required": false, "schema": { "type": "string", "enum": [ "external", "managed" ] }, "example": "managed" } ], "responses": { "200": { "description": "Returns a collection of terms of service text and settings for the enterprise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServices" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "terms_of_services", "tags": [ "Terms of service" ], "x-codeSamples": [ { "lang": "curl", "label": "List terms of services", "source": "curl -i -X GET \"https://api.box.com/2.0/terms_of_services\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List terms of services", "source": "await client.TermsOfServices.GetTermsOfServiceAsync();" }, { "lang": "swift", "label": "List terms of services", "source": "try await client.termsOfServices.getTermsOfService()" }, { "lang": "java", "label": "List terms of services", "source": "client.getTermsOfServices().getTermsOfService()" }, { "lang": "node", "label": "List terms of services", "source": "await client.termsOfServices.getTermsOfService();" }, { "lang": "python", "label": "List terms of services", "source": "client.terms_of_services.get_terms_of_service()" } ] }, "post": { "operationId": "post_terms_of_services", "summary": "Create terms of service", "description": "Creates a terms of service for a given enterprise and type of user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Whether this terms of service is active.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ] }, "tos_type": { "description": "The type of user to set the terms of service for.", "type": "string", "example": "managed", "enum": [ "external", "managed" ] }, "text": { "description": "The terms of service text to display to users.\n\nThe text can be set to empty if the `status` is set to `disabled`.", "type": "string", "example": "By collaborating on this file you are accepting..." } }, "required": [ "status", "text" ] } } } }, "responses": { "200": { "description": "Returns a new task object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfService" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "terms_of_services", "tags": [ "Terms of service" ], "x-codeSamples": [ { "lang": "curl", "label": "Create terms of service", "source": "curl -i -X POST \"https://api.box.com/2.0/terms_of_services\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"status\": \"enabled\",\n \"text\": \"By collaborating on this file you are accepting...\"\n }'" }, { "lang": "dotnet", "label": "Create terms of service", "source": "await client.TermsOfServices.CreateTermsOfServiceAsync(requestBody: new CreateTermsOfServiceRequestBody(status: CreateTermsOfServiceRequestBodyStatusField.Disabled, text: \"Test TOS\") { TosType = CreateTermsOfServiceRequestBodyTosTypeField.Managed });" }, { "lang": "swift", "label": "Create terms of service", "source": "try await client.termsOfServices.createTermsOfService(requestBody: CreateTermsOfServiceRequestBody(status: CreateTermsOfServiceRequestBodyStatusField.disabled, tosType: CreateTermsOfServiceRequestBodyTosTypeField.managed, text: \"Test TOS\"))" }, { "lang": "java", "label": "Create terms of service", "source": "client.getTermsOfServices().createTermsOfService(new CreateTermsOfServiceRequestBody.Builder(CreateTermsOfServiceRequestBodyStatusField.DISABLED, \"Test TOS\").tosType(CreateTermsOfServiceRequestBodyTosTypeField.MANAGED).build())" }, { "lang": "node", "label": "Create terms of service", "source": "await client.termsOfServices.createTermsOfService({\n status: 'disabled' as CreateTermsOfServiceRequestBodyStatusField,\n tosType: 'managed' as CreateTermsOfServiceRequestBodyTosTypeField,\n text: 'Test TOS',\n} satisfies CreateTermsOfServiceRequestBody);" }, { "lang": "python", "label": "Create terms of service", "source": "client.terms_of_services.create_terms_of_service(\n CreateTermsOfServiceStatus.DISABLED,\n \"Test TOS\",\n tos_type=CreateTermsOfServiceTosType.MANAGED,\n)" } ] } }, "/terms_of_services/{terms_of_service_id}": { "get": { "operationId": "get_terms_of_services_id", "summary": "Get terms of service", "description": "Fetches a specific terms of service.", "parameters": [ { "name": "terms_of_service_id", "in": "path", "description": "The ID of the terms of service.", "required": true, "schema": { "type": "string" }, "example": "324234" } ], "responses": { "200": { "description": "Returns a terms of service object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfService" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "terms_of_services", "tags": [ "Terms of service" ], "x-codeSamples": [ { "lang": "curl", "label": "Get terms of service", "source": "curl -i -X GET \"https://api.box.com/2.0/terms_of_services/324234\" \\\n -H \"authorization: Bearer \"" } ] }, "put": { "operationId": "put_terms_of_services_id", "summary": "Update terms of service", "description": "Updates a specific terms of service.", "parameters": [ { "name": "terms_of_service_id", "in": "path", "description": "The ID of the terms of service.", "required": true, "schema": { "type": "string" }, "example": "324234" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Whether this terms of service is active.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ] }, "text": { "description": "The terms of service text to display to users.\n\nThe text can be set to empty if the `status` is set to `disabled`.", "type": "string", "example": "By collaborating on this file you are accepting..." } }, "required": [ "status", "text" ] } } } }, "responses": { "200": { "description": "Returns an updated terms of service object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfService" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "terms_of_services", "tags": [ "Terms of service" ], "x-codeSamples": [ { "lang": "curl", "label": "Update terms of service", "source": "curl -i -X PUT \"https://api.box.com/2.0/terms_of_services/324234\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"status\": \"enabled\",\n \"text\": \"By collaborating on this file you are accepting...\"\n }'" }, { "lang": "dotnet", "label": "Update terms of service", "source": "await client.TermsOfServices.UpdateTermsOfServiceByIdAsync(termsOfServiceId: tos.Id, requestBody: new UpdateTermsOfServiceByIdRequestBody(status: UpdateTermsOfServiceByIdRequestBodyStatusField.Disabled, text: \"TOS\"));" }, { "lang": "swift", "label": "Update terms of service", "source": "try await client.termsOfServices.updateTermsOfServiceById(termsOfServiceId: tos.id, requestBody: UpdateTermsOfServiceByIdRequestBody(status: UpdateTermsOfServiceByIdRequestBodyStatusField.disabled, text: \"TOS\"))" }, { "lang": "java", "label": "Update terms of service", "source": "client.getTermsOfServices().updateTermsOfServiceById(tos.getId(), new UpdateTermsOfServiceByIdRequestBody(UpdateTermsOfServiceByIdRequestBodyStatusField.DISABLED, \"TOS\"))" }, { "lang": "node", "label": "Update terms of service", "source": "await client.termsOfServices.updateTermsOfServiceById(tos.id, {\n status: 'disabled' as UpdateTermsOfServiceByIdRequestBodyStatusField,\n text: 'TOS',\n} satisfies UpdateTermsOfServiceByIdRequestBody);" }, { "lang": "python", "label": "Update terms of service", "source": "client.terms_of_services.update_terms_of_service_by_id(\n tos.id, UpdateTermsOfServiceByIdStatus.DISABLED, \"TOS\"\n)" } ] } }, "/terms_of_service_user_statuses": { "get": { "operationId": "get_terms_of_service_user_statuses", "summary": "List terms of service user statuses", "description": "Retrieves an overview of users and their status for a terms of service, including Whether they have accepted the terms and when.", "parameters": [ { "name": "tos_id", "in": "query", "description": "The ID of the terms of service.", "required": true, "schema": { "type": "string" }, "example": "324234" }, { "name": "user_id", "in": "query", "description": "Limits results to the given user ID.", "required": false, "schema": { "type": "string" }, "example": "123334" } ], "responses": { "200": { "description": "Returns a list of terms of service statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServiceUserStatuses" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "terms_of_service_user_statuses", "tags": [ "Terms of service user statuses" ], "x-codeSamples": [ { "lang": "curl", "label": "List terms of service user statuses", "source": "curl -i -X GET \"https://api.box.com/2.0/terms_of_service_user_statuses?tos_id=324234\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List terms of service user statuses", "source": "await client.TermsOfServiceUserStatuses.GetTermsOfServiceUserStatusesAsync(queryParams: new GetTermsOfServiceUserStatusesQueryParams(tosId: tos.Id) { UserId = user.Id });" }, { "lang": "swift", "label": "List terms of service user statuses", "source": "try await client.termsOfServiceUserStatuses.getTermsOfServiceUserStatuses(queryParams: GetTermsOfServiceUserStatusesQueryParams(tosId: tos.id, userId: user.id))" }, { "lang": "java", "label": "List terms of service user statuses", "source": "client.getTermsOfServiceUserStatuses().getTermsOfServiceUserStatuses(new GetTermsOfServiceUserStatusesQueryParams.Builder(tos.getId()).userId(user.getId()).build())" }, { "lang": "node", "label": "List terms of service user statuses", "source": "await client.termsOfServiceUserStatuses.getTermsOfServiceUserStatuses({\n tosId: tos.id,\n userId: user.id,\n} satisfies GetTermsOfServiceUserStatusesQueryParams);" }, { "lang": "python", "label": "List terms of service user statuses", "source": "client.terms_of_service_user_statuses.get_terms_of_service_user_statuses(\n tos.id, user_id=user.id\n)" } ] }, "post": { "operationId": "post_terms_of_service_user_statuses", "summary": "Create terms of service status for new user", "description": "Sets the status for a terms of service for a user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tos": { "description": "The terms of service to set the status for.", "type": "object", "properties": { "type": { "description": "The type of object.", "type": "string", "example": "terms_of_service", "enum": [ "terms_of_service" ] }, "id": { "description": "The ID of terms of service.", "type": "string", "example": "1232132" } }, "required": [ "id", "type" ] }, "user": { "description": "The user to set the status for.", "type": "object", "properties": { "type": { "description": "The type of object.", "type": "string", "example": "user", "enum": [ "user" ] }, "id": { "description": "The ID of user.", "type": "string", "example": "3423423" } }, "required": [ "id", "type" ] }, "is_accepted": { "description": "Whether the user has accepted the terms.", "type": "boolean", "example": true } }, "required": [ "tos", "user", "is_accepted" ] } } } }, "responses": { "201": { "description": "Returns a terms of service status object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServiceUserStatus" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "terms_of_service_user_statuses", "tags": [ "Terms of service user statuses" ], "x-codeSamples": [ { "lang": "curl", "label": "Create terms of service status for new user", "source": "curl -i -X POST \"https://api.box.com/2.0/terms_of_service_user_statuses\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"tos\": {\n \"type\": \"terms_of_service\",\n \"id\": \"1232132\"\n },\n \"user\": {\n \"type\": \"user\",\n \"id\": \"3423423\"\n },\n \"is_accepted\": true\n }'" }, { "lang": "dotnet", "label": "Create terms of service status for new user", "source": "await client.TermsOfServiceUserStatuses.CreateTermsOfServiceStatusForUserAsync(requestBody: new CreateTermsOfServiceStatusForUserRequestBody(tos: new CreateTermsOfServiceStatusForUserRequestBodyTosField(id: tos.Id), user: new CreateTermsOfServiceStatusForUserRequestBodyUserField(id: user.Id), isAccepted: false));" }, { "lang": "swift", "label": "Create terms of service status for new user", "source": "try await client.termsOfServiceUserStatuses.createTermsOfServiceStatusForUser(requestBody: CreateTermsOfServiceStatusForUserRequestBody(tos: CreateTermsOfServiceStatusForUserRequestBodyTosField(id: tos.id), user: CreateTermsOfServiceStatusForUserRequestBodyUserField(id: user.id), isAccepted: false))" }, { "lang": "java", "label": "Create terms of service status for new user", "source": "client.getTermsOfServiceUserStatuses().createTermsOfServiceStatusForUser(new CreateTermsOfServiceStatusForUserRequestBody(new CreateTermsOfServiceStatusForUserRequestBodyTosField(tos.getId()), new CreateTermsOfServiceStatusForUserRequestBodyUserField(user.getId()), false))" }, { "lang": "node", "label": "Create terms of service status for new user", "source": "await client.termsOfServiceUserStatuses.createTermsOfServiceStatusForUser({\n tos: new CreateTermsOfServiceStatusForUserRequestBodyTosField({ id: tos.id }),\n user: new CreateTermsOfServiceStatusForUserRequestBodyUserField({\n id: user.id,\n }),\n isAccepted: false,\n} satisfies CreateTermsOfServiceStatusForUserRequestBody);" }, { "lang": "python", "label": "Create terms of service status for new user", "source": "client.terms_of_service_user_statuses.create_terms_of_service_status_for_user(\n CreateTermsOfServiceStatusForUserTos(id=tos.id),\n CreateTermsOfServiceStatusForUserUser(id=user.id),\n False,\n)" } ] } }, "/terms_of_service_user_statuses/{terms_of_service_user_status_id}": { "put": { "operationId": "put_terms_of_service_user_statuses_id", "summary": "Update terms of service status for existing user", "description": "Updates the status for a terms of service for a user.", "parameters": [ { "name": "terms_of_service_user_status_id", "in": "path", "description": "The ID of the terms of service status.", "required": true, "schema": { "type": "string" }, "example": "324234" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_accepted": { "description": "Whether the user has accepted the terms.", "type": "boolean", "example": true } }, "required": [ "is_accepted" ] } } } }, "responses": { "200": { "description": "Returns the updated terms of service status object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServiceUserStatus" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "terms_of_service_user_statuses", "tags": [ "Terms of service user statuses" ], "x-codeSamples": [ { "lang": "curl", "label": "Update terms of service status for existing user", "source": "curl -i -X PUT \"https://api.box.com/2.0/terms_of_service_user_statuses/324234\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"is_accepted\": true\n }'" }, { "lang": "dotnet", "label": "Update terms of service status for existing user", "source": "await client.TermsOfServiceUserStatuses.UpdateTermsOfServiceStatusForUserByIdAsync(termsOfServiceUserStatusId: createdTosUserStatus.Id, requestBody: new UpdateTermsOfServiceStatusForUserByIdRequestBody(isAccepted: true));" }, { "lang": "swift", "label": "Update terms of service status for existing user", "source": "try await client.termsOfServiceUserStatuses.updateTermsOfServiceStatusForUserById(termsOfServiceUserStatusId: createdTosUserStatus.id, requestBody: UpdateTermsOfServiceStatusForUserByIdRequestBody(isAccepted: true))" }, { "lang": "java", "label": "Update terms of service status for existing user", "source": "client.getTermsOfServiceUserStatuses().updateTermsOfServiceStatusForUserById(createdTosUserStatus.getId(), new UpdateTermsOfServiceStatusForUserByIdRequestBody(true))" }, { "lang": "node", "label": "Update terms of service status for existing user", "source": "await client.termsOfServiceUserStatuses.updateTermsOfServiceStatusForUserById(\n createdTosUserStatus.id,\n {\n isAccepted: true,\n } satisfies UpdateTermsOfServiceStatusForUserByIdRequestBody,\n);" }, { "lang": "python", "label": "Update terms of service status for existing user", "source": "client.terms_of_service_user_statuses.update_terms_of_service_status_for_user_by_id(\n created_tos_user_status.id, True\n)" } ] } }, "/collaboration_whitelist_entries": { "get": { "operationId": "get_collaboration_whitelist_entries", "summary": "List allowed collaboration domains", "description": "Returns the list domains that have been deemed safe to create collaborations for within the current enterprise.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of domains that are allowed for collaboration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistEntries" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_entries", "tags": [ "Domain restrictions for collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "List allowed collaboration domains", "source": "curl -i -X GET \"https://api.box.com/2.0/collaboration_whitelist_entries\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List allowed collaboration domains", "source": "await client.CollaborationAllowlistEntries.GetCollaborationWhitelistEntriesAsync();" }, { "lang": "swift", "label": "List allowed collaboration domains", "source": "try await client.collaborationAllowlistEntries.getCollaborationWhitelistEntries()" }, { "lang": "java", "label": "List allowed collaboration domains", "source": "client.getCollaborationAllowlistEntries().getCollaborationWhitelistEntries()" }, { "lang": "node", "label": "List allowed collaboration domains", "source": "await client.collaborationAllowlistEntries.getCollaborationWhitelistEntries();" }, { "lang": "python", "label": "List allowed collaboration domains", "source": "client.collaboration_allowlist_entries.get_collaboration_whitelist_entries()" } ] }, "post": { "operationId": "post_collaboration_whitelist_entries", "summary": "Add domain to list of allowed collaboration domains", "description": "Creates a new entry in the list of allowed domains to allow collaboration for.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "description": "The domain to add to the list of allowed domains.", "type": "string", "example": "example.com" }, "direction": { "description": "The direction in which to allow collaborations.", "type": "string", "example": "inbound", "enum": [ "inbound", "outbound", "both" ] } }, "required": [ "domain", "direction" ] } } } }, "responses": { "200": { "description": "Returns a new entry on the list of allowed domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistEntry" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_entries", "tags": [ "Domain restrictions for collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "Add domain to list of allowed collaboration domains", "source": "curl -i -X POST \"https://api.box.com/2.0/collaboration_whitelist_entries\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"domain\": \"example.com\",\n \"direction\": \"inbound\"\n }'" }, { "lang": "dotnet", "label": "Add domain to list of allowed collaboration domains", "source": "await client.CollaborationAllowlistEntries.CreateCollaborationWhitelistEntryAsync(requestBody: new CreateCollaborationWhitelistEntryRequestBody(direction: CreateCollaborationWhitelistEntryRequestBodyDirectionField.Inbound, domain: domain));" }, { "lang": "swift", "label": "Add domain to list of allowed collaboration domains", "source": "try await client.collaborationAllowlistEntries.createCollaborationWhitelistEntry(requestBody: CreateCollaborationWhitelistEntryRequestBody(direction: CreateCollaborationWhitelistEntryRequestBodyDirectionField.inbound, domain: domain))" }, { "lang": "java", "label": "Add domain to list of allowed collaboration domains", "source": "client.getCollaborationAllowlistEntries().createCollaborationWhitelistEntry(new CreateCollaborationWhitelistEntryRequestBody(domain, CreateCollaborationWhitelistEntryRequestBodyDirectionField.INBOUND))" }, { "lang": "node", "label": "Add domain to list of allowed collaboration domains", "source": "await client.collaborationAllowlistEntries.createCollaborationWhitelistEntry({\n direction:\n 'inbound' as CreateCollaborationWhitelistEntryRequestBodyDirectionField,\n domain: domain,\n} satisfies CreateCollaborationWhitelistEntryRequestBody);" }, { "lang": "python", "label": "Add domain to list of allowed collaboration domains", "source": "client.collaboration_allowlist_entries.create_collaboration_whitelist_entry(\n domain, CreateCollaborationWhitelistEntryDirection.INBOUND\n)" } ] } }, "/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}": { "get": { "operationId": "get_collaboration_whitelist_entries_id", "summary": "Get allowed collaboration domain", "description": "Returns a domain that has been deemed safe to create collaborations for within the current enterprise.", "parameters": [ { "name": "collaboration_whitelist_entry_id", "in": "path", "description": "The ID of the entry in the list.", "required": true, "schema": { "type": "string" }, "example": "213123" } ], "responses": { "200": { "description": "Returns an entry on the list of allowed domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistEntry" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_entries", "tags": [ "Domain restrictions for collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "Get allowed collaboration domain", "source": "curl -i -X GET \"https://api.box.com/2.0/collaboration_whitelist_entries/213123\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get allowed collaboration domain", "source": "await client.CollaborationAllowlistEntries.GetCollaborationWhitelistEntryByIdAsync(collaborationWhitelistEntryId: NullableUtils.Unwrap(newEntry.Id));" }, { "lang": "swift", "label": "Get allowed collaboration domain", "source": "try await client.collaborationAllowlistEntries.getCollaborationWhitelistEntryById(collaborationWhitelistEntryId: newEntry.id!)" }, { "lang": "java", "label": "Get allowed collaboration domain", "source": "client.getCollaborationAllowlistEntries().getCollaborationWhitelistEntryById(newEntry.getId())" }, { "lang": "node", "label": "Get allowed collaboration domain", "source": "await client.collaborationAllowlistEntries.getCollaborationWhitelistEntryById(\n newEntry.id!,\n);" }, { "lang": "python", "label": "Get allowed collaboration domain", "source": "client.collaboration_allowlist_entries.get_collaboration_whitelist_entry_by_id(\n new_entry.id\n)" } ] }, "delete": { "operationId": "delete_collaboration_whitelist_entries_id", "summary": "Remove domain from list of allowed collaboration domains", "description": "Removes a domain from the list of domains that have been deemed safe to create collaborations for within the current enterprise.", "parameters": [ { "name": "collaboration_whitelist_entry_id", "in": "path", "description": "The ID of the entry in the list.", "required": true, "schema": { "type": "string" }, "example": "213123" } ], "responses": { "204": { "description": "A blank response is returned if the entry was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_entries", "tags": [ "Domain restrictions for collaborations" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove domain from list of allowed collaboration domains", "source": "curl -i -X DELETE \"https://api.box.com/2.0/collaboration_whitelist_entries/213123\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove domain from list of allowed collaboration domains", "source": "await client.CollaborationAllowlistEntries.DeleteCollaborationWhitelistEntryByIdAsync(collaborationWhitelistEntryId: NullableUtils.Unwrap(entry.Id));" }, { "lang": "swift", "label": "Remove domain from list of allowed collaboration domains", "source": "try await client.collaborationAllowlistEntries.deleteCollaborationWhitelistEntryById(collaborationWhitelistEntryId: entry.id!)" }, { "lang": "java", "label": "Remove domain from list of allowed collaboration domains", "source": "client.getCollaborationAllowlistEntries().deleteCollaborationWhitelistEntryById(entry.getId())" }, { "lang": "node", "label": "Remove domain from list of allowed collaboration domains", "source": "await client.collaborationAllowlistEntries.deleteCollaborationWhitelistEntryById(\n entry.id!,\n);" }, { "lang": "python", "label": "Remove domain from list of allowed collaboration domains", "source": "client.collaboration_allowlist_entries.delete_collaboration_whitelist_entry_by_id(\n entry.id\n)" } ] } }, "/collaboration_whitelist_exempt_targets": { "get": { "operationId": "get_collaboration_whitelist_exempt_targets", "summary": "List users exempt from collaboration domain restrictions", "description": "Returns a list of users who have been exempt from the collaboration domain restrictions.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of user exemptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTargets" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_exempt_targets", "tags": [ "Domain restrictions (User exemptions)" ], "x-codeSamples": [ { "lang": "curl", "label": "List users exempt from collaboration domain restrictions", "source": "curl -i -X GET \"https://api.box.com/2.0/collaboration_whitelist_exempt_targets\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List users exempt from collaboration domain restrictions", "source": "await client.CollaborationAllowlistExemptTargets.GetCollaborationWhitelistExemptTargetsAsync();" }, { "lang": "swift", "label": "List users exempt from collaboration domain restrictions", "source": "try await client.collaborationAllowlistExemptTargets.getCollaborationWhitelistExemptTargets()" }, { "lang": "java", "label": "List users exempt from collaboration domain restrictions", "source": "client.getCollaborationAllowlistExemptTargets().getCollaborationWhitelistExemptTargets()" }, { "lang": "node", "label": "List users exempt from collaboration domain restrictions", "source": "await client.collaborationAllowlistExemptTargets.getCollaborationWhitelistExemptTargets();" }, { "lang": "python", "label": "List users exempt from collaboration domain restrictions", "source": "client.collaboration_allowlist_exempt_targets.get_collaboration_whitelist_exempt_targets()" } ] }, "post": { "operationId": "post_collaboration_whitelist_exempt_targets", "summary": "Create user exemption from collaboration domain restrictions", "description": "Exempts a user from the restrictions set out by the allowed list of domains for collaborations.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "description": "The user to exempt.", "type": "object", "properties": { "id": { "description": "The ID of the user to exempt.", "type": "string", "example": "23522323" } }, "required": [ "id" ] } }, "required": [ "user" ] } } } }, "responses": { "200": { "description": "Returns a new exemption entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_exempt_targets", "tags": [ "Domain restrictions (User exemptions)" ], "x-codeSamples": [ { "lang": "curl", "label": "Create user exemption from collaboration domain restrictions", "source": "curl -i -X POST \"https://api.box.com/2.0/collaboration_whitelist_exempt_targets\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"user\": {\n \"id\": \"23522323\"\n }\n }'" }, { "lang": "dotnet", "label": "Create user exemption from collaboration domain restrictions", "source": "await client.CollaborationAllowlistExemptTargets.CreateCollaborationWhitelistExemptTargetAsync(requestBody: new CreateCollaborationWhitelistExemptTargetRequestBody(user: new CreateCollaborationWhitelistExemptTargetRequestBodyUserField(id: user.Id)));" }, { "lang": "swift", "label": "Create user exemption from collaboration domain restrictions", "source": "try await client.collaborationAllowlistExemptTargets.createCollaborationWhitelistExemptTarget(requestBody: CreateCollaborationWhitelistExemptTargetRequestBody(user: CreateCollaborationWhitelistExemptTargetRequestBodyUserField(id: user.id)))" }, { "lang": "java", "label": "Create user exemption from collaboration domain restrictions", "source": "client.getCollaborationAllowlistExemptTargets().createCollaborationWhitelistExemptTarget(new CreateCollaborationWhitelistExemptTargetRequestBody(new CreateCollaborationWhitelistExemptTargetRequestBodyUserField(user.getId())))" }, { "lang": "node", "label": "Create user exemption from collaboration domain restrictions", "source": "await client.collaborationAllowlistExemptTargets.createCollaborationWhitelistExemptTarget(\n {\n user: {\n id: user.id,\n } satisfies CreateCollaborationWhitelistExemptTargetRequestBodyUserField,\n } satisfies CreateCollaborationWhitelistExemptTargetRequestBody,\n);" }, { "lang": "python", "label": "Create user exemption from collaboration domain restrictions", "source": "client.collaboration_allowlist_exempt_targets.create_collaboration_whitelist_exempt_target(\n CreateCollaborationWhitelistExemptTargetUser(id=user.id)\n)" } ] } }, "/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}": { "get": { "operationId": "get_collaboration_whitelist_exempt_targets_id", "summary": "Get user exempt from collaboration domain restrictions", "description": "Returns a users who has been exempt from the collaboration domain restrictions.", "parameters": [ { "name": "collaboration_whitelist_exempt_target_id", "in": "path", "description": "The ID of the exemption to the list.", "required": true, "schema": { "type": "string" }, "example": "984923" } ], "responses": { "200": { "description": "Returns the user's exempted from the list of collaboration domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_exempt_targets", "tags": [ "Domain restrictions (User exemptions)" ], "x-codeSamples": [ { "lang": "curl", "label": "Get user exempt from collaboration domain restrictions", "source": "curl -i -X GET \"https://api.box.com/2.0/collaboration_whitelist_exempt_targets/984923\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get user exempt from collaboration domain restrictions", "source": "await client.CollaborationAllowlistExemptTargets.GetCollaborationWhitelistExemptTargetByIdAsync(collaborationWhitelistExemptTargetId: NullableUtils.Unwrap(newExemptTarget.Id));" }, { "lang": "swift", "label": "Get user exempt from collaboration domain restrictions", "source": "try await client.collaborationAllowlistExemptTargets.getCollaborationWhitelistExemptTargetById(collaborationWhitelistExemptTargetId: newExemptTarget.id!)" }, { "lang": "java", "label": "Get user exempt from collaboration domain restrictions", "source": "client.getCollaborationAllowlistExemptTargets().getCollaborationWhitelistExemptTargetById(newExemptTarget.getId())" }, { "lang": "node", "label": "Get user exempt from collaboration domain restrictions", "source": "await client.collaborationAllowlistExemptTargets.getCollaborationWhitelistExemptTargetById(\n newExemptTarget.id!,\n);" }, { "lang": "python", "label": "Get user exempt from collaboration domain restrictions", "source": "client.collaboration_allowlist_exempt_targets.get_collaboration_whitelist_exempt_target_by_id(\n new_exempt_target.id\n)" } ] }, "delete": { "operationId": "delete_collaboration_whitelist_exempt_targets_id", "summary": "Remove user from list of users exempt from domain restrictions", "description": "Removes a user's exemption from the restrictions set out by the allowed list of domains for collaborations.", "parameters": [ { "name": "collaboration_whitelist_exempt_target_id", "in": "path", "description": "The ID of the exemption to the list.", "required": true, "schema": { "type": "string" }, "example": "984923" } ], "responses": { "204": { "description": "A blank response is returned if the exemption was successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "collaboration_allowlist_exempt_targets", "tags": [ "Domain restrictions (User exemptions)" ], "x-codeSamples": [ { "lang": "curl", "label": "Remove user from list of users exempt from domain restrictions", "source": "curl -i -X DELETE \"https://api.box.com/2.0/collaboration_whitelist_exempt_targets/984923\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove user from list of users exempt from domain restrictions", "source": "await client.CollaborationAllowlistExemptTargets.DeleteCollaborationWhitelistExemptTargetByIdAsync(collaborationWhitelistExemptTargetId: NullableUtils.Unwrap(exemptTarget.Id));" }, { "lang": "swift", "label": "Remove user from list of users exempt from domain restrictions", "source": "try await client.collaborationAllowlistExemptTargets.deleteCollaborationWhitelistExemptTargetById(collaborationWhitelistExemptTargetId: exemptTarget.id!)" }, { "lang": "java", "label": "Remove user from list of users exempt from domain restrictions", "source": "client.getCollaborationAllowlistExemptTargets().deleteCollaborationWhitelistExemptTargetById(exemptTarget.getId())" }, { "lang": "node", "label": "Remove user from list of users exempt from domain restrictions", "source": "await client.collaborationAllowlistExemptTargets.deleteCollaborationWhitelistExemptTargetById(\n exemptTarget.id!,\n);" }, { "lang": "python", "label": "Remove user from list of users exempt from domain restrictions", "source": "client.collaboration_allowlist_exempt_targets.delete_collaboration_whitelist_exempt_target_by_id(\n exempt_target.id\n)" } ] } }, "/storage_policies": { "get": { "operationId": "get_storage_policies", "summary": "List storage policies", "description": "Fetches all the storage policies in the enterprise.", "parameters": [ { "name": "fields", "in": "query", "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.\n\nBe 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.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "id", "type", "name" ], "explode": false }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of storage policies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicies" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "storage_policies", "tags": [ "Standard and Zones Storage Policies" ], "x-codeSamples": [ { "lang": "curl", "label": "List storage policies", "source": "curl -i -X GET \"https://api.box.com/2.0/storage_policies\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List storage policies", "source": "await client.StoragePolicies.GetStoragePoliciesAsync();" }, { "lang": "swift", "label": "List storage policies", "source": "try await client.storagePolicies.getStoragePolicies()" }, { "lang": "java", "label": "List storage policies", "source": "client.getStoragePolicies().getStoragePolicies()" }, { "lang": "node", "label": "List storage policies", "source": "await client.storagePolicies.getStoragePolicies();" }, { "lang": "python", "label": "List storage policies", "source": "client.storage_policies.get_storage_policies()" } ] } }, "/storage_policies/{storage_policy_id}": { "get": { "operationId": "get_storage_policies_id", "summary": "Get storage policy", "description": "Fetches a specific storage policy.", "parameters": [ { "name": "storage_policy_id", "in": "path", "description": "The ID of the storage policy.", "required": true, "schema": { "type": "string" }, "example": "34342" } ], "responses": { "200": { "description": "Returns a storage policy object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicy" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "storage_policies", "tags": [ "Standard and Zones Storage Policies" ], "x-codeSamples": [ { "lang": "curl", "label": "Get storage policy", "source": "curl -i -X GET \"https://api.box.com/2.0/storage_policies/34342\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get storage policy", "source": "await client.StoragePolicies.GetStoragePolicyByIdAsync(storagePolicyId: storagePolicy.Id);" }, { "lang": "swift", "label": "Get storage policy", "source": "try await client.storagePolicies.getStoragePolicyById(storagePolicyId: storagePolicy.id)" }, { "lang": "java", "label": "Get storage policy", "source": "client.getStoragePolicies().getStoragePolicyById(storagePolicy.getId())" }, { "lang": "node", "label": "Get storage policy", "source": "await client.storagePolicies.getStoragePolicyById(storagePolicy.id);" }, { "lang": "python", "label": "Get storage policy", "source": "client.storage_policies.get_storage_policy_by_id(storage_policy.id)" } ] } }, "/storage_policy_assignments": { "get": { "operationId": "get_storage_policy_assignments", "summary": "List storage policy assignments", "description": "Fetches all the storage policy assignment for an enterprise or user.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "resolved_for_type", "in": "query", "description": "The target type to return assignments for.", "required": true, "schema": { "type": "string", "enum": [ "user", "enterprise" ] }, "example": "user" }, { "name": "resolved_for_id", "in": "query", "description": "The ID of the user or enterprise to return assignments for.", "required": true, "schema": { "type": "string" }, "example": "984322" } ], "responses": { "200": { "description": "Returns a collection of storage policies for the enterprise or user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignments" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "storage_policy_assignments", "tags": [ "Standard and Zones Storage Policy Assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "List storage policy assignments", "source": "curl -i -X GET \"https://api.box.com/2.0/storage_policy_assignments?resolved_for_type=user&resolved_for_id=984322\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List storage policy assignments", "source": "await client.StoragePolicyAssignments.GetStoragePolicyAssignmentsAsync(queryParams: new GetStoragePolicyAssignmentsQueryParams(resolvedForType: GetStoragePolicyAssignmentsQueryParamsResolvedForTypeField.User, resolvedForId: userId));" }, { "lang": "swift", "label": "List storage policy assignments", "source": "try await client.storagePolicyAssignments.getStoragePolicyAssignments(queryParams: GetStoragePolicyAssignmentsQueryParams(resolvedForType: GetStoragePolicyAssignmentsQueryParamsResolvedForTypeField.user, resolvedForId: userId))" }, { "lang": "java", "label": "List storage policy assignments", "source": "client.getStoragePolicyAssignments().getStoragePolicyAssignments(new GetStoragePolicyAssignmentsQueryParams(GetStoragePolicyAssignmentsQueryParamsResolvedForTypeField.USER, userId))" }, { "lang": "node", "label": "List storage policy assignments", "source": "await client.storagePolicyAssignments.getStoragePolicyAssignments({\n resolvedForType:\n 'user' as GetStoragePolicyAssignmentsQueryParamsResolvedForTypeField,\n resolvedForId: userId,\n} satisfies GetStoragePolicyAssignmentsQueryParams);" }, { "lang": "python", "label": "List storage policy assignments", "source": "client.storage_policy_assignments.get_storage_policy_assignments(\n GetStoragePolicyAssignmentsResolvedForType.USER, user_id\n)" } ] }, "post": { "operationId": "post_storage_policy_assignments", "summary": "Assign storage policy", "description": "Creates a storage policy assignment for an enterprise or user.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_policy": { "description": "The storage policy to assign to the user or enterprise.", "type": "object", "properties": { "type": { "description": "The type to assign.", "type": "string", "example": "storage_policy", "enum": [ "storage_policy" ] }, "id": { "description": "The ID of the storage policy to assign.", "type": "string", "example": "1434325" } }, "required": [ "type", "id" ] }, "assigned_to": { "description": "The user or enterprise to assign the storage policy to.", "type": "object", "properties": { "type": { "description": "The type to assign the policy to.", "type": "string", "example": "user", "enum": [ "user", "enterprise" ] }, "id": { "description": "The ID of the user or enterprise.", "type": "string", "example": "9987987" } }, "required": [ "type", "id" ] } }, "required": [ "storage_policy", "assigned_to" ] } } } }, "responses": { "200": { "description": "Returns the new storage policy assignment created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "storage_policy_assignments", "tags": [ "Standard and Zones Storage Policy Assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Assign storage policy", "source": "curl -i -X POST \"https://api.box.com/2.0/storage_policy_assignments\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"storage_policy\": {\n \"type\": \"storage_policy\",\n \"id\": \"1434325\"\n },\n \"assigned_to\": {\n \"type\": \"user\",\n \"id\": \"9987987\"\n }\n }'" }, { "lang": "dotnet", "label": "Assign storage policy", "source": "await client.StoragePolicyAssignments.CreateStoragePolicyAssignmentAsync(requestBody: new CreateStoragePolicyAssignmentRequestBody(storagePolicy: new CreateStoragePolicyAssignmentRequestBodyStoragePolicyField(id: policyId), assignedTo: new CreateStoragePolicyAssignmentRequestBodyAssignedToField(id: userId, type: CreateStoragePolicyAssignmentRequestBodyAssignedToTypeField.User)));" }, { "lang": "swift", "label": "Assign storage policy", "source": "try await client.storagePolicyAssignments.createStoragePolicyAssignment(requestBody: CreateStoragePolicyAssignmentRequestBody(storagePolicy: CreateStoragePolicyAssignmentRequestBodyStoragePolicyField(id: policyId), assignedTo: CreateStoragePolicyAssignmentRequestBodyAssignedToField(id: userId, type: CreateStoragePolicyAssignmentRequestBodyAssignedToTypeField.user)))" }, { "lang": "java", "label": "Assign storage policy", "source": "client.getStoragePolicyAssignments().createStoragePolicyAssignment(new CreateStoragePolicyAssignmentRequestBody(new CreateStoragePolicyAssignmentRequestBodyStoragePolicyField(policyId), new CreateStoragePolicyAssignmentRequestBodyAssignedToField(CreateStoragePolicyAssignmentRequestBodyAssignedToTypeField.USER, userId)))" }, { "lang": "node", "label": "Assign storage policy", "source": "await client.storagePolicyAssignments.createStoragePolicyAssignment({\n storagePolicy: new CreateStoragePolicyAssignmentRequestBodyStoragePolicyField(\n { id: policyId },\n ),\n assignedTo: {\n id: userId,\n type: 'user' as CreateStoragePolicyAssignmentRequestBodyAssignedToTypeField,\n } satisfies CreateStoragePolicyAssignmentRequestBodyAssignedToField,\n} satisfies CreateStoragePolicyAssignmentRequestBody);" }, { "lang": "python", "label": "Assign storage policy", "source": "client.storage_policy_assignments.create_storage_policy_assignment(\n CreateStoragePolicyAssignmentStoragePolicy(id=policy_id),\n CreateStoragePolicyAssignmentAssignedTo(\n id=user_id, type=CreateStoragePolicyAssignmentAssignedToTypeField.USER\n ),\n)" } ] } }, "/storage_policy_assignments/{storage_policy_assignment_id}": { "get": { "operationId": "get_storage_policy_assignments_id", "summary": "Get storage policy assignment", "description": "Fetches a specific storage policy assignment.", "parameters": [ { "name": "storage_policy_assignment_id", "in": "path", "description": "The ID of the storage policy assignment.", "required": true, "schema": { "type": "string" }, "example": "932483" } ], "responses": { "200": { "description": "Returns a storage policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "storage_policy_assignments", "tags": [ "Standard and Zones Storage Policy Assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Get storage policy assignment", "source": "curl -i -X GET \"https://api.box.com/2.0/storage_policy_assignments/932483\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get storage policy assignment", "source": "await client.StoragePolicyAssignments.GetStoragePolicyAssignmentByIdAsync(storagePolicyAssignmentId: storagePolicyAssignment.Id);" }, { "lang": "swift", "label": "Get storage policy assignment", "source": "try await client.storagePolicyAssignments.getStoragePolicyAssignmentById(storagePolicyAssignmentId: storagePolicyAssignment.id)" }, { "lang": "java", "label": "Get storage policy assignment", "source": "client.getStoragePolicyAssignments().getStoragePolicyAssignmentById(storagePolicyAssignment.getId())" }, { "lang": "node", "label": "Get storage policy assignment", "source": "await client.storagePolicyAssignments.getStoragePolicyAssignmentById(\n storagePolicyAssignment.id,\n);" }, { "lang": "python", "label": "Get storage policy assignment", "source": "client.storage_policy_assignments.get_storage_policy_assignment_by_id(\n storage_policy_assignment.id\n)" } ] }, "put": { "operationId": "put_storage_policy_assignments_id", "summary": "Update storage policy assignment", "description": "Updates a specific storage policy assignment.", "parameters": [ { "name": "storage_policy_assignment_id", "in": "path", "description": "The ID of the storage policy assignment.", "required": true, "schema": { "type": "string" }, "example": "932483" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_policy": { "description": "The storage policy to assign to the user or enterprise.", "type": "object", "properties": { "type": { "description": "The type to assign.", "type": "string", "example": "storage_policy", "enum": [ "storage_policy" ] }, "id": { "description": "The ID of the storage policy to assign.", "type": "string", "example": "1434325" } }, "required": [ "type", "id" ] } }, "required": [ "storage_policy" ] } } } }, "responses": { "200": { "description": "Returns an updated storage policy assignment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoragePolicyAssignment" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "storage_policy_assignments", "tags": [ "Standard and Zones Storage Policy Assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Update storage policy assignment", "source": "curl -i -X PUT \"https://api.box.com/2.0/storage_policy_assignments/932483\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"storage_policy\": {\n \"type\": \"storage_policy\",\n \"id\": \"1434325\"\n }\n }'" }, { "lang": "dotnet", "label": "Update storage policy assignment", "source": "await client.StoragePolicyAssignments.UpdateStoragePolicyAssignmentByIdAsync(storagePolicyAssignmentId: storagePolicyAssignment.Id, requestBody: new UpdateStoragePolicyAssignmentByIdRequestBody(storagePolicy: new UpdateStoragePolicyAssignmentByIdRequestBodyStoragePolicyField(id: storagePolicy2.Id)));" }, { "lang": "swift", "label": "Update storage policy assignment", "source": "try await client.storagePolicyAssignments.updateStoragePolicyAssignmentById(storagePolicyAssignmentId: storagePolicyAssignment.id, requestBody: UpdateStoragePolicyAssignmentByIdRequestBody(storagePolicy: UpdateStoragePolicyAssignmentByIdRequestBodyStoragePolicyField(id: storagePolicy2.id)))" }, { "lang": "java", "label": "Update storage policy assignment", "source": "client.getStoragePolicyAssignments().updateStoragePolicyAssignmentById(storagePolicyAssignment.getId(), new UpdateStoragePolicyAssignmentByIdRequestBody(new UpdateStoragePolicyAssignmentByIdRequestBodyStoragePolicyField(storagePolicy2.getId())))" }, { "lang": "node", "label": "Update storage policy assignment", "source": "await client.storagePolicyAssignments.updateStoragePolicyAssignmentById(\n storagePolicyAssignment.id,\n {\n storagePolicy:\n new UpdateStoragePolicyAssignmentByIdRequestBodyStoragePolicyField({\n id: storagePolicy2.id,\n }),\n } satisfies UpdateStoragePolicyAssignmentByIdRequestBody,\n);" }, { "lang": "python", "label": "Update storage policy assignment", "source": "client.storage_policy_assignments.update_storage_policy_assignment_by_id(\n storage_policy_assignment.id,\n UpdateStoragePolicyAssignmentByIdStoragePolicy(id=storage_policy_2.id),\n)" } ] }, "delete": { "operationId": "delete_storage_policy_assignments_id", "summary": "Unassign storage policy", "description": "Delete a storage policy assignment.\n\nDeleting a storage policy assignment on a user will have the user inherit the enterprise's default storage policy.\n\nThere is a rate limit for calling this endpoint of only twice per user in a 24 hour time frame.", "parameters": [ { "name": "storage_policy_assignment_id", "in": "path", "description": "The ID of the storage policy assignment.", "required": true, "schema": { "type": "string" }, "example": "932483" } ], "responses": { "204": { "description": "Returns an empty response when the storage policy assignment is successfully deleted." }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "storage_policy_assignments", "tags": [ "Standard and Zones Storage Policy Assignments" ], "x-codeSamples": [ { "lang": "curl", "label": "Unassign storage policy", "source": "curl -i -X DELETE \"https://api.box.com/2.0/storage_policy_assignments/932483\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"items\": {\n \"type\": \"storage_policy\",\n \"id\": \"1434325\"\n }\n }'" }, { "lang": "dotnet", "label": "Unassign storage policy", "source": "await client.StoragePolicyAssignments.DeleteStoragePolicyAssignmentByIdAsync(storagePolicyAssignmentId: storagePolicyAssignment.Id);" }, { "lang": "swift", "label": "Unassign storage policy", "source": "try await client.storagePolicyAssignments.deleteStoragePolicyAssignmentById(storagePolicyAssignmentId: storagePolicyAssignment.id)" }, { "lang": "java", "label": "Unassign storage policy", "source": "client.getStoragePolicyAssignments().deleteStoragePolicyAssignmentById(storagePolicyAssignment.getId())" }, { "lang": "node", "label": "Unassign storage policy", "source": "await client.storagePolicyAssignments.deleteStoragePolicyAssignmentById(\n storagePolicyAssignment.id,\n);" }, { "lang": "python", "label": "Unassign storage policy", "source": "client.storage_policy_assignments.delete_storage_policy_assignment_by_id(\n storage_policy_assignment.id\n)" } ] } }, "/zip_downloads": { "post": { "operationId": "post_zip_downloads", "summary": "Create zip download", "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.\n\nThe limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first.\n\n**Note**: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipDownloadRequest" } } } }, "responses": { "202": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipDownload" }, "examples": { "default": { "value": { "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content", "status_url": "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status", "expires_at": "2020-07-22T11:26:08Z", "name_conflicts": [ [ { "id": "12345", "type": "file", "original_name": "Report.pdf", "download_name": "3aa6a7.pdf" }, { "id": "34325", "type": "file", "original_name": "Report.pdf", "download_name": "5d53f2.pdf" } ] ] } } } } } }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\nIn 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.\n\nThe following is a list of common error codes for this response.\n\n- `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.\n- `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.\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when an authorization header is provided but the user does not have access to the items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "zip_downloads", "tags": [ "Zip Downloads" ], "x-box-reference-category": "zip_downloads", "x-codeSamples": [ { "lang": "curl", "label": "Create zip download", "source": "curl -i -X POST \"https://api.box.com/2.0/zip_downloads\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"download_file_name\": \"January Financials\",\n \"items\": [\n {\n \"type\": \"file\",\n \"id\": \"12345\"\n },\n {\n \"type\": \"file\",\n \"id\": \"34325\"\n },\n {\n \"type\": \"folder\",\n \"id\": \"45678\"\n }\n ]\n }'" }, { "lang": "dotnet", "label": "Create zip download", "source": "await client.ZipDownloads.CreateZipDownloadAsync(requestBody: new ZipDownloadRequest(items: Array.AsReadOnly(new [] {new ZipDownloadRequestItemsField(id: file1.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: file2.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: folder1.Id, type: ZipDownloadRequestItemsTypeField.Folder)})) { DownloadFileName = \"zip\" });" }, { "lang": "swift", "label": "Create zip download", "source": "try await client.zipDownloads.createZipDownload(requestBody: ZipDownloadRequest(items: [ZipDownloadRequestItemsField(id: file1.id, type: ZipDownloadRequestItemsTypeField.file), ZipDownloadRequestItemsField(id: file2.id, type: ZipDownloadRequestItemsTypeField.file), ZipDownloadRequestItemsField(id: folder1.id, type: ZipDownloadRequestItemsTypeField.folder)], downloadFileName: \"zip\"))" }, { "lang": "java", "label": "Create zip download", "source": "client.getZipDownloads().createZipDownload(new ZipDownloadRequest.Builder(Arrays.asList(new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FILE, file1.getId()), new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FILE, file2.getId()), new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FOLDER, folder1.getId()))).downloadFileName(\"zip\").build())" }, { "lang": "node", "label": "Create zip download", "source": "await client.zipDownloads.createZipDownload({\n items: [\n {\n id: file1.id,\n type: 'file' as ZipDownloadRequestItemsTypeField,\n } satisfies ZipDownloadRequestItemsField,\n {\n id: file2.id,\n type: 'file' as ZipDownloadRequestItemsTypeField,\n } satisfies ZipDownloadRequestItemsField,\n {\n id: folder1.id,\n type: 'folder' as ZipDownloadRequestItemsTypeField,\n } satisfies ZipDownloadRequestItemsField,\n ],\n downloadFileName: 'zip',\n} satisfies ZipDownloadRequest);" }, { "lang": "python", "label": "Create zip download", "source": "client.zip_downloads.create_zip_download(\n [\n CreateZipDownloadItems(id=file_1.id, type=DownloadZipItemsTypeField.FILE),\n CreateZipDownloadItems(id=file_2.id, type=DownloadZipItemsTypeField.FILE),\n CreateZipDownloadItems(id=folder_1.id, type=DownloadZipItemsTypeField.FOLDER),\n ],\n download_file_name=\"zip\",\n)" } ] } }, "/zip_downloads/{zip_download_id}/content": { "get": { "operationId": "get_zip_downloads_id_content", "summary": "Download zip archive", "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.\n\nBy 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.\n\nThe URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](/reference/post-zip-downloads) API to request to create a `zip` archive, and then follow the `download_url` field in the response to this endpoint.", "parameters": [ { "name": "zip_download_id", "in": "path", "description": "The unique identifier that represent this `zip` archive.", "required": true, "schema": { "type": "string" }, "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd" } ], "responses": { "200": { "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": { "type": "string", "example": "attachment;filename=\"Avatars.zip\";filename*=UTF-8''Avatars.zip" } } }, "content": { "application/octet-stream": { "schema": { "description": "The binary content of the archive, which will include the items requested for this download.", "type": "string", "format": "binary" } } } }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "429": { "description": "Returns an error if the number of concurrent zip downloads has been reached for either the user or the enterprise.\n\n- `user_too_many_concurrent_downloads` - the maximum of 5 parallel downloads of zip archives per user has been met.\n- `enterprise_too_many_concurrent_downloads` - the maximum of 10 parallel downloads of zip archives per enterprise has been met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "zip_downloads", "security": [], "servers": [ { "url": "https://dl.boxcloud.com/2.0", "description": "An opaque server URL for downloading zip downloads. The format of this URL might change over time." } ], "tags": [ "Zip Downloads" ], "x-box-reference-category": "zip_downloads", "x-codeSamples": [ { "lang": "curl", "label": "Download zip archive", "source": "curl -L -X GET \"https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content\" \\\n -H \"authorization: Bearer \" \\\n -o sample_curl.zip" }, { "lang": "dotnet", "label": "Download zip archive", "source": "await client.ZipDownloads.GetZipDownloadContentAsync(downloadUrl: NullableUtils.Unwrap(zipDownload.DownloadUrl));" }, { "lang": "swift", "label": "Download zip archive", "source": "try await client.zipDownloads.getZipDownloadContent(downloadUrl: zipDownload.downloadUrl!, downloadDestinationUrl: URL(path: destinationPathString))" }, { "lang": "java", "label": "Download zip archive", "source": "client.getZipDownloads().getZipDownloadContent(zipDownload.getDownloadUrl())" }, { "lang": "node", "label": "Download zip archive", "source": "await client.zipDownloads.getZipDownloadContent(zipDownload.downloadUrl!);" }, { "lang": "python", "label": "Download zip archive", "source": "client.zip_downloads.get_zip_download_content(zip_download.download_url)" } ] } }, "/zip_downloads/{zip_download_id}/status": { "get": { "operationId": "get_zip_downloads_id_status", "summary": "Get zip download status", "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.\n\nThis endpoint can only be accessed once the download has started. Subsequently this endpoint is valid for 12 hours from the start of the download.\n\nThe URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](/reference/post-zip-downloads) API to request to create a `zip` archive, and then follow the `status_url` field in the response to this endpoint.", "parameters": [ { "name": "zip_download_id", "in": "path", "description": "The unique identifier that represent this `zip` archive.", "required": true, "schema": { "type": "string" }, "example": "Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd" } ], "responses": { "200": { "description": "Returns the status of the `zip` archive that is being downloaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipDownloadStatus" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when an authorization header is provided but the user does not have access to the items.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "zip_downloads", "tags": [ "Zip Downloads" ], "x-box-reference-category": "zip_downloads", "x-codeSamples": [ { "lang": "curl", "label": "Get zip download status", "source": "curl -i -X GET \"https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get zip download status", "source": "await client.ZipDownloads.GetZipDownloadStatusAsync(statusUrl: NullableUtils.Unwrap(zipDownload.StatusUrl));" }, { "lang": "swift", "label": "Get zip download status", "source": "try await client.zipDownloads.getZipDownloadStatus(statusUrl: zipDownload.statusUrl!)" }, { "lang": "java", "label": "Get zip download status", "source": "client.getZipDownloads().getZipDownloadStatus(zipDownload.getStatusUrl())" }, { "lang": "node", "label": "Get zip download status", "source": "await client.zipDownloads.getZipDownloadStatus(zipDownload.statusUrl!);" }, { "lang": "python", "label": "Get zip download status", "source": "client.zip_downloads.get_zip_download_status(zip_download.status_url)" } ] } }, "/sign_requests/{sign_request_id}/cancel": { "post": { "operationId": "post_sign_requests_id_cancel", "summary": "Cancel Box Sign request", "description": "Cancels a sign request.", "parameters": [ { "name": "sign_request_id", "in": "path", "description": "The ID of the signature request.", "required": true, "schema": { "type": "string" }, "example": "33243242" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequestCancelRequest" } } } }, "responses": { "200": { "description": "Returns a Sign Request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequest" } } } }, "404": { "description": "Returns an error when the sign request cannot be found or the user does not have access to the sign request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "sign_requests", "tags": [ "Box Sign requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Cancel Box Sign request", "source": "curl -i -X POST \"https://api.box.com/2.0/sign_requests//cancel\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Cancel Box Sign request", "source": "await client.SignRequests.CancelSignRequestAsync(signRequestId: NullableUtils.Unwrap(createdSignRequest.Id));" }, { "lang": "swift", "label": "Cancel Box Sign request", "source": "try await client.signRequests.cancelSignRequest(signRequestId: createdSignRequest.id!)" }, { "lang": "java", "label": "Cancel Box Sign request", "source": "client.getSignRequests().cancelSignRequest(createdSignRequest.getId())" }, { "lang": "node", "label": "Cancel Box Sign request", "source": "await client.signRequests.cancelSignRequest(createdSignRequest.id!);" }, { "lang": "python", "label": "Cancel Box Sign request", "source": "client.sign_requests.cancel_sign_request(created_sign_request.id)" } ] } }, "/sign_requests/{sign_request_id}/resend": { "post": { "operationId": "post_sign_requests_id_resend", "summary": "Resend Box Sign request", "description": "Resends a signature request email to all outstanding signers.", "parameters": [ { "name": "sign_request_id", "in": "path", "description": "The ID of the signature request.", "required": true, "schema": { "type": "string" }, "example": "33243242" } ], "responses": { "202": { "description": "Returns an empty response when the API call was successful. The email notifications will be sent asynchronously." }, "404": { "description": "Returns an error when the signature request cannot be found or the user does not have access to the signature request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "sign_requests", "tags": [ "Box Sign requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Resend Box Sign request", "source": "curl -i -X POST \"https://api.box.com/2.0/sign_requests//resend\" \\\n -H \"authorization: Bearer \"" } ] } }, "/sign_requests/{sign_request_id}": { "get": { "operationId": "get_sign_requests_id", "summary": "Get Box Sign request by ID", "description": "Gets a sign request by ID.", "parameters": [ { "name": "sign_request_id", "in": "path", "description": "The ID of the signature request.", "required": true, "schema": { "type": "string" }, "example": "33243242" } ], "responses": { "200": { "description": "Returns a signature request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequest" } } } }, "404": { "description": "Returns an error when the signature request cannot be found, the user does not have access to the signature request, or `sign_files` and/or `parent_folder` is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "sign_requests", "tags": [ "Box Sign requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Get Box Sign request by ID", "source": "curl -i -X GET \"https://api.box.com/2.0/sign_requests/\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get Box Sign request by ID", "source": "await client.SignRequests.GetSignRequestByIdAsync(signRequestId: NullableUtils.Unwrap(createdSignRequest.Id));" }, { "lang": "swift", "label": "Get Box Sign request by ID", "source": "try await client.signRequests.getSignRequestById(signRequestId: createdSignRequest.id!)" }, { "lang": "java", "label": "Get Box Sign request by ID", "source": "client.getSignRequests().getSignRequestById(createdSignRequest.getId())" }, { "lang": "node", "label": "Get Box Sign request by ID", "source": "await client.signRequests.getSignRequestById(createdSignRequest.id!);" }, { "lang": "python", "label": "Get Box Sign request by ID", "source": "client.sign_requests.get_sign_request_by_id(created_sign_request.id)" } ] } }, "/sign_requests": { "get": { "operationId": "get_sign_requests", "summary": "List Box Sign requests", "description": "Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "senders", "in": "query", "description": "A list of sender emails to filter the signature requests by sender. If provided, `shared_requests` must be set to `true`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "sender1@boxdemo.com", "sender2@boxdemo.com" ] }, { "name": "shared_requests", "in": "query", "description": "If set to `true`, only includes requests that user is not an owner, but user is a collaborator. Collaborator access is determined by the user access level of the sign files of the request. Default is `false`. Must be set to `true` if `senders` are provided.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true } ], "responses": { "200": { "description": "Returns a collection of sign requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequests" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "sign_requests", "tags": [ "Box Sign requests" ], "x-codeSamples": [ { "lang": "curl", "label": "List Box Sign requests", "source": "curl -i -X GET \"https://api.box.com/2.0/sign_requests\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List Box Sign requests", "source": "await client.SignRequests.GetSignRequestsAsync();" }, { "lang": "swift", "label": "List Box Sign requests", "source": "try await client.signRequests.getSignRequests()" }, { "lang": "java", "label": "List Box Sign requests", "source": "client.getSignRequests().getSignRequests()" }, { "lang": "node", "label": "List Box Sign requests", "source": "await client.signRequests.getSignRequests();" }, { "lang": "python", "label": "List Box Sign requests", "source": "client.sign_requests.get_sign_requests()" } ] }, "post": { "operationId": "post_sign_requests", "summary": "Create Box Sign request", "description": "Creates a signature request. This involves preparing a document for signing and sending the signature request to signers.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequestCreateRequest" } } } }, "responses": { "201": { "description": "Returns a Box Sign request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequest" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "sign_requests", "tags": [ "Box Sign requests" ], "x-codeSamples": [ { "lang": "curl", "label": "Create Box Sign request", "source": "curl -i -X POST \"https://api.box.com/2.0/sign_requests\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"signers\": [\n {\n \"role\": \"signer\",\n \"email\": \"example_email@box.com\"\n }\n ],\n \"source_files\": [\n {\n \"type\": \"file\",\n \"id\": \"123456789\"\n }\n ],\n \"parent_folder\":\n {\n \"type\": \"folder\",\n \"id\": \"0987654321\"\n }\n }'" }, { "lang": "dotnet", "label": "Create Box Sign request", "source": "await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signerEmail, SuppressNotifications = true, DeclinedRedirectUrl = \"https://www.box.com\", EmbedUrlExternalUserId = \"123\", IsInPerson = false, LoginRequired = false, Password = \"password\", Role = SignRequestCreateSignerRoleField.Signer }}), areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: 30L, declinedRedirectUrl: \"https://www.box.com\", emailMessage: \"Please sign this document\", emailSubject: \"Sign this document\", externalId: \"123\", externalSystemName: \"BoxSignIntegration\", isDocumentPreparationNeeded: false, name: \"Sign Request\", parentFolder: new FolderMini(id: destinationFolder.Id), redirectUrl: \"https://www.box.com\", prefillTags: Array.AsReadOnly(new [] {new SignRequestPrefillTag() { DateValue = Utils.DateFromString(date: \"2035-01-01\"), DocumentTagId = \"0\" }}), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)})));" }, { "lang": "swift", "label": "Create Box Sign request", "source": "try await client.signRequests.createSignRequest(requestBody: SignRequestCreateRequest(signers: [SignRequestCreateSigner(email: signerEmail, suppressNotifications: true, declinedRedirectUrl: \"https://www.box.com\", embedUrlExternalUserId: \"123\", isInPerson: false, loginRequired: false, password: \"password\", role: SignRequestCreateSignerRoleField.signer)], areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: Int64(30), declinedRedirectUrl: \"https://www.box.com\", emailMessage: \"Please sign this document\", emailSubject: \"Sign this document\", externalId: \"123\", externalSystemName: \"BoxSignIntegration\", isDocumentPreparationNeeded: false, name: \"Sign Request\", parentFolder: FolderMini(id: destinationFolder.id), redirectUrl: \"https://www.box.com\", prefillTags: [SignRequestPrefillTag(dateValue: try Utils.Dates.dateFromString(date: \"2035-01-01\"), documentTagId: \"0\")], sourceFiles: [FileBase(id: fileToSign.id)]))" }, { "lang": "java", "label": "Create Box Sign request", "source": "client.getSignRequests().createSignRequest(new SignRequestCreateRequest.Builder(Arrays.asList(new SignRequestCreateSigner.Builder().email(signerEmail).role(SignRequestCreateSignerRoleField.SIGNER).isInPerson(false).embedUrlExternalUserId(\"123\").declinedRedirectUrl(\"https://www.box.com\").loginRequired(false).password(\"password\").suppressNotifications(true).build())).sourceFiles(Arrays.asList(new FileBase(fileToSign.getId()))).parentFolder(new FolderMini(destinationFolder.getId())).isDocumentPreparationNeeded(false).redirectUrl(\"https://www.box.com\").declinedRedirectUrl(\"https://www.box.com\").areTextSignaturesEnabled(true).emailSubject(\"Sign this document\").emailMessage(\"Please sign this document\").areRemindersEnabled(true).name(\"Sign Request\").prefillTags(Arrays.asList(new SignRequestPrefillTag.Builder().documentTagId(\"0\").dateValue(dateFromString(\"2035-01-01\")).build())).daysValid(30L).externalId(\"123\").externalSystemName(\"BoxSignIntegration\").build())" }, { "lang": "node", "label": "Create Box Sign request", "source": "await client.signRequests.createSignRequest({\n signers: [\n {\n email: signerEmail,\n suppressNotifications: true,\n declinedRedirectUrl: 'https://www.box.com',\n embedUrlExternalUserId: '123',\n isInPerson: false,\n loginRequired: false,\n password: 'password',\n role: 'signer' as SignRequestCreateSignerRoleField,\n } satisfies SignRequestCreateSigner,\n ],\n areRemindersEnabled: true,\n areTextSignaturesEnabled: true,\n daysValid: 30,\n declinedRedirectUrl: 'https://www.box.com',\n emailMessage: 'Please sign this document',\n emailSubject: 'Sign this document',\n externalId: '123',\n externalSystemName: 'BoxSignIntegration',\n isDocumentPreparationNeeded: false,\n name: 'Sign Request',\n parentFolder: new FolderMini({ id: destinationFolder.id }),\n redirectUrl: 'https://www.box.com',\n prefillTags: [\n {\n dateValue: dateFromString('2035-01-01'),\n documentTagId: '0',\n } satisfies SignRequestPrefillTag,\n ],\n sourceFiles: [new FileBase({ id: fileToSign.id })],\n} satisfies SignRequestCreateRequest);" }, { "lang": "python", "label": "Create Box Sign request", "source": "client.sign_requests.create_sign_request(\n [\n SignRequestCreateSigner(\n email=signer_email,\n suppress_notifications=True,\n declined_redirect_url=\"https://www.box.com\",\n embed_url_external_user_id=\"123\",\n is_in_person=False,\n login_required=False,\n password=\"password\",\n role=SignRequestCreateSignerRoleField.SIGNER,\n )\n ],\n source_files=[FileBase(id=file_to_sign.id)],\n parent_folder=FolderMini(id=destination_folder.id),\n is_document_preparation_needed=False,\n redirect_url=\"https://www.box.com\",\n declined_redirect_url=\"https://www.box.com\",\n are_text_signatures_enabled=True,\n email_subject=\"Sign this document\",\n email_message=\"Please sign this document\",\n are_reminders_enabled=True,\n name=\"Sign Request\",\n prefill_tags=[\n SignRequestPrefillTag(\n date_value=date_from_string(\"2035-01-01\"), document_tag_id=\"0\"\n )\n ],\n days_valid=30,\n external_id=\"123\",\n external_system_name=\"BoxSignIntegration\",\n)" } ] } }, "/workflows": { "get": { "operationId": "get_workflows", "summary": "List workflows", "description": "Returns list of workflows that act on a given `folder ID`, and have a flow with a trigger type of `WORKFLOW_MANUAL_START`.\n\nYou application must be authorized to use the `Manage Box Relay` application scope within the developer console in to use this endpoint.", "parameters": [ { "name": "folder_id", "in": "query", "description": "The unique identifier that represent a folder.\n\nThe 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`.\n\nThe root folder of a Box account is always represented by the ID `0`.", "required": true, "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "trigger_type", "in": "query", "description": "Type of trigger to search for.", "required": false, "schema": { "type": "string", "nullable": false }, "example": "WORKFLOW_MANUAL_START" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" } ], "responses": { "200": { "description": "Returns the workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflows" } } } }, "400": { "description": "Returned if the trigger type is not `WORKFLOW_MANUAL_START`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the folder is not found, or the user does not have access to the folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "workflows", "tags": [ "Workflows" ], "x-codeSamples": [ { "lang": "curl", "label": "List workflows", "source": "curl -i -X GET \"https://api.box.com/2.0/workflows?folder_id=324234\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List workflows", "source": "await adminClient.Workflows.GetWorkflowsAsync(queryParams: new GetWorkflowsQueryParams(folderId: workflowFolderId));" }, { "lang": "swift", "label": "List workflows", "source": "try await adminClient.workflows.getWorkflows(queryParams: GetWorkflowsQueryParams(folderId: workflowFolderId))" }, { "lang": "java", "label": "List workflows", "source": "adminClient.getWorkflows().getWorkflows(new GetWorkflowsQueryParams(workflowFolderId))" }, { "lang": "node", "label": "List workflows", "source": "await adminClient.workflows.getWorkflows({\n folderId: workflowFolderId,\n} satisfies GetWorkflowsQueryParams);" }, { "lang": "python", "label": "List workflows", "source": "admin_client.workflows.get_workflows(workflow_folder_id)" } ] } }, "/workflows/{workflow_id}/start": { "post": { "operationId": "post_workflows_id_start", "summary": "Starts workflow based on request body", "description": "Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`.\n\nYou application must be authorized to use the `Manage Box Relay` application scope within the developer console.", "parameters": [ { "name": "workflow_id", "in": "path", "description": "The ID of the workflow.", "required": true, "schema": { "type": "string" }, "example": "12345" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "The type of the parameters object.", "type": "string", "example": "workflow_parameters", "enum": [ "workflow_parameters" ] }, "flow": { "description": "The flow that will be triggered.", "type": "object", "properties": { "type": { "description": "The type of the flow object.", "type": "string", "example": "flow" }, "id": { "description": "The id of the flow.", "type": "string", "example": "123456789" } } }, "files": { "description": "The array of files for which the workflow should start. All files must be in the workflow's configured folder.", "type": "array", "items": { "type": "object", "description": "A file the workflow should start for.", "properties": { "type": { "description": "The type of the file object.", "type": "string", "example": "file", "enum": [ "file" ] }, "id": { "description": "The id of the file.", "type": "string", "example": "12345678" } } } }, "folder": { "description": "The folder object for which the workflow is configured.", "type": "object", "properties": { "type": { "description": "The type of the folder object.", "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { "description": "The id of the folder.", "type": "string", "example": "87654321" } } }, "outcomes": { "description": "A configurable outcome the workflow should complete.", "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } } }, "required": [ "flow", "files", "folder" ] } } } }, "responses": { "204": { "description": "Starts the workflow." }, "400": { "description": "Returns an error if some of the parameters are missing or not valid.\n\n- `workflow_is_not_enabled` when the workflow is not enabled.\n- `workflow_not_active_on_provided_folder` when the workflow is not enabled for the specified folder id.\n- `parameters_provided_do_not_match_target_outcome` when the provided parameters do not match the expected parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returns an error if there are insufficient permissions.\n\n- `insufficient_access` when the user does not have access rights to file or folder.\n- `missing_relay_full_access` when the user does not have access to Relay Full.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns an error if the workflow could not be found, or the authenticated user does not have access to the workflow.\n\n- `workflow_not_found` when the workflow is not found.\n- `flow_missing_or_inaccessible` when the flow is not a manual start flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "workflows", "tags": [ "Workflows" ], "x-codeSamples": [ { "lang": "curl", "label": "Starts workflow based on request body", "source": "curl -i -X POST \"https://api.box.com/2.0/workflows/42037322/start\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"type\": \"workflow_parameters\",\n \"flow\": {\n \"id\": \"8937625\",\n \"type\": \"flow\"\n },\n \"files\": [{\n \"type\": \"file\",\n \"id\": \"389047572\"\n },\n {\n \"type\": \"file\",\n \"id\": \"389047578\"\n }],\n \"folder\": {\n \"id\": \"2233212\",\n \"type\": \"folder\"\n },\n \"outcomes\": [\n {\n \"id\": \"34895783\",\n \"type\": \"outcome\",\n \"task_collaborators\": {\n \"type\": \"variable\",\n \"variable_type\": \"user_list\",\n \"variable_value\": [{ \"type\": \"user\", \"id\": \"890273642\" }]\n },\n \"completion_rule\": {\n \"type\": \"variable\",\n \"variable_type\": \"task_completion_rule\",\n \"variable_value\": \"all_assignees\"\n },\n \"file_collaborator_role\": {\n \"type\": \"variable\",\n \"variable_type\": \"collaborator_role\",\n \"variable_value\": \"viewer\"\n }\n }\n ]\n }'" }, { "lang": "dotnet", "label": "Starts workflow based on request body", "source": "await adminClient.Workflows.StartWorkflowAsync(workflowId: NullableUtils.Unwrap(workflowToRun.Id), requestBody: new StartWorkflowRequestBody(flow: new StartWorkflowRequestBodyFlowField() { Type = \"flow\", Id = NullableUtils.Unwrap(NullableUtils.Unwrap(workflowToRun.Flows)[0].Id) }, files: Array.AsReadOnly(new [] {new StartWorkflowRequestBodyFilesField() { Type = StartWorkflowRequestBodyFilesTypeField.File, Id = workflowFileId }}), folder: new StartWorkflowRequestBodyFolderField() { Type = StartWorkflowRequestBodyFolderTypeField.Folder, Id = workflowFolderId }) { Type = StartWorkflowRequestBodyTypeField.WorkflowParameters });" }, { "lang": "swift", "label": "Starts workflow based on request body", "source": "try await adminClient.workflows.startWorkflow(workflowId: workflowToRun.id!, requestBody: StartWorkflowRequestBody(type: StartWorkflowRequestBodyTypeField.workflowParameters, flow: StartWorkflowRequestBodyFlowField(type: \"flow\", id: workflowToRun.flows![0].id!), files: [StartWorkflowRequestBodyFilesField(type: StartWorkflowRequestBodyFilesTypeField.file, id: workflowFileId)], folder: StartWorkflowRequestBodyFolderField(type: StartWorkflowRequestBodyFolderTypeField.folder, id: workflowFolderId)))" }, { "lang": "java", "label": "Starts workflow based on request body", "source": "adminClient.getWorkflows().startWorkflow(workflowToRun.getId(), new StartWorkflowRequestBody.Builder(new StartWorkflowRequestBodyFlowField.Builder().type(\"flow\").id(workflowToRun.getFlows().get(0).getId()).build(), Arrays.asList(new StartWorkflowRequestBodyFilesField.Builder().type(StartWorkflowRequestBodyFilesTypeField.FILE).id(workflowFileId).build()), new StartWorkflowRequestBodyFolderField.Builder().type(StartWorkflowRequestBodyFolderTypeField.FOLDER).id(workflowFolderId).build()).type(StartWorkflowRequestBodyTypeField.WORKFLOW_PARAMETERS).build())" }, { "lang": "node", "label": "Starts workflow based on request body", "source": "await adminClient.workflows.startWorkflow(workflowToRun.id!, {\n type: 'workflow_parameters' as StartWorkflowRequestBodyTypeField,\n flow: {\n type: 'flow',\n id: workflowToRun.flows![0].id!,\n } satisfies StartWorkflowRequestBodyFlowField,\n files: [\n {\n type: 'file' as StartWorkflowRequestBodyFilesTypeField,\n id: workflowFileId,\n } satisfies StartWorkflowRequestBodyFilesField,\n ],\n folder: {\n type: 'folder' as StartWorkflowRequestBodyFolderTypeField,\n id: workflowFolderId,\n } satisfies StartWorkflowRequestBodyFolderField,\n} satisfies StartWorkflowRequestBody);" }, { "lang": "python", "label": "Starts workflow based on request body", "source": "admin_client.workflows.start_workflow(\n workflow_to_run.id,\n StartWorkflowFlow(type=\"flow\", id=workflow_to_run.flows[0].id),\n [StartWorkflowFiles(type=StartWorkflowFilesTypeField.FILE, id=workflow_file_id)],\n StartWorkflowFolder(\n type=StartWorkflowFolderTypeField.FOLDER, id=workflow_folder_id\n ),\n type=StartWorkflowType.WORKFLOW_PARAMETERS,\n)" } ] } }, "/sign_templates": { "get": { "operationId": "get_sign_templates", "summary": "List Box Sign templates", "description": "Gets Box Sign templates created by a user.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a collection of templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignTemplates" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "sign_templates", "tags": [ "Box Sign templates" ], "x-codeSamples": [ { "lang": "curl", "label": "List Box Sign templates", "source": "curl -L -X GET \"https://api.box.com/2.0/sign_templates?marker=JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii&limit=1000\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List Box Sign templates", "source": "await client.SignTemplates.GetSignTemplatesAsync(queryParams: new GetSignTemplatesQueryParams() { Limit = 2L });" }, { "lang": "swift", "label": "List Box Sign templates", "source": "try await client.signTemplates.getSignTemplates(queryParams: GetSignTemplatesQueryParams(limit: Int64(2)))" }, { "lang": "java", "label": "List Box Sign templates", "source": "client.getSignTemplates().getSignTemplates(new GetSignTemplatesQueryParams.Builder().limit(2L).build())" }, { "lang": "node", "label": "List Box Sign templates", "source": "await client.signTemplates.getSignTemplates({\n limit: 2,\n} satisfies GetSignTemplatesQueryParams);" }, { "lang": "python", "label": "List Box Sign templates", "source": "client.sign_templates.get_sign_templates(limit=2)" } ] } }, "/sign_templates/{template_id}": { "get": { "operationId": "get_sign_templates_id", "summary": "Get Box Sign template by ID", "description": "Fetches details of a specific Box Sign template.", "parameters": [ { "name": "template_id", "in": "path", "description": "The ID of a Box Sign template.", "required": true, "schema": { "type": "string" }, "example": "123075213-7d117509-8f05-42e4-a5ef-5190a319d41d" } ], "responses": { "200": { "description": "Returns details of a template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignTemplate" } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header is not recognized or not provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the template is not found or the user does not have access to the associated template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "sign_templates", "tags": [ "Box Sign templates" ], "x-codeSamples": [ { "lang": "curl", "label": "Get Box Sign template by ID", "source": "curl -L -X GET \"https://api.box.com/2.0/sign_templates/12345678\" \\\n -H \"accept: application/json\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get Box Sign template by ID", "source": "await client.SignTemplates.GetSignTemplateByIdAsync(templateId: NullableUtils.Unwrap(NullableUtils.Unwrap(signTemplates.Entries)[0].Id));" }, { "lang": "swift", "label": "Get Box Sign template by ID", "source": "try await client.signTemplates.getSignTemplateById(templateId: signTemplates.entries![0].id!)" }, { "lang": "java", "label": "Get Box Sign template by ID", "source": "client.getSignTemplates().getSignTemplateById(signTemplates.getEntries().get(0).getId())" }, { "lang": "node", "label": "Get Box Sign template by ID", "source": "await client.signTemplates.getSignTemplateById(signTemplates.entries![0].id!);" }, { "lang": "python", "label": "Get Box Sign template by ID", "source": "client.sign_templates.get_sign_template_by_id(sign_templates.entries[0].id)" } ] } }, "/integration_mappings/slack": { "get": { "operationId": "get_integration_mappings_slack", "summary": "List Slack integration mappings", "description": "Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise.\n\nYou need Admin or Co-Admin role to use this endpoint.", "parameters": [ { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 }, { "name": "partner_item_type", "in": "query", "description": "Mapped item type, for which the mapping should be returned.", "schema": { "type": "string", "enum": [ "channel" ] }, "example": "channel" }, { "name": "partner_item_id", "in": "query", "description": "ID of the mapped item, for which the mapping should be returned.", "schema": { "type": "string" }, "example": "12345" }, { "name": "box_item_id", "in": "query", "description": "Box item ID, for which the mappings should be returned.", "schema": { "type": "string", "nullable": false }, "example": "12345" }, { "name": "box_item_type", "in": "query", "description": "Box item type, for which the mappings should be returned.", "schema": { "type": "string", "enum": [ "folder" ], "nullable": false }, "example": "folder" }, { "name": "is_manually_created", "in": "query", "description": "Whether the mapping has been manually created.", "schema": { "type": "boolean", "nullable": false }, "example": true } ], "responses": { "200": { "description": "Returns a collection of integration mappings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappings" } } } }, "400": { "description": "The server cannot or will not process the request due to an apparent client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "List Slack integration mappings", "source": "curl -L -X GET \"https://api.box.com/2.0/integration_mappings/slack?partner_item_id=C987654321&box_item_id=123456789\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List Slack integration mappings", "source": "await userClient.IntegrationMappings.GetSlackIntegrationMappingAsync();" }, { "lang": "swift", "label": "List Slack integration mappings", "source": "try await userClient.integrationMappings.getSlackIntegrationMapping()" }, { "lang": "java", "label": "List Slack integration mappings", "source": "userClient.getIntegrationMappings().getSlackIntegrationMapping()" }, { "lang": "node", "label": "List Slack integration mappings", "source": "await userClient.integrationMappings.getSlackIntegrationMapping();" }, { "lang": "python", "label": "List Slack integration mappings", "source": "user_client.integration_mappings.get_slack_integration_mapping()" } ] }, "post": { "operationId": "post_integration_mappings_slack", "summary": "Create Slack integration mapping", "description": "Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item.\n\nYou need Admin or Co-Admin role to use this endpoint.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappingSlackCreateRequest" } } } }, "responses": { "201": { "description": "Returns the created integration mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMapping" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item_id`. Error codes:\n\n- `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`,\n- `CHANNEL_ALREADY_MAPPED` - channel is already mapped to another `box_item_id`,\n- `CHANNEL_NOT_FOUND` - channel was not found,\n- `CHANNEL_NOT_SUITABLE_FOR_CFS` - connect channel, not suitable for Box as Content layer for Slack,\n- `BOX_ENTERPRISE_MISMATCH` - Box folder must be owned by the enterprise, which is configured to use Box as Content layer for Slack,\n- `CFS_DISABLED` - Box as Content layer for Slack must be enabled for a provided Slack workspace or organization\n- `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise,\n- `JWT_APP_NOT_AUTHORIZED` - JWT authorization error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "Create Slack integration mapping", "source": "curl -L -X POST \"https://api.box.com/2.0/integration_mappings/slack\" \\\n -H \"authorization: Bearer \" \\\n -H 'content-type: application/json' \\\n -d '{\n \"partner_item\": {\n \"id\": \"C987654321\",\n \"type\": \"channel\",\n \"slack_workspace_id\": \"T5555555\"\n },\n \"box_item\": {\n \"id\": \"123456789\",\n \"type\": \"folder\"\n }\n }'" }, { "lang": "dotnet", "label": "Create Slack integration mapping", "source": "await userClient.IntegrationMappings.CreateSlackIntegrationMappingAsync(requestBody: new IntegrationMappingSlackCreateRequest(partnerItem: new IntegrationMappingPartnerItemSlack(id: slackPartnerItemId) { SlackOrgId = slackOrgId }, boxItem: new IntegrationMappingBoxItemSlack(id: folder.Id)));" }, { "lang": "swift", "label": "Create Slack integration mapping", "source": "try await userClient.integrationMappings.createSlackIntegrationMapping(requestBody: IntegrationMappingSlackCreateRequest(partnerItem: IntegrationMappingPartnerItemSlack(id: slackPartnerItemId, slackOrgId: slackOrgId), boxItem: IntegrationMappingBoxItemSlack(id: folder.id)))" }, { "lang": "java", "label": "Create Slack integration mapping", "source": "userClient.getIntegrationMappings().createSlackIntegrationMapping(new IntegrationMappingSlackCreateRequest(new IntegrationMappingPartnerItemSlack.Builder(slackPartnerItemId).slackOrgId(slackOrgId).build(), new IntegrationMappingBoxItemSlack(folder.getId())))" }, { "lang": "node", "label": "Create Slack integration mapping", "source": "await userClient.integrationMappings.createSlackIntegrationMapping({\n partnerItem: new IntegrationMappingPartnerItemSlack({\n id: slackPartnerItemId,\n slackOrgId: slackOrgId,\n }),\n boxItem: new IntegrationMappingBoxItemSlack({ id: folder.id }),\n} satisfies IntegrationMappingSlackCreateRequest);" }, { "lang": "python", "label": "Create Slack integration mapping", "source": "user_client.integration_mappings.create_slack_integration_mapping(\n IntegrationMappingPartnerItemSlack(\n id=slack_partner_item_id, slack_org_id=slack_org_id\n ),\n IntegrationMappingBoxItemSlack(id=folder.id),\n)" } ] } }, "/integration_mappings/slack/{integration_mapping_id}": { "put": { "operationId": "put_integration_mappings_slack_id", "summary": "Update Slack integration mapping", "description": "Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). Supports updating the Box folder ID and options.\n\nYou need Admin or Co-Admin role to use this endpoint.", "parameters": [ { "name": "integration_mapping_id", "in": "path", "description": "An ID of an integration mapping.", "required": true, "schema": { "type": "string" }, "example": "11235432" } ], "requestBody": { "description": "At least one of `box_item` and `options` must be provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "box_item": { "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" } ] }, "options": { "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingSlackOptions" } ] } } } } } }, "responses": { "200": { "description": "Returns the updated integration mapping object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMapping" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item`. Error codes:\n\n- `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`,\n- `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise,\n- `JWT_APP_NOT_AUTHORIZED` - JWT authorization error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns `not_found` if integration mapping object was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "Update Slack integration mapping", "source": "curl -L -X PUT \"https://api.box.com/2.0/integration_mappings/slack/512521\" \\\n -H \"authorization: Bearer \" \\\n -H 'content-type: application/json' \\\n -d '{\n \"options\": {\n \"is_access_management_disabled\": true\n }\n }'" }, { "lang": "dotnet", "label": "Update Slack integration mapping", "source": "await userClient.IntegrationMappings.UpdateSlackIntegrationMappingByIdAsync(integrationMappingId: slackIntegrationMapping.Id, requestBody: new UpdateSlackIntegrationMappingByIdRequestBody() { BoxItem = new IntegrationMappingBoxItemSlack(id: folder.Id) });" }, { "lang": "swift", "label": "Update Slack integration mapping", "source": "try await userClient.integrationMappings.updateSlackIntegrationMappingById(integrationMappingId: slackIntegrationMapping.id, requestBody: UpdateSlackIntegrationMappingByIdRequestBody(boxItem: IntegrationMappingBoxItemSlack(id: folder.id)))" }, { "lang": "java", "label": "Update Slack integration mapping", "source": "userClient.getIntegrationMappings().updateSlackIntegrationMappingById(slackIntegrationMapping.getId(), new UpdateSlackIntegrationMappingByIdRequestBody.Builder().boxItem(new IntegrationMappingBoxItemSlack(folder.getId())).build())" }, { "lang": "node", "label": "Update Slack integration mapping", "source": "await userClient.integrationMappings.updateSlackIntegrationMappingById(\n slackIntegrationMapping.id,\n {\n requestBody: {\n boxItem: new IntegrationMappingBoxItemSlack({ id: folder.id }),\n } satisfies UpdateSlackIntegrationMappingByIdRequestBody,\n } satisfies UpdateSlackIntegrationMappingByIdOptionalsInput,\n);" }, { "lang": "python", "label": "Update Slack integration mapping", "source": "user_client.integration_mappings.update_slack_integration_mapping_by_id(\n slack_integration_mapping.id, box_item=IntegrationMappingBoxItemSlack(id=folder.id)\n)" } ] }, "delete": { "operationId": "delete_integration_mappings_slack_id", "summary": "Delete Slack integration mapping", "description": "Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).\n\nYou need Admin or Co-Admin role to use this endpoint.", "parameters": [ { "name": "integration_mapping_id", "in": "path", "description": "An ID of an integration mapping.", "required": true, "schema": { "type": "string" }, "example": "11235432" } ], "responses": { "204": { "description": "Empty body in response." }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete Slack integration mapping", "source": "curl -L -X DELETE \"https://api.box.com/2.0/integration_mappings/slack/512521\" \\\n -H \"authorization: Bearer \" \\\n -d ''" }, { "lang": "dotnet", "label": "Delete Slack integration mapping", "source": "await userClient.IntegrationMappings.DeleteSlackIntegrationMappingByIdAsync(integrationMappingId: slackIntegrationMapping.Id);" }, { "lang": "swift", "label": "Delete Slack integration mapping", "source": "try await userClient.integrationMappings.deleteSlackIntegrationMappingById(integrationMappingId: slackIntegrationMapping.id)" }, { "lang": "java", "label": "Delete Slack integration mapping", "source": "userClient.getIntegrationMappings().deleteSlackIntegrationMappingById(slackIntegrationMapping.getId())" }, { "lang": "node", "label": "Delete Slack integration mapping", "source": "await userClient.integrationMappings.deleteSlackIntegrationMappingById(\n slackIntegrationMapping.id,\n);" }, { "lang": "python", "label": "Delete Slack integration mapping", "source": "user_client.integration_mappings.delete_slack_integration_mapping_by_id(\n slack_integration_mapping.id\n)" } ] } }, "/integration_mappings/teams": { "get": { "operationId": "get_integration_mappings_teams", "summary": "List Teams integration mappings", "description": "Lists [Teams integration mappings](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint.", "x-stability-level": "stable", "parameters": [ { "name": "partner_item_type", "in": "query", "description": "Mapped item type, for which the mapping should be returned.", "schema": { "type": "string", "enum": [ "channel", "team" ] }, "example": "channel" }, { "name": "partner_item_id", "in": "query", "description": "ID of the mapped item, for which the mapping should be returned.", "schema": { "type": "string" }, "example": "12345" }, { "name": "box_item_id", "in": "query", "description": "Box item ID, for which the mappings should be returned.", "schema": { "type": "string" }, "example": "12345" }, { "name": "box_item_type", "in": "query", "description": "Box item type, for which the mappings should be returned.", "schema": { "type": "string", "enum": [ "folder" ] }, "example": "folder" } ], "responses": { "200": { "description": "Returns a collection of integration mappings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappingsTeams" } } } }, "400": { "description": "The server cannot or will not process the request due to an apparent client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "List Teams integration mappings", "source": "curl -L -X GET \"https://api.box.com/2.0/integration_mappings/teams\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List Teams integration mappings", "source": "await userClient.IntegrationMappings.GetTeamsIntegrationMappingAsync();" }, { "lang": "swift", "label": "List Teams integration mappings", "source": "try await userClient.integrationMappings.getTeamsIntegrationMapping()" }, { "lang": "java", "label": "List Teams integration mappings", "source": "userClient.getIntegrationMappings().getTeamsIntegrationMapping()" }, { "lang": "node", "label": "List Teams integration mappings", "source": "await userClient.integrationMappings.getTeamsIntegrationMapping();" }, { "lang": "python", "label": "List Teams integration mappings", "source": "user_client.integration_mappings.get_teams_integration_mapping()" } ] }, "post": { "operationId": "post_integration_mappings_teams", "summary": "Create Teams integration mapping", "description": "Creates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) by mapping a Teams channel to a Box item. You need Admin or Co-Admin role to use this endpoint.", "x-stability-level": "stable", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappingTeamsCreateRequest" } } } }, "responses": { "201": { "description": "Returns the created integration mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappingTeams" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item_id`. Error codes:\n\n- `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`,\n- `CHANNEL_ALREADY_MAPPED` - channel is already mapped to another `box_item_id`,\n- `TEAM_ALREADY_MAPPED` - team is already mapped to another `box_item_id`,\n- `BOX_ENTERPRISE_MISMATCH` - Box folder must be owned by the enterprise, which is configured to use Box as Content layer for Teams,\n- `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise\n- `FOLDER_ALREADY_MAPPED` - Box folder must not be mapped to another integration mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns a `not_found` error if the integration mapping, record or folder could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "Create Teams integration mapping", "source": "curl -L -X POST \"https://api.box.com/2.0/integration_mappings/teams\" \\\n -H \"authorization: Bearer \" \\\n -H 'content-type: application/json' \\\n -d '{\n \"partner_item\": {\n \"id\": \"19%3ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2\",\n \"type\": \"channel\",\n \"team_id\": \"hjgjgjg-bhhj-564a-b643-hghgj685u\",\n \"tenant_id\": \"E1234567\"\n },\n \"box_item\": {\n \"id\": \"42037322\",\n \"type\": \"folder\"\n }\n }'" }, { "lang": "dotnet", "label": "Create Teams integration mapping", "source": "await userClient.IntegrationMappings.CreateTeamsIntegrationMappingAsync(requestBody: new IntegrationMappingTeamsCreateRequest(partnerItem: new IntegrationMappingPartnerItemTeamsCreateRequest(type: IntegrationMappingPartnerItemTeamsCreateRequestTypeField.Channel, id: partnerItemId, tenantId: tenantId, teamId: teamId), boxItem: new FolderReference(id: folder.Id)));" }, { "lang": "swift", "label": "Create Teams integration mapping", "source": "try await userClient.integrationMappings.createTeamsIntegrationMapping(requestBody: IntegrationMappingTeamsCreateRequest(partnerItem: IntegrationMappingPartnerItemTeamsCreateRequest(type: IntegrationMappingPartnerItemTeamsCreateRequestTypeField.channel, id: partnerItemId, tenantId: tenantId, teamId: teamId), boxItem: FolderReference(id: folder.id)))" }, { "lang": "java", "label": "Create Teams integration mapping", "source": "userClient.getIntegrationMappings().createTeamsIntegrationMapping(new IntegrationMappingTeamsCreateRequest(new IntegrationMappingPartnerItemTeamsCreateRequest(IntegrationMappingPartnerItemTeamsCreateRequestTypeField.CHANNEL, partnerItemId, tenantId, teamId), new FolderReference(folder.getId())))" }, { "lang": "node", "label": "Create Teams integration mapping", "source": "await userClient.integrationMappings.createTeamsIntegrationMapping({\n partnerItem: {\n type: 'channel' as IntegrationMappingPartnerItemTeamsCreateRequestTypeField,\n id: partnerItemId,\n tenantId: tenantId,\n teamId: teamId,\n } satisfies IntegrationMappingPartnerItemTeamsCreateRequest,\n boxItem: new FolderReference({ id: folder.id }),\n} satisfies IntegrationMappingTeamsCreateRequest);" }, { "lang": "python", "label": "Create Teams integration mapping", "source": "user_client.integration_mappings.create_teams_integration_mapping(\n IntegrationMappingPartnerItemTeamsCreateRequest(\n type=IntegrationMappingPartnerItemTeamsCreateRequestTypeField.CHANNEL,\n id=partner_item_id,\n tenant_id=tenant_id,\n team_id=team_id,\n ),\n FolderReference(id=folder.id),\n)" } ] } }, "/integration_mappings/teams/{integration_mapping_id}": { "put": { "operationId": "put_integration_mappings_teams_id", "summary": "Update Teams integration mapping", "description": "Updates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint.", "x-stability-level": "stable", "parameters": [ { "name": "integration_mapping_id", "in": "path", "description": "An ID of an integration mapping.", "required": true, "schema": { "type": "string" }, "example": "11235432" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "box_item": { "allOf": [ { "$ref": "#/components/schemas/FolderReference" }, { "description": "The Box folder, to which the object from the partner app domain is mapped." } ] } } } } } }, "responses": { "200": { "description": "Returns the updated integration mapping object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMappingTeams" } } } }, "400": { "description": "Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item`. Error codes:\n\n- `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`,\n- `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise,\n- `FOLDER_ALREADY_MAPPED` - Box folder must not be mapped to another integration mapping.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returns `not_found` if integration mapping object was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "Update Teams integration mapping", "source": "curl -L -X PUT \"https://api.box.com/2.0/integration_mappings/teams/12345\" \\\n -H \"authorization: Bearer \" \\\n -H 'content-type: application/json'" }, { "lang": "dotnet", "label": "Update Teams integration mapping", "source": "await userClient.IntegrationMappings.UpdateTeamsIntegrationMappingByIdAsync(integrationMappingId: integrationMappingId, requestBody: new UpdateTeamsIntegrationMappingByIdRequestBody() { BoxItem = new FolderReference(id: \"1234567\") });" }, { "lang": "swift", "label": "Update Teams integration mapping", "source": "try await userClient.integrationMappings.updateTeamsIntegrationMappingById(integrationMappingId: integrationMappingId, requestBody: UpdateTeamsIntegrationMappingByIdRequestBody(boxItem: FolderReference(id: \"1234567\")))" }, { "lang": "java", "label": "Update Teams integration mapping", "source": "userClient.getIntegrationMappings().updateTeamsIntegrationMappingById(integrationMappingId, new UpdateTeamsIntegrationMappingByIdRequestBody.Builder().boxItem(new FolderReference(\"1234567\")).build())" }, { "lang": "node", "label": "Update Teams integration mapping", "source": "await userClient.integrationMappings.updateTeamsIntegrationMappingById(\n integrationMappingId,\n {\n requestBody: {\n boxItem: new FolderReference({ id: '1234567' }),\n } satisfies UpdateTeamsIntegrationMappingByIdRequestBody,\n } satisfies UpdateTeamsIntegrationMappingByIdOptionalsInput,\n);" }, { "lang": "python", "label": "Update Teams integration mapping", "source": "user_client.integration_mappings.update_teams_integration_mapping_by_id(\n integration_mapping_id, box_item=FolderReference(id=\"1234567\")\n)" } ] }, "delete": { "operationId": "delete_integration_mappings_teams_id", "summary": "Delete Teams integration mapping", "description": "Deletes a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). You need Admin or Co-Admin role to use this endpoint.", "x-stability-level": "stable", "parameters": [ { "name": "integration_mapping_id", "in": "path", "description": "An ID of an integration mapping.", "required": true, "schema": { "type": "string" }, "example": "11235432" } ], "responses": { "204": { "description": "Empty body in response." }, "404": { "description": "Returns a `not_found` error if the integration mapping could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "integration_mappings", "tags": [ "Integration mappings" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete Teams integration mapping", "source": "curl -L -X DELETE \"https://api.box.com/2.0/integration_mappings/teams/342423\" \\\n -H \"authorization: Bearer \" \\\n -d ''" }, { "lang": "dotnet", "label": "Delete Teams integration mapping", "source": "await userClient.IntegrationMappings.DeleteTeamsIntegrationMappingByIdAsync(integrationMappingId: integrationMappingId);" }, { "lang": "swift", "label": "Delete Teams integration mapping", "source": "try await userClient.integrationMappings.deleteTeamsIntegrationMappingById(integrationMappingId: integrationMappingId)" }, { "lang": "java", "label": "Delete Teams integration mapping", "source": "userClient.getIntegrationMappings().deleteTeamsIntegrationMappingById(integrationMappingId)" }, { "lang": "node", "label": "Delete Teams integration mapping", "source": "await userClient.integrationMappings.deleteTeamsIntegrationMappingById(\n integrationMappingId,\n);" }, { "lang": "python", "label": "Delete Teams integration mapping", "source": "user_client.integration_mappings.delete_teams_integration_mapping_by_id(\n integration_mapping_id\n)" } ] } }, "/ai/ask": { "post": { "operationId": "post_ai_ask", "summary": "Ask question", "description": "Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.\n\nYou can ask a question about a single file, several files, or the entire contents of a Box Hub. To search across and ask questions about everything in a Box Hub, send a single item with `type` set to `hubs` and the Hub's ID as the `id`. Box AI answers the question using the indexed content of all files in that Hub.\n\nAsking questions about a Box Hub requires Box AI for Hubs to be enabled in the Admin Console before the Hub is created, so that its content is indexed.", "x-stability-level": "stable", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAsk" } } } }, "responses": { "200": { "description": "A successful response including the answer from the LLM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiResponse--Full" } } } }, "204": { "description": "No content is available to answer the question. This is returned when the request item is a hub, but content in the hubs is not indexed. To ensure content in the hub is indexed, make sure Box AI for Hubs in the Admin Console was enabled before hub creation." }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai", "tags": [ "AI" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Ask question", "source": "curl -i -L -X POST \"https://api.box.com/2.0/ai/ask\" \\\n -H \"content-type: application/json\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"mode\": \"single_item_qa\",\n \"prompt\": \"What is the value provided by public APIs based on this document?\",\n \"items\": [\n {\n \"type\": \"file\",\n \"id\": \"9842787262\"\n }\n ],\n \"dialogue_history\": [\n {\n \"prompt\": \"Make my email about public APIs sound more professional\",\n \"answer\": \"Here is the first draft of your professional email about public APIs\",\n \"created_at\": \"2013-12-12T10:53:43-08:00\"\n }\n ],\n \"include_citations\": true,\n \"ai_agent\": {\n \"type\": \"ai_agent_ask\",\n \"long_text\": {\n \"model\": \"azure__openai__gpt_4o_mini\",\n \"prompt_template\": \"It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?\"\n },\n \"basic_text\": {\n \"model\": \"azure__openai__gpt_4o_mini\"\n }\n }\n }'" }, { "lang": "dotnet", "label": "Ask question", "source": "await client.Ai.CreateAiAskAsync(requestBody: new AiAsk(mode: AiAskModeField.SingleItemQa, prompt: \"Which direction does the Sun rise?\", items: Array.AsReadOnly(new [] {new AiItemAsk(id: fileToAsk.Id, type: AiItemAskTypeField.File) { Content = \"The Sun rises in the east\" }})));" }, { "lang": "swift", "label": "Ask question", "source": "try await client.ai.createAiAsk(requestBody: AiAsk(mode: AiAskModeField.singleItemQa, prompt: \"Which direction does the Sun rise?\", items: [AiItemAsk(id: fileToAsk.id, type: AiItemAskTypeField.file, content: \"The Sun rises in the east\")]))" }, { "lang": "java", "label": "Ask question", "source": "client.getAi().createAiAsk(new AiAsk.Builder(AiAskModeField.SINGLE_ITEM_QA, \"Which direction does the Sun rise?\", Arrays.asList(new AiItemAsk.Builder(fileToAsk.getId(), AiItemAskTypeField.FILE).content(\"The Sun rises in the east\").build())).aiAgent(aiAskAgentBasicTextConfig).build())" }, { "lang": "node", "label": "Ask question", "source": "await client.ai.createAiAsk({\n mode: 'single_item_qa' as AiAskModeField,\n prompt: 'Which direction does the Sun rise?',\n items: [\n {\n id: fileToAsk.id,\n type: 'file' as AiItemAskTypeField,\n content: 'The Sun rises in the east',\n } satisfies AiItemAsk,\n ],\n aiAgent: aiAskAgentBasicTextConfig,\n} satisfies AiAsk);" }, { "lang": "python", "label": "Ask question", "source": "client.ai.create_ai_ask(\n CreateAiAskMode.SINGLE_ITEM_QA,\n \"Which direction does the Sun rise?\",\n [\n AiItemAsk(\n id=file_to_ask.id,\n type=AiItemAskTypeField.FILE,\n content=\"The Sun rises in the east\",\n )\n ],\n ai_agent=ai_ask_agent_basic_text_config,\n)" } ] } }, "/ai/text_gen": { "post": { "operationId": "post_ai_text_gen", "summary": "Generate text", "description": "Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt.", "x-stability-level": "stable", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiTextGen" } } } }, "responses": { "200": { "description": "A successful response including the answer from the LLM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiResponse" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai", "tags": [ "AI" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Generate text", "source": "curl -i -L -X POST \"https://api.box.com/2.0/ai/text_gen\" \\\n -H \"content-type: application/json\" \\\n -H \"authorization: Bearer \" \\\n -d '{\n \"prompt\": \"Write a social media post about protein powder.\",\n \"items\": [\n {\n \"id\": \"12345678\",\n \"type\": \"file\",\n \"content\": \"More information about protein powders\"\n }\n ],\n \"dialogue_history\": [\n {\n \"prompt\": \"Can you add some more information?\",\n \"answer\": \"Public API schemas provide necessary information to integrate with APIs...\",\n \"created_at\": \"2013-12-12T11:20:43-08:00\"\n }\n ],\n \"ai_agent\": {\n \"type\": \"ai_agent_text_gen\",\n \"basic_gen\": {\n \"model\": \"azure__openai__gpt_4o_mini\"\n }\n }\n }'" }, { "lang": "dotnet", "label": "Generate text", "source": "await client.Ai.CreateAiTextGenAsync(requestBody: new AiTextGen(prompt: \"Paraphrase the documents\", items: Array.AsReadOnly(new [] {new AiTextGenItemsField(id: fileToAsk.Id, type: AiTextGenItemsTypeField.File) { Content = \"The Earth goes around the Sun. The Sun rises in the east in the morning.\" }})) { DialogueHistory = Array.AsReadOnly(new [] {new AiDialogueHistory() { Prompt = \"What does the earth go around?\", Answer = \"The Sun\", CreatedAt = Utils.DateTimeFromString(dateTime: \"2021-01-01T00:00:00Z\") },new AiDialogueHistory() { Prompt = \"On Earth, where does the Sun rise?\", Answer = \"east\", CreatedAt = Utils.DateTimeFromString(dateTime: \"2021-01-01T00:00:00Z\") }}) });" }, { "lang": "swift", "label": "Generate text", "source": "try await client.ai.createAiTextGen(requestBody: AiTextGen(prompt: \"Paraphrase the documents\", items: [AiTextGenItemsField(id: fileToAsk.id, type: AiTextGenItemsTypeField.file, content: \"The Earth goes around the Sun. The Sun rises in the east in the morning.\")], dialogueHistory: [AiDialogueHistory(prompt: \"What does the earth go around?\", answer: \"The Sun\", createdAt: try Utils.Dates.dateTimeFromString(dateTime: \"2021-01-01T00:00:00Z\")), AiDialogueHistory(prompt: \"On Earth, where does the Sun rise?\", answer: \"east\", createdAt: try Utils.Dates.dateTimeFromString(dateTime: \"2021-01-01T00:00:00Z\"))]))" }, { "lang": "java", "label": "Generate text", "source": "client.getAi().createAiTextGen(new AiTextGen.Builder(\"Paraphrase the documents\", Arrays.asList(new AiTextGenItemsField.Builder(fileToAsk.getId()).type(AiTextGenItemsTypeField.FILE).content(\"The Earth goes around the Sun. The Sun rises in the east in the morning.\").build())).dialogueHistory(Arrays.asList(new AiDialogueHistory.Builder().prompt(\"What does the earth go around?\").answer(\"The Sun\").createdAt(dateTimeFromString(\"2021-01-01T00:00:00Z\")).build(), new AiDialogueHistory.Builder().prompt(\"On Earth, where does the Sun rise?\").answer(\"east\").createdAt(dateTimeFromString(\"2021-01-01T00:00:00Z\")).build())).build())" }, { "lang": "node", "label": "Generate text", "source": "await client.ai.createAiTextGen({\n prompt: 'Paraphrase the documents',\n items: [\n new AiTextGenItemsField({\n id: fileToAsk.id,\n type: 'file' as AiTextGenItemsTypeField,\n content:\n 'The Earth goes around the Sun. The Sun rises in the east in the morning.',\n }),\n ],\n dialogueHistory: [\n {\n prompt: 'What does the earth go around?',\n answer: 'The Sun',\n createdAt: dateTimeFromString('2021-01-01T00:00:00Z'),\n } satisfies AiDialogueHistory,\n {\n prompt: 'On Earth, where does the Sun rise?',\n answer: 'east',\n createdAt: dateTimeFromString('2021-01-01T00:00:00Z'),\n } satisfies AiDialogueHistory,\n ],\n} satisfies AiTextGen);" }, { "lang": "python", "label": "Generate text", "source": "client.ai.create_ai_text_gen(\n \"Paraphrase the documents\",\n [\n CreateAiTextGenItems(\n id=file_to_ask.id,\n type=CreateAiTextGenItemsTypeField.FILE,\n content=\"The Earth goes around the Sun. The Sun rises in the east in the morning.\",\n )\n ],\n dialogue_history=[\n AiDialogueHistory(\n prompt=\"What does the earth go around?\",\n answer=\"The Sun\",\n created_at=date_time_from_string(\"2021-01-01T00:00:00Z\"),\n ),\n AiDialogueHistory(\n prompt=\"On Earth, where does the Sun rise?\",\n answer=\"east\",\n created_at=date_time_from_string(\"2021-01-01T00:00:00Z\"),\n ),\n ],\n)" } ] } }, "/ai_agent_default": { "get": { "operationId": "get_ai_agent_default", "summary": "Get AI agent default configuration", "description": "Get the AI agent default config.", "x-stability-level": "stable", "parameters": [ { "name": "mode", "in": "query", "description": "The mode to filter the agent config to return.", "required": true, "schema": { "type": "string", "enum": [ "ask", "text_gen", "extract", "extract_structured" ] }, "example": "ask" }, { "name": "language", "in": "query", "description": "The ISO language code to return the agent config for. If the language is not supported the default agent config is returned.", "required": false, "schema": { "type": "string" }, "example": "ja" }, { "name": "model", "in": "query", "description": "The model to return the default agent config for.", "required": false, "schema": { "type": "string" }, "example": "azure__openai__gpt_4o_mini" } ], "responses": { "200": { "description": "A successful response including the default agent configuration. This response can be one of the following four objects:\n\n- AI agent for questions\n- AI agent for text generation\n- AI agent for freeform metadata extraction\n- AI agent for structured metadata extraction. The response depends on the agent configuration requested in this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAgent" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai", "tags": [ "AI" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Get AI agent default configuration", "source": "curl -L -X GET \"https://api.box.com/2.0/ai_agent_default?mode=text_gen\" \\\n -H 'Authorization: Bearer '" }, { "lang": "dotnet", "label": "Get AI agent default configuration", "source": "await client.Ai.GetAiAgentDefaultConfigAsync(queryParams: new GetAiAgentDefaultConfigQueryParams(mode: GetAiAgentDefaultConfigQueryParamsModeField.Ask) { Language = \"en-US\" });" }, { "lang": "swift", "label": "Get AI agent default configuration", "source": "try await client.ai.getAiAgentDefaultConfig(queryParams: GetAiAgentDefaultConfigQueryParams(mode: GetAiAgentDefaultConfigQueryParamsModeField.ask, language: \"en-US\"))" }, { "lang": "java", "label": "Get AI agent default configuration", "source": "client.getAi().getAiAgentDefaultConfig(new GetAiAgentDefaultConfigQueryParams.Builder(GetAiAgentDefaultConfigQueryParamsModeField.ASK).language(\"en-US\").build())" }, { "lang": "node", "label": "Get AI agent default configuration", "source": "await client.ai.getAiAgentDefaultConfig({\n mode: 'ask' as GetAiAgentDefaultConfigQueryParamsModeField,\n language: 'en-US',\n} satisfies GetAiAgentDefaultConfigQueryParams);" }, { "lang": "python", "label": "Get AI agent default configuration", "source": "client.ai.get_ai_agent_default_config(GetAiAgentDefaultConfigMode.ASK, language=\"en-US\")" } ] } }, "/ai/extract": { "post": { "operationId": "post_ai_extract", "summary": "Extract metadata (freeform)", "description": "Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs. In this request, both the prompt and the output can be freeform. Metadata template setup before sending the request is not required.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiExtract" } } } }, "responses": { "200": { "description": "A response including the answer from the LLM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiResponse" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai", "tags": [ "AI" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Extract metadata (freeform)", "source": "curl -i -L 'https://api.box.com/2.0/ai/extract' \\\n -H 'content-type: application/json' \\\n -H 'authorization: Bearer ' \\\n -d '{\n \"prompt\": \"Extract data related to contract conditions\",\n \"items\": [\n {\n \"type\": \"file\",\n \"id\": \"1497741268097\"\n }\n ],\n \"ai_agent\": {\n \"type\": \"ai_agent_extract\",\n \"long_text\": {\n \"model\": \"azure__openai__gpt_4o_mini\",\n \"prompt_template\": \"It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?\"\n },\n \"basic_text\": {\n \"model\": \"azure__openai__gpt_4o_mini\"\n }\n }\n }'" }, { "lang": "dotnet", "label": "Extract metadata (freeform)", "source": "await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: \"firstName, lastName, location, yearOfBirth, company\", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));" }, { "lang": "swift", "label": "Extract metadata (freeform)", "source": "try await client.ai.createAiExtract(requestBody: AiExtract(prompt: \"firstName, lastName, location, yearOfBirth, company\", items: [AiItemBase(id: file.id)]))" }, { "lang": "java", "label": "Extract metadata (freeform)", "source": "client.getAi().createAiExtract(new AiExtract.Builder(\"firstName, lastName, location, yearOfBirth, company\", Arrays.asList(new AiItemBase(file.getId()))).aiAgent(aiExtractAgentBasicTextConfig).build())" }, { "lang": "node", "label": "Extract metadata (freeform)", "source": "await client.ai.createAiExtract({\n prompt: 'firstName, lastName, location, yearOfBirth, company',\n items: [new AiItemBase({ id: file.id })],\n aiAgent: aiExtractAgentBasicTextConfig,\n} satisfies AiExtract);" }, { "lang": "python", "label": "Extract metadata (freeform)", "source": "client.ai.create_ai_extract(\n \"firstName, lastName, location, yearOfBirth, company\",\n [AiItemBase(id=file.id)],\n ai_agent=ai_extract_agent_basic_text_config,\n)" } ] } }, "/ai/extract_structured": { "post": { "operationId": "post_ai_extract_structured", "summary": "Extract metadata (structured)", "description": "Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs.\n\nTo define the extraction structure, provide either a metadata template or a list of fields. To learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or use the [metadata template API](/guides/metadata/templates/create).\n\nThis endpoint also supports [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent).\n\nFor information about supported file formats and languages, see the [Extract metadata from file (structured)](/guides/box-ai/ai-tutorials/extract-metadata-structured) API guide.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiExtractStructured" } } } }, "responses": { "200": { "description": "A successful response including the answer from the LLM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiExtractStructuredResponse" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai", "tags": [ "AI" ], "x-box-enable-explorer": false, "x-codeSamples": [ { "lang": "curl", "label": "Extract metadata (structured)", "source": "curl -i -L 'https://api.box.com/2.0/ai/extract_structured' \\\n -H 'content-type: application/json' \\\n -H 'authorization: Bearer ' \\\n -d '{\n \"items\": [\n {\n \"id\": \"12345678\",\n \"type\": \"file\",\n \"content\": \"This is file content.\"\n }\n ],\n \"metadata_template\": {\n \"template_key\": \"\",\n \"type\": \"metadata_template\",\n \"scope\": \"\"\n },\n \"fields\": [\n {\n \"key\": \"name\",\n \"description\": \"The name of the person.\",\n \"displayName\": \"Name\",\n \"prompt\": \"The name is the first and last name from the email address.\",\n \"type\": \"string\",\n \"options\": [\n {\n \"key\": \"First Name\"\n },\n {\n \"key\": \"Last Name\"\n }\n ]\n }\n ],\n \"ai_agent\": {\n \"type\": \"ai_agent_extract_structured\",\n \"long_text\": {\n \"model\": \"azure__openai__gpt_4o_mini\"\n },\n \"basic_text\": {\n \"model\": \"azure__openai__gpt_4o_mini\"\n }\n }\n }'" }, { "lang": "dotnet", "label": "Extract metadata (structured)", "source": "await client.Ai.CreateAiExtractStructuredAsync(requestBody: new AiExtractStructured(items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})) { Fields = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsField(key: \"firstName\") { DisplayName = \"First name\", Description = \"Person first name\", Prompt = \"What is the your first name?\", Type = \"string\" },new AiExtractStructuredFieldsField(key: \"lastName\") { DisplayName = \"Last name\", Description = \"Person last name\", Prompt = \"What is the your last name?\", Type = \"string\" },new AiExtractStructuredFieldsField(key: \"dateOfBirth\") { DisplayName = \"Birth date\", Description = \"Person date of birth\", Prompt = \"What is the date of your birth?\", Type = \"date\" },new AiExtractStructuredFieldsField(key: \"age\") { DisplayName = \"Age\", Description = \"Person age\", Prompt = \"How old are you?\", Type = \"float\" },new AiExtractStructuredFieldsField(key: \"hobby\") { DisplayName = \"Hobby\", Description = \"Person hobby\", Prompt = \"What is your hobby?\", Type = \"multiSelect\", Options = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsOptionsField(key: \"guitar\"),new AiExtractStructuredFieldsOptionsField(key: \"books\")}) },new AiExtractStructuredFieldsField(key: \"address\") { DisplayName = \"Address\", Description = \"Person address\", Type = \"struct\", Prompt = \"Extract the full mailing address.\", Fields = Array.AsReadOnly(new [] {new AiExtractSubField(key: \"street\") { DisplayName = \"Street\", Type = \"string\" },new AiExtractSubField(key: \"city\") { DisplayName = \"City\", Type = \"string\" },new AiExtractSubField(key: \"state\") { DisplayName = \"State\", Type = \"string\" },new AiExtractSubField(key: \"zip\") { DisplayName = \"Zip\", Type = \"string\" },new AiExtractSubField(key: \"country\") { DisplayName = \"Country\", Type = \"string\" }}) },new AiExtractStructuredFieldsField(key: \"work_history\") { DisplayName = \"Work history\", Description = \"Person work history\", Type = \"table\", Prompt = \"Extract each job as a row.\", Fields = Array.AsReadOnly(new [] {new AiExtractSubField(key: \"job_title\") { DisplayName = \"Job title\", Type = \"string\" },new AiExtractSubField(key: \"company\") { DisplayName = \"Company\", Type = \"string\" },new AiExtractSubField(key: \"start_year\") { DisplayName = \"Start year\", Type = \"string\" },new AiExtractSubField(key: \"end_year\") { DisplayName = \"End year\", Type = \"string\" }}) }}), IncludeConfidenceScore = true, IncludeReference = true });" }, { "lang": "swift", "label": "Extract metadata (structured)", "source": "try await client.ai.createAiExtractStructured(requestBody: AiExtractStructured(fields: [AiExtractStructuredFieldsField(key: \"firstName\", displayName: \"First name\", description: \"Person first name\", prompt: \"What is the your first name?\", type: \"string\"), AiExtractStructuredFieldsField(key: \"lastName\", displayName: \"Last name\", description: \"Person last name\", prompt: \"What is the your last name?\", type: \"string\"), AiExtractStructuredFieldsField(key: \"dateOfBirth\", displayName: \"Birth date\", description: \"Person date of birth\", prompt: \"What is the date of your birth?\", type: \"date\"), AiExtractStructuredFieldsField(key: \"age\", displayName: \"Age\", description: \"Person age\", prompt: \"How old are you?\", type: \"float\"), AiExtractStructuredFieldsField(key: \"hobby\", displayName: \"Hobby\", description: \"Person hobby\", prompt: \"What is your hobby?\", type: \"multiSelect\", options: [AiExtractStructuredFieldsOptionsField(key: \"guitar\"), AiExtractStructuredFieldsOptionsField(key: \"books\")]), AiExtractStructuredFieldsField(key: \"address\", displayName: \"Address\", description: \"Person address\", type: \"struct\", prompt: \"Extract the full mailing address.\", fields: [AiExtractSubField(key: \"street\", displayName: \"Street\", type: \"string\"), AiExtractSubField(key: \"city\", displayName: \"City\", type: \"string\"), AiExtractSubField(key: \"state\", displayName: \"State\", type: \"string\"), AiExtractSubField(key: \"zip\", displayName: \"Zip\", type: \"string\"), AiExtractSubField(key: \"country\", displayName: \"Country\", type: \"string\")]), AiExtractStructuredFieldsField(key: \"work_history\", displayName: \"Work history\", description: \"Person work history\", type: \"table\", prompt: \"Extract each job as a row.\", fields: [AiExtractSubField(key: \"job_title\", displayName: \"Job title\", type: \"string\"), AiExtractSubField(key: \"company\", displayName: \"Company\", type: \"string\"), AiExtractSubField(key: \"start_year\", displayName: \"Start year\", type: \"string\"), AiExtractSubField(key: \"end_year\", displayName: \"End year\", type: \"string\")])], items: [AiItemBase(id: file.id)], includeConfidenceScore: true, includeReference: true))" }, { "lang": "java", "label": "Extract metadata (structured)", "source": "client.getAi().createAiExtractStructured(new AiExtractStructured.Builder(Arrays.asList(new AiItemBase(file.getId()))).fields(Arrays.asList(new AiExtractStructuredFieldsField.Builder(\"firstName\").description(\"Person first name\").displayName(\"First name\").prompt(\"What is the your first name?\").type(\"string\").build(), new AiExtractStructuredFieldsField.Builder(\"lastName\").description(\"Person last name\").displayName(\"Last name\").prompt(\"What is the your last name?\").type(\"string\").build(), new AiExtractStructuredFieldsField.Builder(\"dateOfBirth\").description(\"Person date of birth\").displayName(\"Birth date\").prompt(\"What is the date of your birth?\").type(\"date\").build(), new AiExtractStructuredFieldsField.Builder(\"age\").description(\"Person age\").displayName(\"Age\").prompt(\"How old are you?\").type(\"float\").build(), new AiExtractStructuredFieldsField.Builder(\"hobby\").description(\"Person hobby\").displayName(\"Hobby\").prompt(\"What is your hobby?\").type(\"multiSelect\").options(Arrays.asList(new AiExtractStructuredFieldsOptionsField(\"guitar\"), new AiExtractStructuredFieldsOptionsField(\"books\"))).build(), new AiExtractStructuredFieldsField.Builder(\"address\").description(\"Person address\").displayName(\"Address\").prompt(\"Extract the full mailing address.\").type(\"struct\").fields(Arrays.asList(new AiExtractSubField.Builder(\"street\").displayName(\"Street\").type(\"string\").build(), new AiExtractSubField.Builder(\"city\").displayName(\"City\").type(\"string\").build(), new AiExtractSubField.Builder(\"state\").displayName(\"State\").type(\"string\").build(), new AiExtractSubField.Builder(\"zip\").displayName(\"Zip\").type(\"string\").build(), new AiExtractSubField.Builder(\"country\").displayName(\"Country\").type(\"string\").build())).build(), new AiExtractStructuredFieldsField.Builder(\"work_history\").description(\"Person work history\").displayName(\"Work history\").prompt(\"Extract each job as a row.\").type(\"table\").fields(Arrays.asList(new AiExtractSubField.Builder(\"job_title\").displayName(\"Job title\").type(\"string\").build(), new AiExtractSubField.Builder(\"company\").displayName(\"Company\").type(\"string\").build(), new AiExtractSubField.Builder(\"start_year\").displayName(\"Start year\").type(\"string\").build(), new AiExtractSubField.Builder(\"end_year\").displayName(\"End year\").type(\"string\").build())).build())).aiAgent(aiExtractStructuredAgentBasicTextConfig).includeConfidenceScore(true).includeReference(true).build())" }, { "lang": "node", "label": "Extract metadata (structured)", "source": "await client.ai.createAiExtractStructured({\n fields: [\n {\n key: 'firstName',\n displayName: 'First name',\n description: 'Person first name',\n prompt: 'What is the your first name?',\n type: 'string',\n } satisfies AiExtractStructuredFieldsField,\n {\n key: 'lastName',\n displayName: 'Last name',\n description: 'Person last name',\n prompt: 'What is the your last name?',\n type: 'string',\n } satisfies AiExtractStructuredFieldsField,\n {\n key: 'dateOfBirth',\n displayName: 'Birth date',\n description: 'Person date of birth',\n prompt: 'What is the date of your birth?',\n type: 'date',\n } satisfies AiExtractStructuredFieldsField,\n {\n key: 'age',\n displayName: 'Age',\n description: 'Person age',\n prompt: 'How old are you?',\n type: 'float',\n } satisfies AiExtractStructuredFieldsField,\n {\n key: 'hobby',\n displayName: 'Hobby',\n description: 'Person hobby',\n prompt: 'What is your hobby?',\n type: 'multiSelect',\n options: [\n { key: 'guitar' } satisfies AiExtractStructuredFieldsOptionsField,\n { key: 'books' } satisfies AiExtractStructuredFieldsOptionsField,\n ],\n } satisfies AiExtractStructuredFieldsField,\n {\n key: 'address',\n displayName: 'Address',\n description: 'Person address',\n type: 'struct',\n prompt: 'Extract the full mailing address.',\n fields: [\n {\n key: 'street',\n displayName: 'Street',\n type: 'string',\n } satisfies AiExtractSubField,\n {\n key: 'city',\n displayName: 'City',\n type: 'string',\n } satisfies AiExtractSubField,\n {\n key: 'state',\n displayName: 'State',\n type: 'string',\n } satisfies AiExtractSubField,\n {\n key: 'zip',\n displayName: 'Zip',\n type: 'string',\n } satisfies AiExtractSubField,\n {\n key: 'country',\n displayName: 'Country',\n type: 'string',\n } satisfies AiExtractSubField,\n ],\n } satisfies AiExtractStructuredFieldsField,\n {\n key: 'work_history',\n displayName: 'Work history',\n description: 'Person work history',\n type: 'table',\n prompt: 'Extract each job as a row.',\n fields: [\n {\n key: 'job_title',\n displayName: 'Job title',\n type: 'string',\n } satisfies AiExtractSubField,\n {\n key: 'company',\n displayName: 'Company',\n type: 'string',\n } satisfies AiExtractSubField,\n {\n key: 'start_year',\n displayName: 'Start year',\n type: 'string',\n } satisfies AiExtractSubField,\n {\n key: 'end_year',\n displayName: 'End year',\n type: 'string',\n } satisfies AiExtractSubField,\n ],\n } satisfies AiExtractStructuredFieldsField,\n ],\n items: [new AiItemBase({ id: file.id })],\n includeConfidenceScore: true,\n includeReference: true,\n aiAgent: aiExtractStructuredAgentBasicTextConfig,\n} satisfies AiExtractStructured);" }, { "lang": "python", "label": "Extract metadata (structured)", "source": "client.ai.create_ai_extract_structured(\n [AiItemBase(id=file.id)],\n fields=[\n CreateAiExtractStructuredFields(\n key=\"firstName\",\n display_name=\"First name\",\n description=\"Person first name\",\n prompt=\"What is the your first name?\",\n type=\"string\",\n ),\n CreateAiExtractStructuredFields(\n key=\"lastName\",\n display_name=\"Last name\",\n description=\"Person last name\",\n prompt=\"What is the your last name?\",\n type=\"string\",\n ),\n CreateAiExtractStructuredFields(\n key=\"dateOfBirth\",\n display_name=\"Birth date\",\n description=\"Person date of birth\",\n prompt=\"What is the date of your birth?\",\n type=\"date\",\n ),\n CreateAiExtractStructuredFields(\n key=\"age\",\n display_name=\"Age\",\n description=\"Person age\",\n prompt=\"How old are you?\",\n type=\"float\",\n ),\n CreateAiExtractStructuredFields(\n key=\"hobby\",\n display_name=\"Hobby\",\n description=\"Person hobby\",\n prompt=\"What is your hobby?\",\n type=\"multiSelect\",\n options=[\n CreateAiExtractStructuredFieldsOptionsField(key=\"guitar\"),\n CreateAiExtractStructuredFieldsOptionsField(key=\"books\"),\n ],\n ),\n CreateAiExtractStructuredFields(\n key=\"address\",\n display_name=\"Address\",\n description=\"Person address\",\n type=\"struct\",\n prompt=\"Extract the full mailing address.\",\n fields=[\n AiExtractSubField(key=\"street\", display_name=\"Street\", type=\"string\"),\n AiExtractSubField(key=\"city\", display_name=\"City\", type=\"string\"),\n AiExtractSubField(key=\"state\", display_name=\"State\", type=\"string\"),\n AiExtractSubField(key=\"zip\", display_name=\"Zip\", type=\"string\"),\n AiExtractSubField(key=\"country\", display_name=\"Country\", type=\"string\"),\n ],\n ),\n CreateAiExtractStructuredFields(\n key=\"work_history\",\n display_name=\"Work history\",\n description=\"Person work history\",\n type=\"table\",\n prompt=\"Extract each job as a row.\",\n fields=[\n AiExtractSubField(\n key=\"job_title\", display_name=\"Job title\", type=\"string\"\n ),\n AiExtractSubField(key=\"company\", display_name=\"Company\", type=\"string\"),\n AiExtractSubField(\n key=\"start_year\", display_name=\"Start year\", type=\"string\"\n ),\n AiExtractSubField(\n key=\"end_year\", display_name=\"End year\", type=\"string\"\n ),\n ],\n ),\n ],\n ai_agent=ai_extract_structured_agent_basic_text_config,\n include_confidence_score=True,\n include_reference=True,\n)" } ] } }, "/ai_agents": { "get": { "operationId": "get_ai_agents", "summary": "List AI agents", "description": "Lists AI agents based on the provided parameters.", "parameters": [ { "name": "mode", "in": "query", "description": "The mode to filter the agent config to return. Possible values are: `ask`, `text_gen`, and `extract`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ask", "text_gen", "extract" ], "explode": false }, { "name": "fields", "in": "query", "description": "The fields to return in the response.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ask", "text_gen", "extract" ], "explode": false }, { "name": "agent_state", "in": "query", "description": "The state of the agents to return. Possible values are: `enabled`, `disabled` and `enabled_for_selected_users`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "enabled" ], "explode": false }, { "name": "include_box_default", "in": "query", "description": "Whether to include the Box default agents in the response.", "required": false, "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "A successful response including the agents list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiMultipleAgentResponse" } } } }, "400": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai_studio", "tags": [ "AI Studio" ], "x-codeSamples": [ { "lang": "curl", "label": "List AI agents", "source": "curl -i -X GET \"https://api.box.com/2.0/ai_agents\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List AI agents", "source": "await client.AiStudio.GetAiAgentsAsync();" }, { "lang": "swift", "label": "List AI agents", "source": "try await client.aiStudio.getAiAgents()" }, { "lang": "java", "label": "List AI agents", "source": "client.getAiStudio().getAiAgents()" }, { "lang": "node", "label": "List AI agents", "source": "await client.aiStudio.getAiAgents();" }, { "lang": "python", "label": "List AI agents", "source": "client.ai_studio.get_ai_agents()" } ] }, "post": { "operationId": "post_ai_agents", "summary": "Create AI agent", "description": "Creates an AI agent. At least one of the following capabilities must be provided: `ask`, `text_gen`, `extract`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiAgent" } } } }, "responses": { "200": { "description": "Definition of created AI agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSingleAgentResponse--Full" } } } }, "400": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai_studio", "tags": [ "AI Studio" ], "x-codeSamples": [ { "lang": "curl", "label": "Create AI agent", "source": "curl -i -L -X POST \"https://api.box.com/2.0/ai_agents\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"type\": \"ai_agent\",\n \"name\": \"My AI Agent\",\n \"access_state\": \"enabled\",\n \"ask\": {\n \"type\": \"ai_agent_ask\",\n \"access_state\": \"enabled\",\n \"description\": \"Answers questions about documents\"\n }\n }'" }, { "lang": "dotnet", "label": "Create AI agent", "source": "await client.AiStudio.CreateAiAgentAsync(requestBody: new CreateAiAgent(name: agentName, accessState: \"enabled\") { Ask = new AiStudioAgentAsk(accessState: \"enabled\", description: \"desc1\") });" }, { "lang": "swift", "label": "Create AI agent", "source": "try await client.aiStudio.createAiAgent(requestBody: CreateAiAgent(name: agentName, accessState: \"enabled\", ask: AiStudioAgentAsk(accessState: \"enabled\", description: \"desc1\")))" }, { "lang": "java", "label": "Create AI agent", "source": "client.getAiStudio().createAiAgent(new CreateAiAgent.Builder(agentName, \"enabled\").ask(new AiStudioAgentAsk(\"enabled\", \"desc1\")).build())" }, { "lang": "node", "label": "Create AI agent", "source": "await client.aiStudio.createAiAgent({\n name: agentName,\n accessState: 'enabled',\n ask: new AiStudioAgentAsk({ accessState: 'enabled', description: 'desc1' }),\n} satisfies CreateAiAgentInput);" }, { "lang": "python", "label": "Create AI agent", "source": "client.ai_studio.create_ai_agent(\n agent_name,\n \"enabled\",\n ask=AiStudioAgentAsk(access_state=\"enabled\", description=\"desc1\"),\n)" } ] } }, "/ai_agents/{agent_id}": { "put": { "operationId": "put_ai_agents_id", "summary": "Update AI agent", "description": "Updates an AI agent.", "parameters": [ { "name": "agent_id", "in": "path", "description": "The ID of the agent to update.", "required": true, "schema": { "type": "string" }, "example": "1234" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAiAgent" } } } }, "responses": { "200": { "description": "Definition of created AI agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSingleAgentResponse--Full" } } } }, "400": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai_studio", "tags": [ "AI Studio" ], "x-codeSamples": [ { "lang": "curl", "label": "Update AI agent", "source": "curl -i -X PUT \"https://api.box.com/2.0/ai_agents/1234567890\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Update AI agent", "source": "await client.AiStudio.UpdateAiAgentByIdAsync(agentId: createdAgent.Id, requestBody: new CreateAiAgent(name: agentName, accessState: \"enabled\") { Ask = new AiStudioAgentAsk(accessState: \"disabled\", description: \"desc2\") });" }, { "lang": "swift", "label": "Update AI agent", "source": "try await client.aiStudio.updateAiAgentById(agentId: createdAgent.id, requestBody: CreateAiAgent(name: agentName, accessState: \"enabled\", ask: AiStudioAgentAsk(accessState: \"disabled\", description: \"desc2\")))" }, { "lang": "java", "label": "Update AI agent", "source": "client.getAiStudio().updateAiAgentById(createdAgent.getId(), new CreateAiAgent.Builder(agentName, \"enabled\").ask(new AiStudioAgentAsk(\"disabled\", \"desc2\")).build())" }, { "lang": "node", "label": "Update AI agent", "source": "await client.aiStudio.updateAiAgentById(createdAgent.id, {\n name: agentName,\n accessState: 'enabled',\n ask: new AiStudioAgentAsk({ accessState: 'disabled', description: 'desc2' }),\n} satisfies CreateAiAgentInput);" }, { "lang": "python", "label": "Update AI agent", "source": "client.ai_studio.update_ai_agent_by_id(\n created_agent.id,\n agent_name,\n \"enabled\",\n ask=AiStudioAgentAsk(access_state=\"disabled\", description=\"desc2\"),\n)" } ] }, "get": { "operationId": "get_ai_agents_id", "summary": "Get AI agent by agent ID", "description": "Gets an AI Agent using the `agent_id` parameter.", "parameters": [ { "name": "agent_id", "in": "path", "description": "The agent id to get.", "required": true, "schema": { "type": "string" }, "example": "1234" }, { "name": "fields", "in": "query", "description": "The fields to return in the response.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "ask", "text_gen", "extract" ], "explode": false } ], "responses": { "200": { "description": "A successful response including the agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiSingleAgentResponse--Full" } } } }, "400": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai_studio", "tags": [ "AI Studio" ], "x-codeSamples": [ { "lang": "curl", "label": "Get AI agent by agent ID", "source": "curl -i -X GET \"https://api.box.com/2.0/ai_agents/1234567890\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get AI agent by agent ID", "source": "await client.AiStudio.GetAiAgentByIdAsync(agentId: createdAgent.Id, queryParams: new GetAiAgentByIdQueryParams() { Fields = Array.AsReadOnly(new [] {\"ask\"}) });" }, { "lang": "swift", "label": "Get AI agent by agent ID", "source": "try await client.aiStudio.getAiAgentById(agentId: createdAgent.id, queryParams: GetAiAgentByIdQueryParams(fields: [\"ask\"]))" }, { "lang": "java", "label": "Get AI agent by agent ID", "source": "client.getAiStudio().getAiAgentById(createdAgent.getId(), new GetAiAgentByIdQueryParams.Builder().fields(Arrays.asList(\"ask\")).build())" }, { "lang": "node", "label": "Get AI agent by agent ID", "source": "await client.aiStudio.getAiAgentById(createdAgent.id, {\n queryParams: { fields: ['ask'] } satisfies GetAiAgentByIdQueryParams,\n} satisfies GetAiAgentByIdOptionalsInput);" }, { "lang": "python", "label": "Get AI agent by agent ID", "source": "client.ai_studio.get_ai_agent_by_id(created_agent.id, fields=[\"ask\"])" } ] }, "delete": { "operationId": "delete_ai_agents_id", "summary": "Delete AI agent", "description": "Deletes an AI agent using the provided parameters.", "parameters": [ { "name": "agent_id", "in": "path", "description": "The ID of the agent to delete.", "required": true, "schema": { "type": "string" }, "example": "1234" } ], "responses": { "204": { "description": "A successful response with no content." }, "400": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the AI agent is not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "500": { "description": "An unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "ai_studio", "tags": [ "AI Studio" ], "x-codeSamples": [ { "lang": "curl", "label": "Delete AI agent", "source": "curl -L -X DELETE \"https://api.box.com/2.0/ai_agents/12345\" \\\n -H 'Authorization: Bearer '" }, { "lang": "dotnet", "label": "Delete AI agent", "source": "await client.AiStudio.DeleteAiAgentByIdAsync(agentId: createdAgent.Id);" }, { "lang": "swift", "label": "Delete AI agent", "source": "try await client.aiStudio.deleteAiAgentById(agentId: createdAgent.id)" }, { "lang": "java", "label": "Delete AI agent", "source": "client.getAiStudio().deleteAiAgentById(createdAgent.getId())" }, { "lang": "node", "label": "Delete AI agent", "source": "await client.aiStudio.deleteAiAgentById(createdAgent.id);" }, { "lang": "python", "label": "Delete AI agent", "source": "client.ai_studio.delete_ai_agent_by_id(created_agent.id)" } ] } }, "/metadata_taxonomies": { "post": { "operationId": "post_metadata_taxonomies", "summary": "Create metadata taxonomy", "description": "Creates a new metadata taxonomy that can be used in metadata templates.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "description": "The taxonomy key. If it is not provided in the request body, it will be generated from the `displayName`. The `displayName` would be converted to lower case, and all spaces and non-alphanumeric characters replaced with underscores.", "type": "string", "example": "geography", "maxLength": 256 }, "displayName": { "description": "The display name of the taxonomy.", "type": "string", "example": "Geography", "maxLength": 4096 }, "namespace": { "description": "The namespace of the metadata taxonomy to create.", "type": "string", "example": "enterprise_123456", "maxLength": 4096 } }, "required": [ "displayName", "namespace" ] } } } }, "responses": { "201": { "description": "The schema representing the metadata taxonomy created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomy" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to create the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Create metadata taxonomy", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_taxonomies\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"displayName\": \"Geography\",\n \"key\": \"geography\",\n \"namespace\": \"enterprise_123456\"\n }'" }, { "lang": "dotnet", "label": "Create metadata taxonomy", "source": "await client.MetadataTaxonomies.CreateMetadataTaxonomyAsync(requestBody: new CreateMetadataTaxonomyRequestBody(displayName: displayName, namespaceParam: namespaceParam) { Key = taxonomyKey });" }, { "lang": "swift", "label": "Create metadata taxonomy", "source": "try await client.metadataTaxonomies.createMetadataTaxonomy(requestBody: CreateMetadataTaxonomyRequestBody(displayName: displayName, key: taxonomyKey, namespace: namespace))" }, { "lang": "java", "label": "Create metadata taxonomy", "source": "client.getMetadataTaxonomies().createMetadataTaxonomy(new CreateMetadataTaxonomyRequestBody.Builder(displayName, namespace).key(taxonomyKey).build())" }, { "lang": "node", "label": "Create metadata taxonomy", "source": "await client.metadataTaxonomies.createMetadataTaxonomy({\n displayName: displayName,\n key: taxonomyKey,\n namespace: namespace,\n} satisfies CreateMetadataTaxonomyRequestBody);" }, { "lang": "python", "label": "Create metadata taxonomy", "source": "client.metadata_taxonomies.create_metadata_taxonomy(\n display_name, namespace, key=taxonomy_key\n)" } ] } }, "/metadata_taxonomies/{namespace}": { "get": { "operationId": "get_metadata_taxonomies_id", "summary": "Get metadata taxonomies for namespace", "description": "Used to retrieve all metadata taxonomies in a namespace.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns all of the metadata taxonomies within a namespace and their corresponding schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomies" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata taxonomies for namespace", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata taxonomies for namespace", "source": "await client.MetadataTaxonomies.GetMetadataTaxonomiesAsync(namespaceParam: namespaceParam);" }, { "lang": "swift", "label": "Get metadata taxonomies for namespace", "source": "try await client.metadataTaxonomies.getMetadataTaxonomies(namespace: namespace)" }, { "lang": "java", "label": "Get metadata taxonomies for namespace", "source": "client.getMetadataTaxonomies().getMetadataTaxonomies(namespace)" }, { "lang": "node", "label": "Get metadata taxonomies for namespace", "source": "await client.metadataTaxonomies.getMetadataTaxonomies(namespace);" }, { "lang": "python", "label": "Get metadata taxonomies for namespace", "source": "client.metadata_taxonomies.get_metadata_taxonomies(namespace)" } ] } }, "/metadata_taxonomies/{namespace}/{taxonomy_key}": { "get": { "operationId": "get_metadata_taxonomies_id_id", "summary": "Get metadata taxonomy by taxonomy key", "description": "Used to retrieve a metadata taxonomy by taxonomy key.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" } ], "responses": { "200": { "description": "Returns the metadata taxonomy identified by the taxonomy key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomy" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned when a taxonomy with the given `namespace` and `taxonomy_key` cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata taxonomy by taxonomy key", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata taxonomy by taxonomy key", "source": "await client.MetadataTaxonomies.GetMetadataTaxonomyByKeyAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);" }, { "lang": "swift", "label": "Get metadata taxonomy by taxonomy key", "source": "try await client.metadataTaxonomies.getMetadataTaxonomyByKey(namespace: namespace, taxonomyKey: taxonomyKey)" }, { "lang": "java", "label": "Get metadata taxonomy by taxonomy key", "source": "client.getMetadataTaxonomies().getMetadataTaxonomyByKey(namespace, taxonomyKey)" }, { "lang": "node", "label": "Get metadata taxonomy by taxonomy key", "source": "await client.metadataTaxonomies.getMetadataTaxonomyByKey(\n namespace,\n taxonomyKey,\n);" }, { "lang": "python", "label": "Get metadata taxonomy by taxonomy key", "source": "client.metadata_taxonomies.get_metadata_taxonomy_by_key(namespace, taxonomy_key)" } ] }, "patch": { "operationId": "patch_metadata_taxonomies_id_id", "summary": "Update metadata taxonomy", "description": "Updates an existing metadata taxonomy.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "description": "The display name of the taxonomy.", "type": "string", "example": "Geography", "maxLength": 4096 } }, "required": [ "displayName" ] } } } }, "responses": { "200": { "description": "The schema representing the updated metadata taxonomy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomy" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Update metadata taxonomy", "source": "curl -i -X PATCH \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"displayName\": \"Geography\"\n }'" }, { "lang": "dotnet", "label": "Update metadata taxonomy", "source": "await client.MetadataTaxonomies.UpdateMetadataTaxonomyAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new UpdateMetadataTaxonomyRequestBody(displayName: updatedDisplayName));" }, { "lang": "swift", "label": "Update metadata taxonomy", "source": "try await client.metadataTaxonomies.updateMetadataTaxonomy(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: UpdateMetadataTaxonomyRequestBody(displayName: updatedDisplayName))" }, { "lang": "java", "label": "Update metadata taxonomy", "source": "client.getMetadataTaxonomies().updateMetadataTaxonomy(namespace, taxonomyKey, new UpdateMetadataTaxonomyRequestBody(updatedDisplayName))" }, { "lang": "node", "label": "Update metadata taxonomy", "source": "await client.metadataTaxonomies.updateMetadataTaxonomy(namespace, taxonomyKey, {\n displayName: updatedDisplayName,\n} satisfies UpdateMetadataTaxonomyRequestBody);" }, { "lang": "python", "label": "Update metadata taxonomy", "source": "client.metadata_taxonomies.update_metadata_taxonomy(\n namespace, taxonomy_key, updated_display_name\n)" } ] }, "delete": { "operationId": "delete_metadata_taxonomies_id_id", "summary": "Remove metadata taxonomy", "description": "Delete a metadata taxonomy. This deletion is permanent and cannot be reverted.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" } ], "responses": { "204": { "description": "Returns an empty response when the metadata taxonomy is successfully deleted." }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to delete the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata taxonomy does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Remove metadata taxonomy", "source": "curl -i -X DELETE \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove metadata taxonomy", "source": "await client.MetadataTaxonomies.DeleteMetadataTaxonomyAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);" }, { "lang": "swift", "label": "Remove metadata taxonomy", "source": "try await client.metadataTaxonomies.deleteMetadataTaxonomy(namespace: namespace, taxonomyKey: taxonomyKey)" }, { "lang": "java", "label": "Remove metadata taxonomy", "source": "client.getMetadataTaxonomies().deleteMetadataTaxonomy(namespace, taxonomyKey)" }, { "lang": "node", "label": "Remove metadata taxonomy", "source": "await client.metadataTaxonomies.deleteMetadataTaxonomy(namespace, taxonomyKey);" }, { "lang": "python", "label": "Remove metadata taxonomy", "source": "client.metadata_taxonomies.delete_metadata_taxonomy(namespace, taxonomy_key)" } ] } }, "/metadata_taxonomies/{namespace}/{taxonomy_key}/levels": { "post": { "operationId": "post_metadata_taxonomies_id_id_levels", "summary": "Create metadata taxonomy levels", "description": "Creates new metadata taxonomy levels.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array of metadata taxonomy levels to be created.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataTaxonomyLevel" } } } } }, "responses": { "201": { "description": "Returns an array of all taxonomy levels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyLevels" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Create metadata taxonomy levels", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/levels\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '[\n {\n \"displayName\": \"Continent\",\n \"description\": \"Continent Level\"\n },\n {\n \"displayName\": \"Country\",\n \"description\": \"Country Level\"\n }\n ]'" }, { "lang": "dotnet", "label": "Create metadata taxonomy levels", "source": "await client.MetadataTaxonomies.CreateMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: Array.AsReadOnly(new [] {new MetadataTaxonomyLevel() { DisplayName = \"Continent\", Description = \"Continent Level\" },new MetadataTaxonomyLevel() { DisplayName = \"Country\", Description = \"Country Level\" }}));" }, { "lang": "swift", "label": "Create metadata taxonomy levels", "source": "try await client.metadataTaxonomies.createMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: [MetadataTaxonomyLevel(displayName: \"Continent\", description: \"Continent Level\"), MetadataTaxonomyLevel(displayName: \"Country\", description: \"Country Level\")])" }, { "lang": "java", "label": "Create metadata taxonomy levels", "source": "client.getMetadataTaxonomies().createMetadataTaxonomyLevel(namespace, taxonomyKey, Arrays.asList(new MetadataTaxonomyLevel.Builder().displayName(\"Continent\").description(\"Continent Level\").build(), new MetadataTaxonomyLevel.Builder().displayName(\"Country\").description(\"Country Level\").build()))" }, { "lang": "node", "label": "Create metadata taxonomy levels", "source": "await client.metadataTaxonomies.createMetadataTaxonomyLevel(\n namespace,\n taxonomyKey,\n [\n {\n displayName: 'Continent',\n description: 'Continent Level',\n } satisfies MetadataTaxonomyLevel,\n {\n displayName: 'Country',\n description: 'Country Level',\n } satisfies MetadataTaxonomyLevel,\n ],\n);" }, { "lang": "python", "label": "Create metadata taxonomy levels", "source": "client.metadata_taxonomies.create_metadata_taxonomy_level(\n namespace,\n taxonomy_key,\n [\n MetadataTaxonomyLevel(display_name=\"Continent\", description=\"Continent Level\"),\n MetadataTaxonomyLevel(display_name=\"Country\", description=\"Country Level\"),\n ],\n)" } ] } }, "/metadata_taxonomies/{namespace}/{taxonomy_key}/levels/{level_index}": { "patch": { "operationId": "patch_metadata_taxonomies_id_id_levels_id", "summary": "Update metadata taxonomy level", "description": "Updates an existing metadata taxonomy level.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" }, { "name": "level_index", "in": "path", "description": "The index of the metadata taxonomy level.", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "description": "The display name of the taxonomy level.", "type": "string", "example": "France" }, "description": { "description": "The description of the taxonomy level.", "type": "string", "example": "French Republic" } }, "required": [ "displayName" ] } } } }, "responses": { "200": { "description": "The updated taxonomy level.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyLevel" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Update metadata taxonomy level", "source": "curl -i -X PATCH \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/levels/1\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"displayName\": \"France\",\n \"description\": \"French Republic\"\n }'" }, { "lang": "dotnet", "label": "Update metadata taxonomy level", "source": "await client.MetadataTaxonomies.UpdateMetadataTaxonomyLevelByIdAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, levelIndex: 1L, requestBody: new UpdateMetadataTaxonomyLevelByIdRequestBody(displayName: \"Continent UPDATED\") { Description = \"Continent Level UPDATED\" });" }, { "lang": "swift", "label": "Update metadata taxonomy level", "source": "try await client.metadataTaxonomies.updateMetadataTaxonomyLevelById(namespace: namespace, taxonomyKey: taxonomyKey, levelIndex: Int64(1), requestBody: UpdateMetadataTaxonomyLevelByIdRequestBody(displayName: \"Continent UPDATED\", description: \"Continent Level UPDATED\"))" }, { "lang": "java", "label": "Update metadata taxonomy level", "source": "client.getMetadataTaxonomies().updateMetadataTaxonomyLevelById(namespace, taxonomyKey, 1L, new UpdateMetadataTaxonomyLevelByIdRequestBody.Builder(\"Continent UPDATED\").description(\"Continent Level UPDATED\").build())" }, { "lang": "node", "label": "Update metadata taxonomy level", "source": "await client.metadataTaxonomies.updateMetadataTaxonomyLevelById(\n namespace,\n taxonomyKey,\n 1,\n {\n displayName: 'Continent UPDATED',\n description: 'Continent Level UPDATED',\n } satisfies UpdateMetadataTaxonomyLevelByIdRequestBody,\n);" }, { "lang": "python", "label": "Update metadata taxonomy level", "source": "client.metadata_taxonomies.update_metadata_taxonomy_level_by_id(\n namespace,\n taxonomy_key,\n 1,\n \"Continent UPDATED\",\n description=\"Continent Level UPDATED\",\n)" } ] } }, "/metadata_taxonomies/{namespace}/{taxonomy_key}/levels:append": { "post": { "operationId": "post_metadata_taxonomies_id_id_levels:append", "summary": "Add metadata taxonomy level", "description": "Creates a new metadata taxonomy level and appends it to the existing levels. If there are no levels defined yet, this will create the first level.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "description": "The display name of the taxonomy level.", "type": "string", "example": "France" }, "description": { "description": "The description of the taxonomy level.", "type": "string", "example": "French Republic" } }, "required": [ "displayName" ] } } } }, "responses": { "201": { "description": "Returns an array of all taxonomy levels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyLevels" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Add metadata taxonomy level", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/levels:append\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"displayName\": \"City\",\n \"description\": \"City Level\"\n }'" }, { "lang": "dotnet", "label": "Add metadata taxonomy level", "source": "await client.MetadataTaxonomies.AddMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new AddMetadataTaxonomyLevelRequestBody(displayName: \"Region\") { Description = \"Region Description\" });" }, { "lang": "swift", "label": "Add metadata taxonomy level", "source": "try await client.metadataTaxonomies.addMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: AddMetadataTaxonomyLevelRequestBody(displayName: \"Region\", description: \"Region Description\"))" }, { "lang": "java", "label": "Add metadata taxonomy level", "source": "client.getMetadataTaxonomies().addMetadataTaxonomyLevel(namespace, taxonomyKey, new AddMetadataTaxonomyLevelRequestBody.Builder(\"Region\").description(\"Region Description\").build())" }, { "lang": "node", "label": "Add metadata taxonomy level", "source": "await client.metadataTaxonomies.addMetadataTaxonomyLevel(\n namespace,\n taxonomyKey,\n {\n displayName: 'Region',\n description: 'Region Description',\n } satisfies AddMetadataTaxonomyLevelRequestBody,\n);" }, { "lang": "python", "label": "Add metadata taxonomy level", "source": "client.metadata_taxonomies.add_metadata_taxonomy_level(\n namespace, taxonomy_key, \"Region\", description=\"Region Description\"\n)" } ] } }, "/metadata_taxonomies/{namespace}/{taxonomy_key}/levels:trim": { "post": { "operationId": "post_metadata_taxonomies_id_id_levels:trim", "summary": "Delete metadata taxonomy level", "description": "Deletes the last level of the metadata taxonomy.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" } ], "responses": { "200": { "description": "Returns an array of all taxonomy levels.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyLevels" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Delete metadata taxonomy level", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/levels:trim\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Delete metadata taxonomy level", "source": "await client.MetadataTaxonomies.DeleteMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);" }, { "lang": "swift", "label": "Delete metadata taxonomy level", "source": "try await client.metadataTaxonomies.deleteMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey)" }, { "lang": "java", "label": "Delete metadata taxonomy level", "source": "client.getMetadataTaxonomies().deleteMetadataTaxonomyLevel(namespace, taxonomyKey)" }, { "lang": "node", "label": "Delete metadata taxonomy level", "source": "await client.metadataTaxonomies.deleteMetadataTaxonomyLevel(\n namespace,\n taxonomyKey,\n);" }, { "lang": "python", "label": "Delete metadata taxonomy level", "source": "client.metadata_taxonomies.delete_metadata_taxonomy_level(namespace, taxonomy_key)" } ] } }, "/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes": { "get": { "operationId": "get_metadata_taxonomies_id_id_nodes", "summary": "List metadata taxonomy nodes", "description": "Used to retrieve metadata taxonomy nodes based on the parameters specified. Results are sorted in lexicographic order unless a `query` parameter is passed. With a `query` parameter specified, results are sorted in order of relevance.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" }, { "name": "level", "in": "query", "description": "Filters results by taxonomy level. Multiple values can be provided. Results include nodes that match any of the specified values.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "example": [ 1 ] }, { "name": "parent", "in": "query", "description": "Node identifier of a direct parent node. Multiple values can be provided. Results include nodes that match any of the specified values.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "c73a9bf3-f377-4210-9159-3df06a481905" ] }, { "name": "ancestor", "in": "query", "description": "Node identifier of any ancestor node. Multiple values can be provided. Results include nodes that match any of the specified values.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "c73a9bf3-f377-4210-9159-3df06a481905", "bf8b8213-be1f-4011-bd45-533c0713fa0a" ] }, { "name": "query", "in": "query", "description": "Query text to search for the taxonomy nodes.", "required": false, "schema": { "type": "string" }, "example": "France" }, { "name": "include-total-result-count", "in": "query", "description": "When set to `true` this provides the total number of nodes that matched the query. The response will compute counts of up to 10,000 elements. Defaults to `false`.", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of the taxonomy nodes that match the specified parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyNodes" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-codeSamples": [ { "lang": "curl", "label": "List metadata taxonomy nodes", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/nodes\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List metadata taxonomy nodes", "source": "await client.MetadataTaxonomies.GetMetadataTaxonomyNodesAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);" }, { "lang": "swift", "label": "List metadata taxonomy nodes", "source": "try await client.metadataTaxonomies.getMetadataTaxonomyNodes(namespace: namespace, taxonomyKey: taxonomyKey)" }, { "lang": "java", "label": "List metadata taxonomy nodes", "source": "client.getMetadataTaxonomies().getMetadataTaxonomyNodes(namespace, taxonomyKey)" }, { "lang": "node", "label": "List metadata taxonomy nodes", "source": "await client.metadataTaxonomies.getMetadataTaxonomyNodes(\n namespace,\n taxonomyKey,\n);" }, { "lang": "python", "label": "List metadata taxonomy nodes", "source": "client.metadata_taxonomies.get_metadata_taxonomy_nodes(namespace, taxonomy_key)" } ] }, "post": { "operationId": "post_metadata_taxonomies_id_id_nodes", "summary": "Create metadata taxonomy node", "description": "Creates a new metadata taxonomy node.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "description": "The display name of the taxonomy node.", "type": "string", "example": "France" }, "level": { "description": "The level of the taxonomy node.", "type": "integer", "example": 1 }, "parentId": { "description": "The identifier of the parent taxonomy node. Omit this field for root-level nodes.", "type": "string", "example": "99df4513-7102-4896-8228-94635ee9d330" } }, "required": [ "displayName", "level" ] } } } }, "responses": { "201": { "description": "The schema representing the taxonomy node created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyNode" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Create metadata taxonomy node", "source": "curl -i -X POST \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/nodes\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"displayName\": \"Europe\",\n \"level\": 1\n }'" }, { "lang": "dotnet", "label": "Create metadata taxonomy node", "source": "await client.MetadataTaxonomies.CreateMetadataTaxonomyNodeAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new CreateMetadataTaxonomyNodeRequestBody(displayName: \"Europe\", level: 1));" }, { "lang": "swift", "label": "Create metadata taxonomy node", "source": "try await client.metadataTaxonomies.createMetadataTaxonomyNode(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: CreateMetadataTaxonomyNodeRequestBody(displayName: \"Europe\", level: 1))" }, { "lang": "java", "label": "Create metadata taxonomy node", "source": "client.getMetadataTaxonomies().createMetadataTaxonomyNode(namespace, taxonomyKey, new CreateMetadataTaxonomyNodeRequestBody(\"Europe\", 1))" }, { "lang": "node", "label": "Create metadata taxonomy node", "source": "await client.metadataTaxonomies.createMetadataTaxonomyNode(\n namespace,\n taxonomyKey,\n {\n displayName: 'Europe',\n level: 1,\n } satisfies CreateMetadataTaxonomyNodeRequestBody,\n);" }, { "lang": "python", "label": "Create metadata taxonomy node", "source": "client.metadata_taxonomies.create_metadata_taxonomy_node(\n namespace, taxonomy_key, \"Europe\", 1\n)" } ] } }, "/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}": { "get": { "operationId": "get_metadata_taxonomies_id_id_nodes_id", "summary": "Get metadata taxonomy node by ID", "description": "Retrieves a metadata taxonomy node by its identifier.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" }, { "name": "node_id", "in": "path", "description": "The identifier of the metadata taxonomy node.", "required": true, "schema": { "type": "string" }, "example": "14d3d433-c77f-49c5-b146-9dea370f6e32" } ], "responses": { "200": { "description": "Returns the metadata taxonomy node that matches the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyNode" } } } }, "400": { "description": "Returned if any of the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the taxonomy node with the given `node_id` cannot be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-codeSamples": [ { "lang": "curl", "label": "Get metadata taxonomy node by ID", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/nodes/14d3d433-c77f-49c5-b146-9dea370f6e32\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Get metadata taxonomy node by ID", "source": "await client.MetadataTaxonomies.GetMetadataTaxonomyNodeByIdAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, nodeId: countryNode.Id);" }, { "lang": "swift", "label": "Get metadata taxonomy node by ID", "source": "try await client.metadataTaxonomies.getMetadataTaxonomyNodeById(namespace: namespace, taxonomyKey: taxonomyKey, nodeId: countryNode.id)" }, { "lang": "java", "label": "Get metadata taxonomy node by ID", "source": "client.getMetadataTaxonomies().getMetadataTaxonomyNodeById(namespace, taxonomyKey, countryNode.getId())" }, { "lang": "node", "label": "Get metadata taxonomy node by ID", "source": "await client.metadataTaxonomies.getMetadataTaxonomyNodeById(\n namespace,\n taxonomyKey,\n countryNode.id,\n);" }, { "lang": "python", "label": "Get metadata taxonomy node by ID", "source": "client.metadata_taxonomies.get_metadata_taxonomy_node_by_id(\n namespace, taxonomy_key, country_node.id\n)" } ] }, "patch": { "operationId": "patch_metadata_taxonomies_id_id_nodes_id", "summary": "Update metadata taxonomy node", "description": "Updates an existing metadata taxonomy node.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" }, { "name": "node_id", "in": "path", "description": "The identifier of the metadata taxonomy node.", "required": true, "schema": { "type": "string" }, "example": "14d3d433-c77f-49c5-b146-9dea370f6e32" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "description": "The display name of the taxonomy node.", "type": "string", "example": "France" } } } } } }, "responses": { "200": { "description": "The schema representing the updated taxonomy node.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyNode" } } } }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Update metadata taxonomy node", "source": "curl -i -X PATCH \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/nodes/14d3d433-c77f-49c5-b146-9dea370f6e32\" \\\n -H \"authorization: Bearer \" \\\n -H \"content-type: application/json\" \\\n -d '{\n \"displayName\": \"France\"\n }'" }, { "lang": "dotnet", "label": "Update metadata taxonomy node", "source": "await client.MetadataTaxonomies.UpdateMetadataTaxonomyNodeAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, nodeId: countryNode.Id, requestBody: new UpdateMetadataTaxonomyNodeRequestBody() { DisplayName = \"Poland UPDATED\" });" }, { "lang": "swift", "label": "Update metadata taxonomy node", "source": "try await client.metadataTaxonomies.updateMetadataTaxonomyNode(namespace: namespace, taxonomyKey: taxonomyKey, nodeId: countryNode.id, requestBody: UpdateMetadataTaxonomyNodeRequestBody(displayName: \"Poland UPDATED\"))" }, { "lang": "java", "label": "Update metadata taxonomy node", "source": "client.getMetadataTaxonomies().updateMetadataTaxonomyNode(namespace, taxonomyKey, countryNode.getId(), new UpdateMetadataTaxonomyNodeRequestBody.Builder().displayName(\"Poland UPDATED\").build())" }, { "lang": "node", "label": "Update metadata taxonomy node", "source": "await client.metadataTaxonomies.updateMetadataTaxonomyNode(\n namespace,\n taxonomyKey,\n countryNode.id,\n {\n requestBody: {\n displayName: 'Poland UPDATED',\n } satisfies UpdateMetadataTaxonomyNodeRequestBody,\n } satisfies UpdateMetadataTaxonomyNodeOptionalsInput,\n);" }, { "lang": "python", "label": "Update metadata taxonomy node", "source": "client.metadata_taxonomies.update_metadata_taxonomy_node(\n namespace, taxonomy_key, country_node.id, display_name=\"Poland UPDATED\"\n)" } ] }, "delete": { "operationId": "delete_metadata_taxonomies_id_id_nodes_id", "summary": "Remove metadata taxonomy node", "description": "Delete a metadata taxonomy node. This deletion is permanent and cannot be reverted. Only metadata taxonomy nodes without any children can be deleted.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "taxonomy_key", "in": "path", "description": "The key of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "geography" }, { "name": "node_id", "in": "path", "description": "The identifier of the metadata taxonomy node.", "required": true, "schema": { "type": "string" }, "example": "14d3d433-c77f-49c5-b146-9dea370f6e32" } ], "responses": { "204": { "description": "Returns an empty response when the metadata taxonomy node is successfully deleted." }, "400": { "description": "Returned if the request parameters or body is not valid.\n\n- `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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "403": { "description": "Returned when the user does not have the permission to delete the metadata taxonomy node. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "404": { "description": "Returned if the metadata taxonomy node does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-box-requires-admin": true, "x-codeSamples": [ { "lang": "curl", "label": "Remove metadata taxonomy node", "source": "curl -i -X DELETE \"https://api.box.com/2.0/metadata_taxonomies/enterprise_123456/geography/nodes/14d3d433-c77f-49c5-b146-9dea370f6e32\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "Remove metadata taxonomy node", "source": "await client.MetadataTaxonomies.DeleteMetadataTaxonomyNodeAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, nodeId: countryNode.Id);" }, { "lang": "swift", "label": "Remove metadata taxonomy node", "source": "try await client.metadataTaxonomies.deleteMetadataTaxonomyNode(namespace: namespace, taxonomyKey: taxonomyKey, nodeId: countryNode.id)" }, { "lang": "java", "label": "Remove metadata taxonomy node", "source": "client.getMetadataTaxonomies().deleteMetadataTaxonomyNode(namespace, taxonomyKey, countryNode.getId())" }, { "lang": "node", "label": "Remove metadata taxonomy node", "source": "await client.metadataTaxonomies.deleteMetadataTaxonomyNode(\n namespace,\n taxonomyKey,\n countryNode.id,\n);" }, { "lang": "python", "label": "Remove metadata taxonomy node", "source": "client.metadata_taxonomies.delete_metadata_taxonomy_node(\n namespace, taxonomy_key, country_node.id\n)" } ] } }, "/metadata_templates/{namespace}/{template_key}/fields/{field_key}/options": { "get": { "operationId": "get_metadata_templates_id_id_fields_id_options", "summary": "List metadata template's options for taxonomy field", "description": "Used to retrieve metadata taxonomy nodes which are available for the taxonomy field based on its configuration and the parameters specified. Results are sorted in lexicographic order unless a `query` parameter is passed. With a `query` parameter specified, results are sorted in order of relevance.", "parameters": [ { "name": "namespace", "in": "path", "description": "The namespace of the metadata taxonomy.", "required": true, "schema": { "type": "string" }, "example": "enterprise_123456" }, { "name": "template_key", "in": "path", "description": "The name of the metadata template.", "required": true, "schema": { "type": "string" }, "example": "properties" }, { "name": "field_key", "in": "path", "description": "The key of the metadata taxonomy field in the template.", "required": true, "schema": { "type": "string" }, "example": "geography" }, { "name": "level", "in": "query", "description": "Filters results by taxonomy level. Multiple values can be provided. Results include nodes that match any of the specified values.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "example": [ 1 ] }, { "name": "parent", "in": "query", "description": "Node identifier of a direct parent node. Multiple values can be provided. Results include nodes that match any of the specified values.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "c73a9bf3-f377-4210-9159-3df06a481905" ] }, { "name": "ancestor", "in": "query", "description": "Node identifier of any ancestor node. Multiple values can be provided. Results include nodes that match any of the specified values.", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "c73a9bf3-f377-4210-9159-3df06a481905", "bf8b8213-be1f-4011-bd45-533c0713fa0a" ] }, { "name": "query", "in": "query", "description": "Query text to search for the taxonomy nodes.", "required": false, "schema": { "type": "string" }, "example": "France" }, { "name": "include-total-result-count", "in": "query", "description": "When set to `true` this provides the total number of nodes that matched the query. The response will compute counts of up to 10,000 elements. Defaults to `false`.", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "only-selectable-options", "in": "query", "description": "When set to `true`, this only returns valid selectable options for this template taxonomy field. Otherwise, it returns all taxonomy nodes, whether or not they are selectable. Defaults to `true`.", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "marker", "in": "query", "description": "Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "required": false, "schema": { "type": "string" }, "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii" }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page.", "required": false, "schema": { "type": "integer", "format": "int64", "maximum": 1000 }, "example": 1000 } ], "responses": { "200": { "description": "Returns a list of the taxonomy nodes that match the specified parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataTaxonomyNodes" } } } }, "400": { "description": "Returned when the request parameters are not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } }, "default": { "description": "An unexpected client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientError" } } } } }, "x-box-tag": "metadata_taxonomies", "tags": [ "Metadata taxonomies" ], "x-codeSamples": [ { "lang": "curl", "label": "List metadata template's options for taxonomy field", "source": "curl -i -X GET \"https://api.box.com/2.0/metadata_templates/enterprise_123456/properties/fields/geography/options\" \\\n -H \"authorization: Bearer \"" }, { "lang": "dotnet", "label": "List metadata template's options for taxonomy field", "source": "await client.MetadataTaxonomies.GetMetadataTemplateFieldOptionsAsync(namespaceParam: namespaceParam, templateKey: metadataTemplateKey, fieldKey: fieldKey);" }, { "lang": "swift", "label": "List metadata template's options for taxonomy field", "source": "try await client.metadataTaxonomies.getMetadataTemplateFieldOptions(namespace: namespace, templateKey: metadataTemplateKey, fieldKey: fieldKey)" }, { "lang": "java", "label": "List metadata template's options for taxonomy field", "source": "client.getMetadataTaxonomies().getMetadataTemplateFieldOptions(namespace, metadataTemplateKey, fieldKey)" }, { "lang": "node", "label": "List metadata template's options for taxonomy field", "source": "await client.metadataTaxonomies.getMetadataTemplateFieldOptions(\n namespace,\n metadataTemplateKey,\n fieldKey,\n);" }, { "lang": "python", "label": "List metadata template's options for taxonomy field", "source": "client.metadata_taxonomies.get_metadata_template_field_options(\n namespace, metadata_template_key, field_key\n)" } ] } } }, "components": { "schemas": { "AccessToken": { "description": "A token that can be used to make authenticated API calls.", "type": "object", "properties": { "access_token": { "description": "The requested access token.", "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "expires_in": { "description": "The time in seconds by which this token will expire.", "type": "integer", "format": "int64", "example": 3600 }, "token_type": { "description": "The type of access token returned.", "type": "string", "example": "bearer", "enum": [ "bearer" ] }, "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.", "type": "array", "items": { "$ref": "#/components/schemas/ResourceScope" } }, "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.", "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "issued_token_type": { "description": "The type of downscoped access token returned. This is only returned if an access token has been downscoped.", "type": "string", "format": "urn", "example": "urn:ietf:params:oauth:token-type:access_token", "enum": [ "urn:ietf:params:oauth:token-type:access_token" ] } }, "title": "Access token", "x-box-resource-id": "access_token", "x-box-tag": "authorization" }, "AiAgent": { "description": "Can be one of the following objects:\n\n- AI agent for questions\n- AI agent for text generation\n- AI agent for freeform metadata extraction\n- AI agent for structured metadata extraction.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiAgentAsk" }, { "$ref": "#/components/schemas/AiAgentTextGen" }, { "$ref": "#/components/schemas/AiAgentExtract" }, { "$ref": "#/components/schemas/AiAgentExtractStructured" } ], "title": "AI agent" }, "AiAgentAllowedEntity": { "description": "The entity with type and ID.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/User--Base" }, { "$ref": "#/components/schemas/Group--Base" } ], "title": "The entity with type and ID", "x-box-resource-id": "ai_agent_allowed_entity" }, "AiAgentAsk": { "description": "The AI agent used to handle queries.", "type": "object", "properties": { "type": { "description": "The type of AI agent used to handle queries.", "type": "string", "example": "ai_agent_ask", "enum": [ "ai_agent_ask" ], "nullable": false }, "long_text": { "$ref": "#/components/schemas/AiAgentLongTextTool" }, "basic_text": { "$ref": "#/components/schemas/AiAgentBasicTextTool" }, "spreadsheet": { "$ref": "#/components/schemas/AiAgentSpreadsheetTool" }, "long_text_multi": { "$ref": "#/components/schemas/AiAgentLongTextTool" }, "basic_text_multi": { "$ref": "#/components/schemas/AiAgentBasicTextTool" }, "basic_image": { "$ref": "#/components/schemas/AiAgentBasicTextTool" }, "basic_image_multi": { "$ref": "#/components/schemas/AiAgentBasicTextTool" } }, "required": [ "type" ], "title": "AI agent for question requests", "x-box-resource-id": "ai_agent_ask", "x-box-tag": "ai" }, "AiAgentBasicGenTool": { "description": "AI agent basic tool used to generate text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentLongTextToolTextGen" }, { "properties": { "content_template": { "description": "How the content should be included in a request to the LLM. Input for `{content}` is optional, depending on the use.", "type": "string", "example": "---{content}---" } } } ], "title": "AI agent basic text generation tool", "x-box-tag": "ai" }, "AiAgentBasicTextTool": { "description": "AI agent processor used to handle basic text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentBasicTextToolBase" }, { "properties": { "system_message": { "description": "System messages try to help the LLM \"understand\" its role and what it is supposed to do.", "type": "string", "example": "You are a helpful travel assistant specialized in budget travel" }, "prompt_template": { "description": "The prompt template contains contextual information of the request and the user prompt. When passing `prompt_template` parameters, you **must include** inputs for `{user_question}` and `{content}`. `{current_date}` is optional, depending on the use.", "type": "string", "example": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.", "maxLength": 10000, "pattern": "(\\{user_question\\}[\\s\\S]*?\\{content\\}|\\{content\\}[\\s\\S]*?\\{user_question\\})" } } } ], "title": "AI agent basic text tool", "x-box-tag": "ai" }, "AiAgentBasicTextToolBase": { "description": "AI agent processor used to handle basic text.", "type": "object", "properties": { "model": { "description": "The model used for the AI agent for basic text. For specific model values, see the [available models list](/guides/box-ai/ai-models).", "type": "string", "example": "azure__openai__gpt_4o_mini" }, "num_tokens_for_completion": { "description": "The number of tokens for completion.", "type": "integer", "example": 8400, "minimum": 1 }, "llm_endpoint_params": { "$ref": "#/components/schemas/AiLlmEndpointParams" } }, "title": "AI agent basic text tool", "x-box-tag": "ai" }, "AiAgentBasicTextToolTextGen": { "description": "AI agent processor used to handle basic text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentBasicTextToolBase" }, { "properties": { "system_message": { "description": "System messages aim at helping the LLM understand its role and what it is supposed to do. The input for `{current_date}` is optional, depending on the use.", "type": "string", "example": "You are a helpful travel assistant specialized in budget travel" }, "prompt_template": { "description": "The prompt template contains contextual information of the request and the user prompt.\n\nWhen using the `prompt_template` parameter, you **must include** input for `{user_question}`. Inputs for `{current_date}` and `{content}` are optional, depending on the use.", "type": "string", "example": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`", "maxLength": 10000, "pattern": "\\{user_question\\}" } } } ], "title": "AI agent basic text tool", "x-box-tag": "ai" }, "AiAgentExtract": { "description": "The AI agent to be used for extraction.", "type": "object", "properties": { "type": { "description": "The type of AI agent to be used for extraction.", "type": "string", "example": "ai_agent_extract", "enum": [ "ai_agent_extract" ], "nullable": false }, "long_text": { "$ref": "#/components/schemas/AiAgentLongTextTool" }, "basic_text": { "$ref": "#/components/schemas/AiAgentBasicTextTool" }, "basic_image": { "$ref": "#/components/schemas/AiAgentBasicTextTool" } }, "required": [ "type" ], "title": "AI agent for extract requests", "x-box-resource-id": "ai_agent_extract", "x-box-tag": "ai" }, "AiAgentExtractStructured": { "description": "The AI agent to be used for structured extraction.", "type": "object", "properties": { "type": { "description": "The type of AI agent to be used for extraction.", "type": "string", "example": "ai_agent_extract_structured", "enum": [ "ai_agent_extract_structured" ], "nullable": false }, "long_text": { "$ref": "#/components/schemas/AiAgentLongTextTool" }, "basic_text": { "$ref": "#/components/schemas/AiAgentBasicTextTool" }, "basic_image": { "$ref": "#/components/schemas/AiAgentBasicTextTool" } }, "required": [ "type" ], "title": "AI agent for structured extract request", "x-box-resource-id": "ai_agent_extract_structured", "x-box-tag": "ai" }, "AiAgentInfo": { "description": "The information on the models and processors used in the request.", "type": "object", "properties": { "models": { "description": "The models used for the request.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "The name of the model used for the request.", "type": "string", "example": "azure__openai__text_embedding_ada_002" }, "provider": { "description": "The provider that owns the model used for the request.", "type": "string", "example": "azure" }, "supported_purpose": { "description": "The supported purpose utilized by the model used for the request.", "type": "string", "example": "embedding" } } } }, "processor": { "description": "The processor used for the request.", "type": "string", "example": "basic_text" } }, "title": "The information on the models and processors used in the request." }, "AiAgentLongTextTool": { "description": "AI agent processor used to to handle longer text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentBasicTextTool" }, { "properties": { "embeddings": { "type": "object", "properties": { "model": { "description": "The model used for the AI agent for calculating embeddings.", "type": "string", "example": "azure__openai__text_embedding_ada_002" }, "strategy": { "type": "object", "properties": { "id": { "description": "The strategy used for the AI agent for calculating embeddings.", "type": "string", "example": "basic" }, "num_tokens_per_chunk": { "description": "The number of tokens per chunk.", "type": "integer", "example": 64, "maximum": 512, "minimum": 1 } } } } } } } ], "title": "AI agent long text tool", "x-box-tag": "ai" }, "AiAgentLongTextToolTextGen": { "description": "AI agent processor used to to handle longer text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentBasicTextToolTextGen" }, { "properties": { "embeddings": { "type": "object", "properties": { "model": { "description": "The model used for the AI agent for calculating embeddings.", "type": "string", "example": "azure__openai__text_embedding_ada_002" }, "strategy": { "type": "object", "properties": { "id": { "description": "The strategy used for the AI agent for calculating embeddings.", "type": "string", "example": "basic" }, "num_tokens_per_chunk": { "description": "The number of tokens per chunk.", "type": "integer", "example": 64, "maximum": 512, "minimum": 1 } } } } } } } ], "title": "AI agent long text tool", "x-box-tag": "ai" }, "AiAgentReference": { "description": "The AI agent used to handle queries.", "type": "object", "properties": { "type": { "description": "The type of AI agent used to handle queries.", "type": "string", "example": "ai_agent_id", "enum": [ "ai_agent_id" ], "nullable": false }, "id": { "description": "The ID of an Agent. This can be a numeric ID for custom agents (for example, `14031`) or a unique identifier for pre-built agents (for example, `enhanced_extract_agent` for the [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent)).", "type": "string", "example": "14031", "nullable": false } }, "required": [ "type", "id" ], "title": "AI agent reference", "x-box-resource-id": "ai_agent_reference", "x-box-tag": "ai" }, "AiAgentSpreadsheetTool": { "description": "The AI agent tool used to handle spreadsheets and tabular data.", "type": "object", "properties": { "model": { "description": "The model used for the AI agent for spreadsheets. For specific model values, see the [available models list](/guides/box-ai/ai-models).", "type": "string", "example": "azure__openai__gpt_4o_mini" }, "num_tokens_for_completion": { "description": "The number of tokens for completion.", "type": "integer", "example": 8400, "minimum": 1 }, "llm_endpoint_params": { "$ref": "#/components/schemas/AiLlmEndpointParams" } }, "title": "AI agent spreadsheet tool", "x-box-tag": "ai" }, "AiAgentTextGen": { "description": "The AI agent used for generating text.", "type": "object", "properties": { "type": { "description": "The type of AI agent used for generating text.", "type": "string", "example": "ai_agent_text_gen", "enum": [ "ai_agent_text_gen" ], "nullable": false }, "basic_gen": { "$ref": "#/components/schemas/AiAgentBasicGenTool" } }, "required": [ "type" ], "title": "AI agent for text generation requests", "x-box-resource-id": "ai_agent_text_gen", "x-box-tag": "ai" }, "AiAsk": { "description": "AI ask request object.", "type": "object", "properties": { "mode": { "description": "Box AI handles text documents with text representations up to 2MB in size, or a maximum of 25 files, whichever comes first. If the text file size exceeds 2MB, the first 2MB of text representation will be processed. Box AI handles image documents with a resolution of 1024 x 1024 pixels, with a maximum of 5 images or 5 pages for multi-page images. If the number of image or image pages exceeds 5, the first 5 images or pages will be processed. If you set mode parameter to `single_item_qa`, the items array can have one element only. Currently Box AI does not support multi-modal requests. If both images and text are sent Box AI will only process the text.", "type": "string", "example": "multiple_item_qa", "enum": [ "multiple_item_qa", "single_item_qa" ], "nullable": false }, "prompt": { "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", "type": "string", "example": "What is the value provided by public APIs based on this document?" }, "items": { "description": "The items to be processed by the LLM, often files. To search across and ask questions about the contents of a Box Hub, pass a single item with `type` set to `hubs`. See the item `type` property for details.", "type": "array", "items": { "$ref": "#/components/schemas/AiItemAsk" }, "maxItems": 25, "minItems": 1, "uniqueItems": true }, "dialogue_history": { "description": "The history of prompts and answers previously passed to the LLM. This provides additional context to the LLM in generating the response.", "type": "array", "items": { "$ref": "#/components/schemas/AiDialogueHistory" } }, "include_citations": { "description": "A flag to indicate whether citations should be returned.", "type": "boolean", "example": true }, "ai_agent": { "allOf": [ { "$ref": "#/components/schemas/AiAskAgent" }, { "description": "The AI agent to be used to handle the request." } ] } }, "required": [ "prompt", "items", "mode" ], "title": "AI ask request", "x-box-tag": "ai" }, "AiAskAgent": { "description": "The AI agent to be used to handle the AI ask request.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiAgentReference" }, { "$ref": "#/components/schemas/AiAgentAsk" } ], "title": "AI ask request agent" }, "AiCitation": { "description": "The citation of the LLM's answer reference.", "type": "object", "properties": { "content": { "description": "The specific content from where the answer was referenced.", "example": "Public APIs are key drivers of innovation and growth.", "type": "string" }, "id": { "description": "The id of the item.", "type": "string", "example": "123" }, "type": { "description": "The type of the item.", "type": "string", "example": "file", "enum": [ "file" ] }, "name": { "description": "The name of the item.", "type": "string", "example": "The importance of public APIs.pdf" } }, "title": "The citation of the LLM's answer reference" }, "AiDialogueHistory": { "description": "A context object that can hold prior prompts and answers.", "type": "object", "properties": { "prompt": { "description": "The prompt previously provided by the client and answered by the LLM.", "type": "string", "example": "Make my email about public APIs sound more professional." }, "answer": { "description": "The answer previously provided by the LLM.", "type": "string", "example": "Here is the first draft of your professional email about public APIs." }, "created_at": { "description": "The ISO date formatted timestamp of when the previous answer to the prompt was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "title": "Dialogue history" }, "AiExtract": { "description": "AI metadata freeform extraction request object.", "type": "object", "properties": { "prompt": { "description": "The prompt provided to a Large Language Model (LLM) in the request. The prompt can be up to 10000 characters long and it can be an XML or a JSON schema.", "type": "string", "example": "\\\"fields\\\":[{\\\"type\\\":\\\"string\\\",\\\"key\\\":\\\"name\\\",\\\"displayName\\\":\\\"Name\\\",\\\"description\\\":\\\"The customer name\\\",\\\"prompt\\\":\\\"Name is always the first word in the document\\\"},{\\\"type\\\":\\\"date\\\",\\\"key\\\":\\\"last_contacted_at\\\",\\\"displayName\\\":\\\"Last Contacted At\\\",\\\"description\\\":\\\"When this customer was last contacted at\\\"}]" }, "items": { "description": "The items that LLM will process. Currently, you can use files only.", "type": "array", "items": { "$ref": "#/components/schemas/AiItem--Base" }, "maxItems": 25, "minItems": 1, "uniqueItems": true }, "ai_agent": { "allOf": [ { "$ref": "#/components/schemas/AiExtractAgent" }, { "description": "The AI agent to be used for the extraction." } ] } }, "required": [ "prompt", "items" ], "title": "AI metadata freeform extraction request", "x-box-tag": "ai" }, "AiExtractAgent": { "description": "The AI agent to be used to handle the AI metadata freeform extraction request.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiAgentReference" }, { "$ref": "#/components/schemas/AiAgentExtract" } ], "title": "AI metadata freeform extraction request agent" }, "AiExtractFieldOption": { "description": "An option for an AI extract field.", "type": "object", "properties": { "key": { "description": "A unique identifier for the option.", "type": "string", "example": "First Name" } }, "required": [ "key" ], "title": "AI Extract Field Option" }, "AiExtractResponse": { "description": "AI extract response. The content of this response may vary depending on the requested configuration.", "type": "object", "additionalProperties": {}, "title": "AI extract response", "x-box-resource-id": "ai_extract_response", "x-box-tag": "ai" }, "AiExtractStructured": { "description": "AI Extract Structured Request object.", "type": "object", "properties": { "items": { "description": "The items to be processed by the LLM. Currently you can use files only.", "type": "array", "items": { "$ref": "#/components/schemas/AiItem--Base" }, "maxItems": 25, "minItems": 1, "uniqueItems": true }, "metadata_template": { "description": "The metadata template containing the fields to extract. For your request to work, you must provide either `metadata_template` or `fields`, but not both.", "type": "object", "properties": { "template_key": { "description": "The name of the metadata template.", "type": "string", "example": "invoiceTemplate" }, "type": { "description": "Value is always `metadata_template`.", "type": "string", "example": "metadata_template", "enum": [ "metadata_template" ] }, "scope": { "description": "The scope of the metadata template that can either be global or enterprise.\n\n- The **global** scope is used for templates that are available to any Box enterprise.\n- The **enterprise** scope represents templates created within a specific enterprise, containing the ID of that enterprise.", "type": "string", "example": "enterprise_12345", "maxLength": 40 } } }, "fields": { "description": "The fields to be extracted from the provided items. For your request to work, you must provide either `metadata_template` or `fields`, but not both.", "type": "array", "items": { "type": "object", "description": "The fields to be extracted from the provided items.", "required": [ "key" ], "properties": { "key": { "description": "A unique identifier for the field.", "type": "string", "example": "name" }, "description": { "description": "A description of the field.", "type": "string", "example": "The name of the person." }, "displayName": { "description": "The display name of the field.", "type": "string", "example": "Name" }, "prompt": { "description": "The context about the key that may include how to find and format it.", "type": "string", "example": "Name is the first and last name from the email address" }, "type": { "description": "The type of the field. It can include but is not limited to `string`, `float`, `date`, `enum`, `multiSelect`,`taxonomy`, `struct`, and `table`.", "type": "string", "example": "enum" }, "options": { "description": "A list of options for this field. This is most often used in combination with the `enum` and `multiSelect` field types.", "type": "array", "items": { "type": "object", "required": [ "key" ], "properties": { "key": { "description": "A unique identifier for the option.", "type": "string", "example": "First Name" } } }, "example": [ { "key": "First Name" }, { "key": "Last Name" } ] }, "fields": { "description": "The nested fields for this field. Used with `struct` and `table` field types to define the nested structure.", "type": "array", "items": { "$ref": "#/components/schemas/AiExtractSubField" } }, "taxonomy_key": { "description": "The identifier for a taxonomy, which corresponds to the `key` of the taxonomy source. Required if using `taxonomy` type field.", "type": "string", "example": "certification_taxonomy" }, "namespace": { "description": "The namespace of the taxonomy source. Required if using `taxonomy` type field from an existing taxonomy.", "type": "string", "example": "enterprise_123" }, "options_rules": { "example": { "multiSelect": false, "selectableLevels": [ 1, 2 ] }, "allOf": [ { "$ref": "#/components/schemas/AiOptionsRules" } ] } } }, "minItems": 1, "uniqueItems": true }, "ai_agent": { "allOf": [ { "$ref": "#/components/schemas/AiExtractStructuredAgent" }, { "description": "The AI agent to be used for the structured extraction. Defaults to the Standard Agent if not specified. If you want to use Enhanced Extract Agent, see [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent) for details." } ] }, "include_confidence_score": { "description": "A flag to indicate whether confidence scores for every extracted field should be returned.", "type": "boolean", "example": true }, "include_reference": { "description": "A flag to indicate whether references for every extracted field should be returned.", "type": "boolean", "example": true }, "taxonomy_sources": { "description": "The taxonomy sources to be used for the structured extraction. They can either be an existing file or a taxonomy. For your request to work, `fields` must also be provided. `taxonomy_sources` is not supported with `metadata_template`.", "type": "array", "items": { "$ref": "#/components/schemas/AiTaxonomySource" }, "example": [ { "type": "taxonomy", "taxonomy_key": "certification_taxonomy", "namespace": "enterprise_123" }, { "type": "file", "taxonomy_key": "industry_taxonomy", "id": "1234567890" } ], "uniqueItems": true } }, "required": [ "items" ], "title": "AI Extract Structured Request", "x-box-tag": "ai" }, "AiExtractStructuredAgent": { "description": "The AI agent to be used to handle the AI extract structured request.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiAgentReference" }, { "$ref": "#/components/schemas/AiAgentExtractStructured" } ], "title": "AI Extract Structured Request agent" }, "AiExtractStructuredResponse": { "description": "AI extract structured response.", "type": "object", "properties": { "answer": { "$ref": "#/components/schemas/AiExtractResponse" }, "created_at": { "description": "The ISO date formatted timestamp of when the answer to the prompt was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "completion_reason": { "description": "The reason the response finishes.", "type": "string", "example": "done" }, "confidence_score": { "description": "The confidence score levels and numeric values for each extracted field as a JSON dictionary. This can be empty if no field could be extracted.", "type": "object", "additionalProperties": {} }, "reference": { "description": "The reference for each extracted field as a JSON dictionary. This can be empty if no field could be extracted.", "type": "object", "additionalProperties": {} }, "ai_agent_info": { "$ref": "#/components/schemas/AiAgentInfo" } }, "required": [ "answer", "created_at" ], "title": "AI extract structured response", "x-box-resource-id": "ai_extract_structured_response", "x-box-tag": "ai" }, "AiExtractSubField": { "description": "A nested field definition for structured and table field types used in AI extraction.", "type": "object", "properties": { "key": { "description": "A unique identifier for the nested field.", "type": "string", "example": "street_name" }, "description": { "description": "A description of the nested field.", "type": "string", "example": "The street name of the address." }, "displayName": { "description": "The display name of the nested field.", "type": "string", "example": "Street Name" }, "prompt": { "description": "Context about the nested field that may include how to find and how to format it.", "type": "string", "example": "The street name from the address section" }, "type": { "description": "The type of the nested field. Allowed types include `string`, `float`, `date`, `number`, `text`, `boolean`, `enum` and `multiSelect`.", "type": "string", "example": "string" }, "options": { "description": "A list of options for this nested field. Used with `enum` and `multiSelect` types.", "type": "array", "items": { "$ref": "#/components/schemas/AiExtractFieldOption" } } }, "required": [ "key" ], "title": "AI Extract Structured Nested Field" }, "AiItem--Base": { "description": "The item to be processed by the LLM.", "type": "object", "properties": { "id": { "description": "The ID of the file.", "type": "string", "example": "123" }, "type": { "description": "The type of the item. Currently the value can be `file` only.", "type": "string", "example": "file", "enum": [ "file" ] }, "content": { "description": "The content of the item, often the text representation.", "example": "This is file content.", "type": "string" } }, "required": [ "id", "type" ], "title": "AI Item (Base)", "x-box-variant": "base", "x-box-variants": [ "base" ] }, "AiItemAsk": { "description": "The item to be processed by the LLM for ask requests.", "type": "object", "properties": { "id": { "description": "The ID of the file, or the ID of the Box Hub when `type` is `hubs`.", "type": "string", "example": "123" }, "type": { "description": "The type of the item. Use `file` to ask a question about a file, or `hubs` to search across and ask a question about the entire contents of a Box Hub. A `hubs` item must be the only item in the request.", "type": "string", "example": "file", "enum": [ "file", "hubs" ] }, "content": { "description": "The content of the item, often the text representation.", "example": "This is file content.", "type": "string" } }, "required": [ "id", "type" ], "title": "AI Item Ask" }, "AiLlmEndpointParams": { "description": "The parameters for the LLM endpoint specific to a model.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiLlmEndpointParamsOpenAi" }, { "$ref": "#/components/schemas/AiLlmEndpointParamsGoogle" }, { "$ref": "#/components/schemas/AiLlmEndpointParamsAWS" }, { "$ref": "#/components/schemas/AiLlmEndpointParamsIBM" } ], "title": "AI LLM endpoint parameters" }, "AiLlmEndpointParamsAWS": { "description": "AI LLM endpoint params AWS object.", "type": "object", "properties": { "type": { "description": "The type of the AI LLM endpoint params object for AWS. This parameter is **required**.", "type": "string", "example": "aws_params", "enum": [ "aws_params" ], "nullable": false }, "temperature": { "description": "What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.", "type": "number", "example": 0.5, "maximum": 1, "minimum": 0, "nullable": true }, "top_p": { "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.", "type": "number", "example": 0.5, "maximum": 1, "minimum": 0, "nullable": true } }, "required": [ "type" ], "title": "AI LLM endpoint params AWS", "x-box-resource-id": "ai_llm_endpoint_params_aws" }, "AiLlmEndpointParamsGoogle": { "description": "AI LLM endpoint params Google object.", "type": "object", "properties": { "type": { "description": "The type of the AI LLM endpoint params object for Google. This parameter is **required**.", "type": "string", "example": "google_params", "enum": [ "google_params" ], "nullable": false }, "temperature": { "description": "The temperature is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection.", "type": "number", "example": 0, "maximum": 2, "minimum": 0, "nullable": true }, "top_p": { "description": "`Top-P` changes how the model selects tokens for output. Tokens are selected from the most (see `top-K`) to least probable until the sum of their probabilities equals the `top-P` value.", "type": "number", "example": 1, "maximum": 2, "minimum": 0.1, "nullable": true }, "top_k": { "description": "`Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature.", "type": "number", "example": 1, "maximum": 2, "minimum": 0.1, "nullable": true } }, "required": [ "type" ], "title": "AI LLM endpoint params Google", "x-box-resource-id": "ai_llm_endpoint_params_google" }, "AiLlmEndpointParamsIBM": { "description": "AI LLM endpoint params IBM object.", "type": "object", "properties": { "type": { "description": "The type of the AI LLM endpoint params object for IBM. This parameter is **required**.", "type": "string", "example": "ibm_params", "enum": [ "ibm_params" ], "nullable": false }, "temperature": { "description": "What sampling temperature to use, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.", "type": "number", "example": 0.5, "nullable": true }, "top_p": { "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.", "type": "number", "example": 0.5, "maximum": 1, "minimum": 0.1, "nullable": true }, "top_k": { "description": "`Top-K` changes how the model selects tokens for output. A low `top-K` means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a high `top-K` means that the next token is selected from among the three most probable tokens by using temperature.", "type": "number", "example": 1, "nullable": true } }, "required": [ "type" ], "title": "AI LLM endpoint params IBM", "x-box-resource-id": "ai_llm_endpoint_params_ibm" }, "AiLlmEndpointParamsOpenAi": { "description": "AI LLM endpoint params OpenAI object.", "type": "object", "properties": { "type": { "description": "The type of the AI LLM endpoint params object for OpenAI. This parameter is **required**.", "type": "string", "example": "openai_params", "enum": [ "openai_params" ], "nullable": false }, "temperature": { "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.", "type": "number", "example": 0, "maximum": 2, "minimum": 0, "nullable": true }, "top_p": { "description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.", "type": "number", "example": 1, "maximum": 1, "minimum": 0.1, "nullable": true }, "frequency_penalty": { "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.", "type": "number", "example": 1.5, "maximum": 2, "minimum": -2, "nullable": true }, "presence_penalty": { "description": "A number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.", "type": "number", "example": 1.5, "maximum": 2, "minimum": -2, "nullable": true }, "stop": { "description": "Up to 4 sequences where the API will stop generating further tokens.", "type": "string", "example": "<|im_end|>", "nullable": true } }, "required": [ "type" ], "title": "AI LLM endpoint params OpenAI", "x-box-resource-id": "ai_llm_endpoint_params_openai" }, "AiMultipleAgentResponse": { "description": "List of AI Agents with pagination.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "The list of AI Agents.", "type": "array", "items": { "$ref": "#/components/schemas/AiSingleAgentResponse--Full" } } } } ], "required": [ "entries" ], "title": "AI agents list", "x-box-resource-id": "ai_multiple_agent_response", "x-box-tag": "ai_studio" }, "AiOptionsRules": { "description": "An object for a `taxonomy` type template field containing configuration for taxonomy options. Required if using `taxonomy` type field.", "type": "object", "properties": { "multi_select": { "description": "Indicates whether the field is a multi-select field. If true, the field can have multiple values.", "type": "boolean", "example": true }, "selectable_levels": { "description": "The selectable levels for the field. This is used to limit the levels of the taxonomy that can be selected.", "type": "array", "items": { "type": "integer", "description": "The level of the taxonomy that can be selected.", "example": 1 } } }, "title": "AI Options Rules" }, "AiResponse": { "description": "AI response.", "type": "object", "properties": { "answer": { "description": "The answer provided by the LLM.", "type": "string", "example": "Public APIs are important because of key and important reasons." }, "created_at": { "description": "The ISO date formatted timestamp of when the answer to the prompt was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "completion_reason": { "description": "The reason the response finishes.", "type": "string", "example": "done" }, "ai_agent_info": { "$ref": "#/components/schemas/AiAgentInfo" } }, "required": [ "answer", "created_at" ], "title": "AI response", "x-box-resource-id": "ai_response", "x-box-tag": "ai", "x-box-variant": "standard", "x-box-variants": [ "standard", "full" ] }, "AiResponse--Full": { "description": "AI ask response.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiResponse" }, { "properties": { "citations": { "description": "The citations of the LLM's answer reference.", "type": "array", "items": { "$ref": "#/components/schemas/AiCitation" } } } } ], "required": [ "answer", "created_at" ], "title": "AI response (Full)", "x-box-resource-id": "ai_response--full", "x-box-tag": "ai", "x-box-variant": "full", "x-box-variants": [ "standard", "full" ] }, "AiSingleAgentResponse": { "description": "Standard representation of an AI Agent instance.", "type": "object", "properties": { "id": { "description": "The unique identifier of the AI Agent.", "type": "string", "example": "1234567890" }, "type": { "description": "The type of agent used to handle queries.", "type": "string", "example": "ai_agent", "enum": [ "ai_agent" ] }, "origin": { "description": "The provider of the AI Agent.", "type": "string", "example": "CUSTOM" }, "name": { "description": "The name of the AI Agent.", "type": "string", "example": "This is my Agent" }, "access_state": { "description": "The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`.", "type": "string", "example": "enabled", "title": "Access State", "x-box-tag": "ai_studio" }, "created_by": { "description": "The user who created this agent.", "allOf": [ { "$ref": "#/components/schemas/User--Base" } ] }, "created_at": { "description": "The ISO date-time formatted timestamp of when this AI agent was created.", "type": "string", "format": "date-time", "example": "2022-01-01T00:00:00Z" }, "modified_by": { "description": "The user who most recently modified this agent.", "allOf": [ { "$ref": "#/components/schemas/User--Base" } ] }, "modified_at": { "description": "The ISO date-time formatted timestamp of when this AI agent was recently modified.", "type": "string", "format": "date-time", "example": "2022-01-01T00:00:00Z" }, "icon_reference": { "description": "The icon reference of the AI Agent.", "type": "string", "example": "https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg", "minLength": 1 }, "allowed_entities": { "description": "List of allowed users or groups.", "type": "array", "items": { "$ref": "#/components/schemas/AiAgentAllowedEntity" } } }, "required": [ "id", "origin", "name", "access_state" ], "title": "AI agent", "x-box-resource-id": "ai_single_agent_response", "x-box-tag": "ai_studio", "x-box-variant": "standard", "x-box-variants": [ "standard", "full" ] }, "AiSingleAgentResponse--Full": { "description": "Full representation of an AI Agent instance.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiSingleAgentResponse" }, { "properties": { "ask": { "$ref": "#/components/schemas/AiStudioAgentAskResponse" }, "text_gen": { "$ref": "#/components/schemas/AiStudioAgentTextGenResponse" }, "extract": { "$ref": "#/components/schemas/AiStudioAgentExtractResponse" } } } ], "required": [ "id", "origin", "name", "access_state" ], "title": "AI agent (Full)", "x-box-resource-id": "ai_single_agent_response--full", "x-box-tag": "ai_studio", "x-box-variant": "full", "x-box-variants": [ "standard", "full" ] }, "AiStudioAgentAsk": { "description": "The AI agent to be used to handle queries.", "type": "object", "properties": { "type": { "description": "The type of AI agent used to handle queries.", "type": "string", "example": "ai_agent_ask", "enum": [ "ai_agent_ask" ], "nullable": false }, "access_state": { "description": "The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.", "type": "string", "example": "enabled", "title": "Capability Access State", "x-box-tag": "ai_studio" }, "description": { "description": "The description of the AI agent.", "type": "string", "example": "This is ASK Agent" }, "custom_instructions": { "description": "Custom instructions for the AI agent.", "type": "string", "example": "This is a custom instruction", "nullable": true }, "suggested_questions": { "description": "Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed.", "type": "array", "items": { "type": "string" }, "example": [ "What is in this file?", "What are the main highlights of this document?" ], "maxItems": 4 }, "long_text": { "$ref": "#/components/schemas/AiStudioAgentLongTextTool" }, "basic_text": { "$ref": "#/components/schemas/AiStudioAgentBasicTextTool" }, "basic_image": { "$ref": "#/components/schemas/AiStudioAgentBasicTextTool" }, "spreadsheet": { "$ref": "#/components/schemas/AiStudioAgentSpreadsheetTool" }, "long_text_multi": { "$ref": "#/components/schemas/AiStudioAgentLongTextTool" }, "basic_text_multi": { "$ref": "#/components/schemas/AiStudioAgentBasicTextTool" }, "basic_image_multi": { "$ref": "#/components/schemas/AiStudioAgentBasicTextTool" } }, "required": [ "type", "access_state", "description" ], "title": "AI agent capability ask request", "x-box-resource-id": "ai_studio_agent_ask", "x-box-tag": "ai_studio" }, "AiStudioAgentAskResponse": { "description": "The AI agent to be used to ask questions.", "type": "object", "properties": { "type": { "description": "The type of AI agent used to ask questions.", "type": "string", "example": "ai_agent_ask", "enum": [ "ai_agent_ask" ], "nullable": false }, "access_state": { "description": "The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.", "type": "string", "example": "enabled", "title": "Capability Access State", "x-box-tag": "ai_studio" }, "description": { "description": "The description of the AI agent.", "type": "string", "example": "This is ASK Agent" }, "custom_instructions": { "description": "Custom instructions for the AI agent.", "type": "string", "example": "This is a custom instruction", "nullable": true }, "suggested_questions": { "description": "Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed.", "type": "array", "items": { "type": "string" }, "example": [ "What is in this file?", "What are the main highlights of this document?" ], "maxItems": 4 }, "long_text": { "$ref": "#/components/schemas/AiStudioAgentLongTextToolResponse" }, "basic_text": { "$ref": "#/components/schemas/AiStudioAgentBasicTextToolResponse" }, "basic_image": { "$ref": "#/components/schemas/AiStudioAgentBasicTextToolResponse" }, "spreadsheet": { "$ref": "#/components/schemas/AiStudioAgentSpreadsheetToolResponse" }, "long_text_multi": { "$ref": "#/components/schemas/AiStudioAgentLongTextToolResponse" }, "basic_text_multi": { "$ref": "#/components/schemas/AiStudioAgentBasicTextToolResponse" }, "basic_image_multi": { "$ref": "#/components/schemas/AiStudioAgentBasicTextToolResponse" } }, "required": [ "type", "access_state", "description" ], "title": "AI agent capability ask", "x-box-resource-id": "ai_studio_agent_ask_response", "x-box-tag": "ai_studio" }, "AiStudioAgentBasicGenTool": { "description": "AI agent basic tool used to generate text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentBasicGenTool" }, { "properties": { "is_custom_instructions_included": { "description": "True if system message contains custom instructions placeholder, false otherwise.", "type": "boolean", "example": false } } } ], "title": "AI agent basic text generation tool request", "x-box-tag": "ai" }, "AiStudioAgentBasicGenToolResponse": { "description": "AI agent basic tool used to generate text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiStudioAgentBasicGenTool" }, { "properties": { "warnings": { "description": "Warnings concerning tool.", "type": "array", "items": { "type": "string" }, "example": [ "MODEL_INACTIVE" ] } } } ], "title": "AI agent basic text generation tool", "x-box-tag": "ai" }, "AiStudioAgentBasicTextTool": { "description": "AI agent processor used to handle basic text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentBasicTextTool" }, { "properties": { "is_custom_instructions_included": { "description": "True if system message contains custom instructions placeholder, false otherwise.", "type": "boolean", "example": false } } } ], "title": "AI agent basic text tool request", "x-box-tag": "ai" }, "AiStudioAgentBasicTextToolResponse": { "description": "AI agent processor used to handle basic text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiStudioAgentBasicTextTool" }, { "properties": { "warnings": { "description": "Warnings concerning tool.", "type": "array", "items": { "type": "string" }, "example": [ "MODEL_INACTIVE" ] } } } ], "title": "AI agent basic text tool", "x-box-tag": "ai" }, "AiStudioAgentExtract": { "description": "The AI agent to be used for metadata extraction.", "type": "object", "properties": { "type": { "description": "The type of AI agent to be used for metadata extraction.", "type": "string", "example": "ai_agent_extract", "enum": [ "ai_agent_extract" ], "nullable": false }, "access_state": { "description": "The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.", "type": "string", "example": "enabled", "title": "Capability Access State", "x-box-tag": "ai_studio" }, "description": { "description": "The description of the AI agent.", "type": "string", "example": "This is ASK Agent" }, "custom_instructions": { "description": "Custom instructions for the AI agent.", "type": "string", "example": "This is a custom instruction", "nullable": true }, "long_text": { "$ref": "#/components/schemas/AiStudioAgentLongTextTool" }, "basic_text": { "$ref": "#/components/schemas/AiStudioAgentBasicTextTool" }, "basic_image": { "$ref": "#/components/schemas/AiStudioAgentBasicTextTool" } }, "required": [ "type", "access_state", "description" ], "title": "AI agent capability extract request", "x-box-resource-id": "ai_studio_agent_extract", "x-box-tag": "ai_studio" }, "AiStudioAgentExtractResponse": { "description": "The AI agent to be used for metadata extraction.", "type": "object", "properties": { "type": { "description": "The type of AI agent to be used for metadata extraction.", "type": "string", "example": "ai_agent_extract", "enum": [ "ai_agent_extract" ], "nullable": false }, "access_state": { "description": "The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.", "type": "string", "example": "enabled", "title": "Capability Access State", "x-box-tag": "ai_studio" }, "description": { "description": "The description of the AI agent.", "type": "string", "example": "This is ASK Agent" }, "custom_instructions": { "description": "Custom instructions for the AI agent.", "type": "string", "example": "This is a custom instruction", "nullable": true }, "long_text": { "$ref": "#/components/schemas/AiStudioAgentLongTextToolResponse" }, "basic_text": { "$ref": "#/components/schemas/AiStudioAgentBasicTextToolResponse" }, "basic_image": { "$ref": "#/components/schemas/AiStudioAgentBasicTextToolResponse" } }, "required": [ "type", "access_state", "description" ], "title": "AI agent capability extract", "x-box-resource-id": "ai_studio_agent_extract_response", "x-box-tag": "ai_studio" }, "AiStudioAgentLongTextTool": { "description": "AI agent processor used to to handle longer text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentLongTextTool" }, { "properties": { "is_custom_instructions_included": { "description": "True if system message contains custom instructions placeholder, false otherwise.", "type": "boolean", "example": false } } } ], "title": "AI agent long text tool request", "x-box-tag": "ai" }, "AiStudioAgentLongTextToolResponse": { "description": "AI agent processor used to to handle longer text.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiStudioAgentLongTextTool" }, { "properties": { "warnings": { "description": "Warnings concerning tool.", "type": "array", "items": { "type": "string" }, "example": [ "MODEL_INACTIVE" ] } } } ], "title": "AI agent long text tool", "x-box-tag": "ai" }, "AiStudioAgentSpreadsheetTool": { "description": "The AI agent tool used to handle spreadsheets and tabular data.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiAgentSpreadsheetTool" }, { "properties": {} } ], "title": "AI agent spreadsheet tool", "x-box-tag": "ai" }, "AiStudioAgentSpreadsheetToolResponse": { "description": "The AI agent tool used to handle spreadsheets and tabular data.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AiStudioAgentSpreadsheetTool" }, { "properties": { "warnings": { "description": "Warnings concerning tool.", "type": "array", "items": { "type": "string" }, "example": [ "MODEL_INACTIVE" ] } } } ], "title": "AI agent spreadsheet tool", "x-box-tag": "ai" }, "AiStudioAgentTextGen": { "description": "The AI agent to be used to generate text.", "type": "object", "properties": { "type": { "description": "The type of AI agent used for generating text.", "type": "string", "example": "ai_agent_text_gen", "enum": [ "ai_agent_text_gen" ], "nullable": false }, "access_state": { "description": "The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.", "type": "string", "example": "enabled", "title": "Capability Access State", "x-box-tag": "ai_studio" }, "description": { "description": "The description of the AI agent.", "type": "string", "example": "This is ASK Agent" }, "custom_instructions": { "description": "Custom instructions for the AI agent.", "type": "string", "example": "This is a custom instruction", "nullable": true }, "suggested_questions": { "description": "Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed.", "type": "array", "items": { "type": "string" }, "example": [ "What is in this file?", "What are the main highlights of this document?" ], "maxItems": 4 }, "basic_gen": { "$ref": "#/components/schemas/AiStudioAgentBasicGenTool" } }, "required": [ "type", "access_state", "description" ], "title": "AI agent capability text generation request", "x-box-resource-id": "ai_studio_agent_text_gen", "x-box-tag": "ai_studio" }, "AiStudioAgentTextGenResponse": { "description": "The AI agent to be used to generate text.", "type": "object", "properties": { "type": { "description": "The type of AI agent used for generating text.", "type": "string", "example": "ai_agent_text_gen", "enum": [ "ai_agent_text_gen" ], "nullable": false }, "access_state": { "description": "The state of the AI Agent capability. Possible values are: `enabled` and `disabled`.", "type": "string", "example": "enabled", "title": "Capability Access State", "x-box-tag": "ai_studio" }, "description": { "description": "The description of the AI agent.", "type": "string", "example": "This is ASK Agent" }, "custom_instructions": { "description": "Custom instructions for the AI agent.", "type": "string", "example": "This is a custom instruction", "nullable": true }, "suggested_questions": { "description": "Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed.", "type": "array", "items": { "type": "string" }, "example": [ "What is in this file?", "What are the main highlights of this document?" ], "maxItems": 4 }, "basic_gen": { "$ref": "#/components/schemas/AiStudioAgentBasicGenToolResponse" } }, "required": [ "type", "access_state", "description" ], "title": "AI agent capability text generation", "x-box-resource-id": "ai_studio_agent_text_gen_response", "x-box-tag": "ai_studio" }, "AiTaxonomyFileReference": { "description": "A taxonomy `.csv` file to be used for the structured extraction. For your request to work, `fields` must also be provided.", "type": "object", "properties": { "type": { "description": "The type of the taxonomy source.", "type": "string", "example": "file", "enum": [ "file" ] }, "taxonomy_key": { "description": "The identifier for a taxonomy, which corresponds to the `taxonomy_key` of the taxonomy source.", "type": "string", "example": "certification_taxonomy" }, "id": { "description": "The ID of the taxonomy source. Required if the type is `file` and unsupported if the type is `taxonomy`.", "type": "string", "example": "1234567890" } }, "title": "AI Taxonomy File Reference" }, "AiTaxonomyReference": { "description": "A taxonomy source to be used for the structured extraction. For your request to work, `fields` must also be provided.", "type": "object", "properties": { "type": { "description": "The type of the taxonomy source.", "type": "string", "example": "taxonomy", "enum": [ "taxonomy" ] }, "taxonomy_key": { "description": "The identifier for a taxonomy, which corresponds to the `taxonomy_key` of the taxonomy source.", "type": "string", "example": "certification_taxonomy" }, "namespace": { "description": "The namespace of the taxonomy source.", "type": "string", "example": "enterprise_123" } }, "title": "AI Taxonomy Reference" }, "AiTaxonomySource": { "description": "A taxonomy source to be used for the structured extraction. It can either be an existing CSV file or a taxonomy.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiTaxonomyReference" }, { "$ref": "#/components/schemas/AiTaxonomyFileReference" } ], "title": "AI Taxonomy Source" }, "AiTextGen": { "description": "AI text gen request object.", "type": "object", "properties": { "prompt": { "description": "The prompt provided by the client to be answered by the LLM. The prompt's length is limited to 10000 characters.", "type": "string", "example": "Write an email to a client about the importance of public APIs." }, "items": { "description": "The items to be processed by the LLM, often files. The array can include **exactly one** element.\n\n**Note**: Box AI handles documents with text representations up to 2MB in size. If the file size exceeds 2MB, the first 2MB of text representation will be processed.", "type": "array", "items": { "required": [ "id", "type" ], "type": "object", "description": "The item to be processed by the LLM.", "properties": { "id": { "description": "The ID of the item.", "type": "string", "example": "123" }, "type": { "description": "The type of the item.", "type": "string", "example": "file", "enum": [ "file" ] }, "content": { "description": "The content to use as context for generating new text or editing existing text.", "example": "This is file content that is relevant to the text gen request.", "type": "string" } } }, "maxItems": 1, "minItems": 1, "uniqueItems": true }, "dialogue_history": { "description": "The history of prompts and answers previously passed to the LLM. This parameter provides the additional context to the LLM when generating the response.", "type": "array", "items": { "$ref": "#/components/schemas/AiDialogueHistory" } }, "ai_agent": { "allOf": [ { "$ref": "#/components/schemas/AiTextGenAgent" }, { "description": "The AI agent to be used for generating text." } ] } }, "required": [ "prompt", "items" ], "title": "AI text gen request", "x-box-tag": "ai" }, "AiTextGenAgent": { "description": "The AI agent to be used to handle the AI text generation request.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiAgentReference" }, { "$ref": "#/components/schemas/AiAgentTextGen" } ], "title": "AI text gen request agent" }, "AppItem": { "description": "An app item represents an content object owned by an application. It can group files and folders together from different paths. That set can be shared via a collaboration.", "type": "object", "properties": { "id": { "description": "The unique identifier for this app item.", "type": "string", "example": "12345678" }, "type": { "description": "The value will always be `app_item`.", "type": "string", "example": "app_item", "enum": [ "app_item" ] }, "application_type": { "description": "The type of the app that owns this app item.", "type": "string", "example": "hubs" } }, "required": [ "id", "type", "application_type" ], "title": "App item", "x-box-resource-id": "app_item", "x-box-tag": "app_item_associations" }, "AppItemAssociatedItem": { "description": "The file, folder or web link which is associated with the app item.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/File--Base" }, { "$ref": "#/components/schemas/Folder--Base" }, { "$ref": "#/components/schemas/WebLink--Base" } ], "title": "App item associated item" }, "AppItemAssociation": { "description": "An app item association represents an association between a file or folder and an app item. Associations between a folder and an app item cascade down to all descendants of the folder.", "type": "object", "properties": { "id": { "description": "The unique identifier for this app item association.", "type": "string", "example": "12345678", "nullable": false }, "type": { "description": "The value will always be `app_item_association`.", "type": "string", "example": "app_item_association", "enum": [ "app_item_association" ], "nullable": false }, "app_item": { "allOf": [ { "$ref": "#/components/schemas/AppItem" }, { "description": "The app item which is associated with the file or folder." } ], "nullable": false }, "item": { "$ref": "#/components/schemas/AppItemAssociatedItem" } }, "required": [ "id", "type", "app_item", "item" ], "title": "App item association", "x-box-resource-id": "app_item_association", "x-box-tag": "app_item_associations" }, "AppItemAssociations": { "description": "A list of app item associations.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AppItemAssociation" } } } } ], "title": "App item associations", "x-box-resource-id": "app_item_associations", "x-box-tag": "app_item_associations" }, "AppItemEventSource": { "description": "The AppItem that triggered an event in the event stream.", "type": "object", "properties": { "id": { "description": "The id of the `AppItem`.", "type": "string", "example": "6374669741" }, "type": { "description": "The type of the source that this event represents. Can only be `app_item`.", "type": "string", "example": "app_item", "enum": [ "app_item" ], "nullable": false }, "app_item_type": { "description": "The type of the `AppItem`.", "type": "string", "example": "hubs" }, "user": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that triggered the event." } ] }, "group": { "allOf": [ { "$ref": "#/components/schemas/Group--Mini" }, { "description": "The group that triggered the event." } ] } }, "required": [ "id", "type", "app_item_type" ], "title": "AppItem event source", "x-box-resource-id": "app_item_event_source" }, "Classification": { "description": "An instance of the classification metadata template, containing the classification applied to the file or folder.\n\nTo get more details about the classification applied to an item, request the classification metadata template.", "type": "object", "properties": { "Box__Security__Classification__Key": { "description": "The name of the classification applied to the item.", "type": "string", "example": "Sensitive" }, "$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}`.", "type": "string", "example": "folder_59449484661," }, "$template": { "description": "The value will always be `securityClassification-6VMVochwUWo`.", "type": "string", "example": "securityClassification-6VMVochwUWo", "enum": [ "securityClassification-6VMVochwUWo" ] }, "$scope": { "description": "The scope of the enterprise that this classification has been applied for.\n\nThis will be in the format `enterprise_{enterprise_id}`.", "type": "string", "example": "enterprise_27335" }, "$version": { "description": "The version of the metadata instance. This version starts at 0 and increases every time a classification is updated.", "type": "integer", "example": 1 }, "$type": { "description": "The unique ID of this classification instance. This will be include the name of the classification template and a unique ID.", "type": "string", "example": "securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8" }, "$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.", "type": "number", "example": 5 }, "$canEdit": { "description": "Whether an end user can change the classification.", "type": "boolean", "example": true } }, "title": "Classification", "x-box-resource-id": "classification", "x-box-tag": "classifications" }, "ClassificationTemplate": { "description": "A metadata template that holds the security classifications defined by an enterprise.", "type": "object", "properties": { "id": { "description": "The ID of the classification template.", "type": "string", "example": "58063d82-4128-7b43-bba9-92f706befcdf" }, "type": { "description": "The value will always be `metadata_template`.", "type": "string", "example": "metadata_template", "enum": [ "metadata_template" ], "nullable": false }, "scope": { "description": "The scope of the classification template. This is in the format `enterprise_{id}` where the `id` is the enterprise ID.", "type": "string", "example": "enterprise_123456" }, "templateKey": { "description": "The value will always be `securityClassification-6VMVochwUWo`.", "type": "string", "example": "securityClassification-6VMVochwUWo", "enum": [ "securityClassification-6VMVochwUWo" ] }, "displayName": { "description": "The name of this template as shown in web and mobile interfaces.", "type": "string", "example": "Classification", "enum": [ "Classification" ] }, "hidden": { "description": "Determines if the template is always available in web and mobile interfaces.", "type": "boolean", "example": false }, "copyInstanceOnItemCopy": { "description": "Determines if classifications are copied along when the file or folder is copied.", "type": "boolean", "example": true }, "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.", "type": "array", "items": { "type": "object", "required": [ "id", "type", "key", "displayName", "options" ], "description": "The metadata template field that represents the available classifications.", "properties": { "id": { "description": "The unique ID of the field.", "type": "string", "example": "822227e0-47a5-921b-88a8-494760b2e6d2" }, "type": { "description": "The array item type.", "type": "string", "example": "enum", "enum": [ "enum" ] }, "key": { "description": "Defines classifications available in the enterprise.", "type": "string", "example": "Box__Security__Classification__Key", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { "description": "The value will always be `Classification`.", "type": "string", "example": "Classification", "enum": [ "Classification" ] }, "hidden": { "description": "Classifications are always visible to web and mobile users.", "type": "boolean", "example": false }, "options": { "description": "A list of classifications available in this enterprise.", "type": "array", "items": { "required": [ "key", "id" ], "type": "object", "description": "A single classification available in this enterprise.", "properties": { "id": { "description": "The unique ID of this classification.", "type": "string", "example": "46aea176-3483-4431-856c-6b5b13d1cc50" }, "key": { "description": "The display name and key for this classification.", "type": "string", "example": "Sensitive" }, "staticConfig": { "description": "Additional information about the classification.", "type": "object", "properties": { "classification": { "description": "Additional information about the classification.\n\nThis 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.", "type": "object", "properties": { "classificationDefinition": { "description": "A longer description of the classification.", "type": "string", "example": "Sensitive information" }, "colorID": { "description": "An internal Box identifier used to assign a color to a classification label.\n\nMapping between a `colorID` and a color may change without notice. Currently, the color mappings are as follows.\n\n- `0`: Yellow.\n- `1`: Orange.\n- `2`: Watermelon red.\n- `3`: Purple rain.\n- `4`: Light blue.\n- `5`: Dark blue.\n- `6`: Light green.\n- `7`: Gray.", "type": "integer", "format": "int64", "example": 4 } } } } } } }, "minItems": 1 } } }, "maxItems": 1, "minItems": 1 } }, "required": [ "id", "type", "scope", "displayName", "fields", "templateKey" ], "title": "Classification Template", "x-box-resource-id": "classification_template", "x-box-tag": "classifications" }, "ClientError": { "description": "A generic error.", "type": "object", "properties": { "type": { "description": "The value will always be `error`.", "type": "string", "example": "error", "enum": [ "error" ], "nullable": false }, "status": { "description": "The HTTP status of the response.", "type": "integer", "format": "int32", "example": 400, "nullable": false }, "code": { "description": "A Box-specific error code.", "type": "string", "example": "item_name_invalid", "enum": [ "created", "accepted", "no_content", "redirect", "not_modified", "bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "precondition_failed", "too_many_requests", "internal_server_error", "unavailable", "item_name_invalid", "insufficient_scope" ] }, "message": { "description": "A short message describing the error.", "type": "string", "example": "Method Not Allowed", "nullable": false }, "context_info": { "description": "A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.", "type": "object", "example": { "message": "Something went wrong" }, "additionalProperties": {}, "nullable": true }, "help_url": { "description": "A URL that links to more information about why this error occurred.", "type": "string", "example": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/", "nullable": false }, "request_id": { "description": "A unique identifier for this response, which can be used when contacting Box support.", "type": "string", "example": "abcdef123456", "nullable": false } }, "title": "Client error", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for this collaboration.", "type": "string", "example": "12345678" }, "type": { "description": "The value will always be `collaboration`.", "type": "string", "example": "collaboration", "enum": [ "collaboration" ] }, "item": { "allOf": [ { "$ref": "#/components/schemas/CollaborationItem" }, { "description": "The file or folder to which access is granted. The field is `null` when the collaboration `status` is `pending` or the collaboration is created on an app item (see `app_item` field)." } ], "nullable": true }, "app_item": { "allOf": [ { "$ref": "#/components/schemas/AppItem" }, { "description": "An `app_item` to which access is granted. The field is `null` when the collaboration is created on an item (see `item` field), or the `app_item` is inaccessible. The role cascades to all items associated with the `app_item`." } ], "nullable": true }, "accessible_by": { "$ref": "#/components/schemas/CollaborationAccessGrantee" }, "invite_email": { "description": "The email address used to invite an unregistered collaborator, if they are not a registered user.", "type": "string", "example": "john@example.com", "nullable": true }, "role": { "description": "The level of access granted.", "type": "string", "example": "editor", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner", "owner" ] }, "expires_at": { "description": "When the collaboration will expire, or `null` if no expiration date is set.", "type": "string", "format": "date-time", "example": "2012-12-26T10:53:43-08:00", "nullable": true }, "is_access_only": { "description": "If set to `true`, collaborators have access to shared items, but such items won't be visible in the All Files list. Additionally, collaborators won't see the path to the root folder for the shared item.", "type": "boolean", "example": true }, "status": { "description": "The status of the collaboration invitation. If the status is `pending`, `name` returns an empty string.", "type": "string", "example": "accepted", "enum": [ "accepted", "pending", "rejected" ] }, "acknowledged_at": { "description": "When the `status` of the collaboration object changed to `accepted` or `rejected`.", "type": "string", "format": "date-time", "example": "2012-12-12T10:55:20-08:00" }, "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" } ] } ] }, "created_at": { "description": "When the collaboration object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the collaboration object was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "acceptance_requirements_status": { "type": "object", "properties": { "terms_of_service_requirement": { "type": "object", "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.", "type": "boolean", "example": true, "nullable": true }, "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." } ] } } }, "strong_password_requirement": { "type": "object", "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, or enforces an exposed password detection for the external collaborators.", "type": "boolean", "example": true }, "user_has_strong_password": { "description": "Whether or not the user has a strong and not exposed password set for their account. The field is `null` when a strong password is not required.", "type": "boolean", "example": true, "nullable": true } } }, "two_factor_authentication_requirement": { "type": "object", "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.", "type": "boolean", "example": true }, "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.", "type": "boolean", "example": true, "nullable": true } } } } } }, "required": [ "id", "type" ], "title": "Collaboration", "x-box-resource-id": "collaboration", "x-box-tag": "user_collaborations" }, "CollaborationAccessGrantee": { "description": "The user or group that is granted access.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/User--Collaborations" }, { "$ref": "#/components/schemas/Group--Mini" } ], "title": "Collaboration access grantee" }, "CollaborationAllowlistEntries": { "description": "A list of allowed domains for collaboration.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of allowed collaboration domains.", "type": "array", "items": { "$ref": "#/components/schemas/CollaborationAllowlistEntry" } } } } ], "title": "Allowed collaboration domains", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for this entry.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `collaboration_whitelist_entry`.", "type": "string", "example": "collaboration_whitelist_entry", "enum": [ "collaboration_whitelist_entry" ] }, "domain": { "description": "The whitelisted domain.", "type": "string", "example": "example.com" }, "direction": { "description": "The direction of the collaborations to allow.", "type": "string", "example": "both", "enum": [ "inbound", "outbound", "both" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise.", "properties": { "id": { "description": "The unique identifier for this enterprise.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise.", "type": "string", "example": "Acme Inc." } } }, { "description": "The enterprise this list is applied to." } ] }, "created_at": { "description": "The time the entry was created at.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "title": "Allowed collaboration domain", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for this exemption.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `collaboration_whitelist_exempt_target`.", "type": "string", "example": "collaboration_whitelist_exempt_target", "enum": [ "collaboration_whitelist_exempt_target" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise.", "properties": { "id": { "description": "The unique identifier for this enterprise.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise.", "type": "string", "example": "Acme Inc." } } }, { "description": "The enterprise this entry belongs to." } ] }, "user": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that has been exempt." } ] }, "created_at": { "description": "The time the entry was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "The time the entry was modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "title": "Allowed collaboration domains user exemption", "x-box-resource-id": "collaboration_allowlist_exempt_target", "x-box-tag": "collaboration_allowlist_exempt_targets" }, "CollaborationAllowlistExemptTargets": { "description": "A list of users exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of users exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise.", "type": "array", "items": { "$ref": "#/components/schemas/CollaborationAllowlistExemptTarget" } } } } ], "title": "Allowed collaboration domains user exemptions", "x-box-resource-id": "collaboration_allowlist_exempt_targets", "x-box-tag": "collaboration_allowlist_exempt_targets" }, "CollaborationItem": { "description": "A collaboration item.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Folder" }, { "$ref": "#/components/schemas/WebLink" } ], "title": "Collaboration item" }, "Collaborations": { "description": "A list of collaborations.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of collaborations.", "type": "array", "items": { "$ref": "#/components/schemas/Collaboration" } } } } ], "title": "Collaborations", "x-box-resource-id": "collaborations", "x-box-tag": "user_collaborations" }, "CollaborationsOffsetPaginated": { "description": "A list of collaborations.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 } } }, { "properties": { "entries": { "description": "A list of collaborations.", "type": "array", "items": { "$ref": "#/components/schemas/Collaboration" } } } } ], "title": "Collaborations", "x-box-resource-id": "collaborations_offset_paginated", "x-box-tag": "user_collaborations" }, "CollaboratorVariable": { "description": "A collaborator object. Allows to specify a list of user ID's that are affected by the workflow result.", "type": "object", "properties": { "type": { "description": "Collaborator object type.", "type": "string", "example": "variable", "enum": [ "variable" ] }, "variable_type": { "description": "Variable type for the Collaborator object.", "type": "string", "example": "user_list", "enum": [ "user_list" ] }, "variable_value": { "description": "A list of user IDs.", "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "description": "User variable used in workflow outcomes.", "properties": { "type": { "description": "The object type.", "type": "string", "example": "user", "enum": [ "user" ] }, "id": { "description": "User's ID.", "type": "string", "example": "636281" } } } } }, "required": [ "type", "variable_type", "variable_value" ], "title": "Collaborator variable" }, "Collection": { "description": "A collection of items, including files and folders.\n\nCurrently, the only collection available is the `favorites` collection.\n\nThe contents of a collection can be explored in a similar way to which the contents of a folder is explored.", "type": "object", "properties": { "id": { "description": "The unique identifier for this collection.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `collection`.", "type": "string", "example": "collection", "enum": [ "collection" ] }, "name": { "description": "The name of the collection.", "type": "string", "example": "Favorites", "enum": [ "Favorites" ] }, "collection_type": { "description": "The type of the collection. This is used to determine the proper visual treatment for collections.", "type": "string", "example": "favorites", "enum": [ "favorites" ] } }, "title": "Collection", "x-box-resource-id": "collection", "x-box-tag": "collections" }, "Collections": { "description": "A list of collections.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "A list of collections.", "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } ], "title": "Collections", "x-box-resource-id": "collections", "x-box-tag": "collections" }, "Comment": { "description": "Standard representation of a comment.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Comment--Base" }, { "properties": { "is_reply_comment": { "description": "Whether or not this comment is a reply to another comment.", "type": "boolean", "example": true }, "message": { "description": "The text of the comment, as provided by the user.", "type": "string", "example": "@Aaron Levie these tigers are cool!" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "A mini user object representing the author of the comment." } ] }, "created_at": { "description": "The time this comment was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "The time this comment was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "item": { "allOf": [ { "title": "Reference", "description": "The bare basic reference for an object.", "type": "object", "properties": { "id": { "description": "The unique identifier for this object.", "type": "string", "example": "11446498" }, "type": { "description": "The type for this object.", "type": "string", "example": "file" } } }, { "description": "The file this comment was placed on." } ] } } } ], "title": "Comment", "x-box-resource-id": "comment", "x-box-tag": "comments", "x-box-variant": "standard" }, "Comment--Base": { "description": "Base representation of a comment.", "type": "object", "properties": { "id": { "description": "The unique identifier for this comment.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `comment`.", "type": "string", "example": "comment", "enum": [ "comment" ] } }, "title": "Comment (Base)", "x-box-resource-id": "comment--base", "x-box-tag": "comments", "x-box-variant": "base", "x-box-variants": [ "base", "standard", "full" ] }, "Comment--Full": { "description": "Comments are messages created on files. Comments can be made independently or created as responses to other comments.", "type": "object", "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.", "type": "string", "example": "@[1234567:Aaron Levie] these tigers are cool!" } } } ], "title": "Comment (Full)", "x-box-resource-id": "comment--full", "x-box-tag": "comments", "x-box-variant": "full" }, "Comments": { "description": "A list of comments.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "A list of comments.", "type": "array", "items": { "$ref": "#/components/schemas/Comment--Full" } } } } ], "title": "Comments", "x-box-resource-id": "comments", "x-box-tag": "comments" }, "CompletionRuleVariable": { "description": "A completion rule object. Determines if an action should be completed by all or any assignees.", "type": "object", "properties": { "type": { "description": "Completion Rule object type.", "type": "string", "example": "variable", "enum": [ "variable" ] }, "variable_type": { "description": "Variable type for the Completion Rule object.", "type": "string", "example": "task_completion_rule", "enum": [ "task_completion_rule" ] }, "variable_value": { "description": "Variable values for a completion rule.", "type": "string", "example": "all_assignees", "enum": [ "all_assignees", "any_assignees" ] } }, "required": [ "type", "variable_type", "variable_value" ], "title": "Completion rule variable" }, "ConflictError": { "description": "The error that occurs when a file can not be created due to a conflict.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ClientError" }, { "properties": { "context_info": { "type": "object", "properties": { "conflicts": { "description": "A list of the file conflicts that caused this error.", "type": "array", "items": { "$ref": "#/components/schemas/FileConflict" } } } } } } ], "title": "Conflict error", "x-box-resource-id": "conflict_error", "x-box-tag": "uploads" }, "CreateAiAgent": { "description": "The schema for AI agent create request.", "type": "object", "properties": { "type": { "description": "The type of agent used to handle queries.", "type": "string", "example": "ai_agent", "enum": [ "ai_agent" ] }, "name": { "description": "The name of the AI Agent.", "type": "string", "example": "My AI Agent" }, "access_state": { "description": "The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`.", "type": "string", "example": "enabled", "title": "Access State", "x-box-tag": "ai_studio" }, "icon_reference": { "description": "The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/` where possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png`.", "type": "string", "example": "https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg", "minLength": 1 }, "allowed_entities": { "description": "List of allowed users or groups.", "type": "array", "items": { "$ref": "#/components/schemas/AiAgentAllowedEntity" } }, "ask": { "$ref": "#/components/schemas/AiStudioAgentAsk" }, "text_gen": { "$ref": "#/components/schemas/AiStudioAgentTextGen" }, "extract": { "$ref": "#/components/schemas/AiStudioAgentExtract" } }, "required": [ "type", "name", "access_state" ], "title": "Create AI agent request", "x-box-tag": "ai_studio" }, "DevicePinner": { "description": "Device pins allow enterprises to control what devices can use native Box applications.", "type": "object", "properties": { "id": { "description": "The unique identifier for this device pin.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `device_pinner`.", "type": "string", "example": "device_pinner", "enum": [ "device_pinner" ] }, "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.", "type": "string", "example": "iPad" } }, "title": "Device pinner", "x-box-resource-id": "device_pinner", "x-box-tag": "device_pinners" }, "DevicePinners": { "description": "A list of device pins.", "type": "object", "properties": { "entries": { "description": "A list of device pins.", "type": "array", "items": { "$ref": "#/components/schemas/DevicePinner" } }, "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.", "type": "integer", "format": "int64", "example": 200, "default": 100 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64", "example": 3000 }, "order": { "description": "The order by which items are returned.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field that is ordered by.", "type": "string", "example": "id", "enum": [ "id" ] }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "asc", "enum": [ "asc", "desc" ] } } } } }, "title": "Device pinners", "x-box-resource-id": "device_pinners", "x-box-tag": "device_pinners" }, "EmailAlias": { "description": "An email alias for a user.", "type": "object", "properties": { "id": { "description": "The unique identifier for this object.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `email_alias`.", "type": "string", "example": "email_alias", "enum": [ "email_alias" ] }, "email": { "description": "The email address.", "type": "string", "example": "alias@example.com" }, "is_confirmed": { "description": "Whether the email address has been confirmed.", "type": "boolean", "example": true } }, "title": "Email alias", "x-box-resource-id": "email_alias", "x-box-tag": "email_aliases" }, "EmailAliases": { "description": "A list of email aliases.", "type": "object", "properties": { "total_count": { "description": "The number of email aliases.", "type": "integer", "format": "int64", "example": 5000 }, "entries": { "description": "A list of email aliases.", "type": "array", "items": { "$ref": "#/components/schemas/EmailAlias" } } }, "title": "Email aliases", "x-box-resource-id": "email_aliases", "x-box-tag": "email_aliases" }, "Enterprise--Base": { "description": "A representation of a enterprise, used when nested within another resource.", "type": "object", "properties": { "id": { "description": "The unique identifier for this enterprise.", "type": "string", "example": "1910967" }, "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ], "nullable": false } }, "title": "Enterprise", "x-box-resource-id": "enterprise--base" }, "Event": { "description": "The description of an event that happened within Box.", "type": "object", "properties": { "type": { "description": "The value will always be `event`.", "type": "string", "example": "event" }, "created_at": { "description": "When the event object was created.", "type": "string", "format": "date-time", "example": "2022-12-12T10:53:43-08:00" }, "recorded_at": { "description": "When the event object was recorded in database.", "type": "string", "format": "date-time", "example": "2022-12-12T10:54:43-08:00" }, "event_id": { "description": "The ID of the event object. You can use this to detect duplicate events.", "type": "string", "example": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83" }, "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_type": { "allOf": [ { "title": "Event Type", "example": "FILE_MARKED_MALICIOUS", "type": "string", "description": "An event type that can trigger an event.", "enum": [ "ACCESS_GRANTED", "ACCESS_REVOKED", "ADD_DEVICE_ASSOCIATION", "ADD_LOGIN_ACTIVITY_DEVICE", "ADMIN_LOGIN", "ADVANCED_FOLDER_SETTINGS_UPDATE", "AI_SECURITY_DETECTION", "ANNOTATIONV2_CREATE", "ANNOTATIONV2_DELETE", "ANNOTATIONV2_EDIT", "APPLICATION_CREATED", "APPLICATION_PUBLIC_KEY_ADDED", "APPLICATION_PUBLIC_KEY_DELETED", "BOX_AI_USER_FAILED_REQUEST", "BOX_AI_USER_REQUEST", "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", "COLLECTION_CREATE", "COLLECTION_DELETE", "COLLECTION_ITEM_CREATE", "COLLECTION_ITEM_DELETE", "COLLECTION_ITEM_UPDATE", "COLLECTION_UPDATE", "COMMENT_CREATE", "COMMENT_DELETE", "COMMENT_EDIT", "CONTENT_ACCESS", "CONTENT_RECOVERY_REPORT_CREATE", "CONTENT_RECOVERY_REPORT_DELETE", "CONTENT_RECOVERY_REPORT_INITIATE", "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", "DISABLE_MULTI_FACTOR_AUTH", "DOWNLOAD", "EDIT", "EDIT_USER", "EDR_CROWDSTRIKE_ACCESS_ALLOWED_NO_CROWDSTRIKE_DEVICE", "EDR_CROWDSTRIKE_ACCESS_REVOKED", "EDR_CROWDSTRIKE_BOX_TOOLS_OUTDATED", "EDR_CROWDSTRIKE_DEVICE_DETECTED", "EDR_CROWDSTRIKE_DRIVE_OUTDATED", "EDR_CROWDSTRIKE_NO_BOX_TOOLS", "EMAIL_ALIAS_CONFIRM", "EMAIL_ALIAS_PRIMARY", "EMAIL_ALIAS_REMOVE", "EMAIL_UPLOAD_DISABLED", "EMAIL_UPLOAD_ENABLED", "ENABLE_MULTI_FACTOR_AUTH", "ENABLE_TWO_FACTOR_AUTH", "ENTERPRISE_APP_AUTHORIZATION_UPDATE", "EXTERNAL_COLLAB_SECURITY_SETTINGS", "FAILED_LOGIN", "FAVORITE", "FILE_MARKED_MALICIOUS", "FILE_REQUEST_CREATE", "FILE_REQUEST_DELETE", "FILE_REQUEST_UPDATE", "FILE_VERSION_RESTORE", "FILE_WATERMARKED_DOWNLOAD", "GROUP_ADD_ITEM", "GROUP_ADD_USER", "GROUP_ADMIN_CREATED", "GROUP_ADMIN_DELETED", "GROUP_ADMIN_PERMISSIONS_UPDATED", "GROUP_CREATION", "GROUP_DELETION", "GROUP_EDITED", "GROUP_REMOVE_ITEM", "GROUP_REMOVE_USER", "ILLEGAL_ITEM_OWNERSHIP_TRANSFER_BY_USER", "ITEM_ASSOCIATION_CREATED", "ITEM_ASSOCIATION_DELETED", "ITEM_ASSOCIATION_UPDATED", "ITEM_COPY", "ITEM_CREATE", "ITEM_DOWNLOAD", "ITEM_EMAIL_SEND", "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_CASCADE_POLICY_APPLY", "METADATA_CASCADE_POLICY_CREATE", "METADATA_INSTANCE_COPY", "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", "OAUTH2_REFRESH_TOKEN_REVOKE", "PREVIEW", "REMOVE_DEVICE_ASSOCIATION", "REMOVE_LOGIN_ACTIVITY_DEVICE", "RENAME", "RETENTION_POLICY_ASSIGNMENT_ADD", "SHARE", "SHARED_LINK_REDIRECT_OUT_OF_SHARED_CONTEXT", "SHARED_LINK_SEND", "SHARE_EXPIRATION", "SHIELD_ACCESS_POLICY_CREATED", "SHIELD_ACCESS_POLICY_DELETED", "SHIELD_ACCESS_POLICY_UPDATED", "SHIELD_ALERT", "SHIELD_DOWNLOAD_BLOCKED", "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_EXTERNAL_COLLAB_INVITE_JUSTIFIED", "SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED", "SHIELD_INFORMATION_BARRIER_DISABLED", "SHIELD_INFORMATION_BARRIER_ENABLED", "SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED", "SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED", "SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED", "SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED", "SHIELD_INFORMATION_BARRIER_PENDING", "SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED", "SHIELD_JUSTIFICATION_APPROVAL", "SHIELD_PREVIEW_BLOCKED", "SHIELD_SHARED_LINK_ACCESS_BLOCKED", "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE", "SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE", "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", "SIGN_DOCUMENT_VIEWED_BY_SIGNER", "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", "UNFAVORITE", "UNLOCK", "UNSHARE", "UPDATE_COLLABORATION_EXPIRATION", "UPDATE_SHARE_EXPIRATION", "UPLOAD", "USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE", "WATERMARK_LABEL_CREATE", "WATERMARK_LABEL_DELETE", "WORKFLOW_AUTOMATION_CREATE", "WORKFLOW_AUTOMATION_DELETE", "WORKFLOW_AUTOMATION_UPDATE" ] }, { "description": "The event type that triggered this event." } ] }, "session_id": { "description": "The session of the user that performed the action. Not all events will populate this attribute.", "type": "string", "example": "70090280850c8d2a1933c1" }, "source": { "allOf": [ { "$ref": "#/components/schemas/EventSourceResource" }, { "description": "The resource that triggered this event. For more information, check out the guide on event triggers." } ] }, "additional_details": { "description": "This object provides additional information about the event if available.\n\nThis 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.", "type": "object", "example": { "key": "value" }, "additionalProperties": {} } }, "title": "Event", "x-box-resource-id": "event", "x-box-tag": "events" }, "Events": { "description": "A list of event objects.", "type": "object", "properties": { "chunk_size": { "description": "The number of events returned in this response.", "type": "integer", "format": "int64", "example": 2 }, "next_stream_position": { "description": "The stream position of the start of the next page (chunk) of events.", "example": "1152922976252290886", "anyOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ] }, "entries": { "description": "A list of events.", "type": "array", "items": { "$ref": "#/components/schemas/Event" } } }, "title": "Events", "x-box-resource-id": "events", "x-box-tag": "events" }, "EventSource": { "description": "The source file or folder that triggered an event in the event stream.", "type": "object", "properties": { "item_type": { "description": "The type of the item that the event represents. Can be `file` or `folder`.", "type": "string", "example": "file", "enum": [ "file", "folder" ], "nullable": false }, "item_id": { "description": "The unique identifier that represents the item.", "type": "string", "example": "560284318361", "nullable": false }, "item_name": { "description": "The name of the item.", "type": "string", "example": "report.pdf", "nullable": false }, "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.", "type": "object", "properties": { "name": { "description": "The classification's name.", "type": "string", "example": "Top Secret" } } }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the root folder or the trash folder." } ], "nullable": true }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this item." }, { "nullable": false } ] } }, "required": [ "item_type", "item_id", "item_name" ], "title": "Event source", "x-box-resource-id": "event_source" }, "EventSourceResource": { "description": "The resource that triggered an event.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/EventSource" }, { "$ref": "#/components/schemas/File" }, { "$ref": "#/components/schemas/Folder" }, { "$ref": "#/components/schemas/GenericSource" }, { "$ref": "#/components/schemas/AppItemEventSource" } ], "title": "Event source resource" }, "File": { "description": "A standard representation of a file, as returned from any file API endpoints by default.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/File--Mini" }, { "properties": { "description": { "description": "The optional description of this file. If the description exceeds 255 characters, the first 255 characters are set as a file description and the rest of it is ignored.", "type": "string", "example": "Contract for Q1 renewal", "maxLength": 255, "nullable": false }, "size": { "description": "The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.", "type": "integer", "example": 629644, "nullable": false }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "The parent folders for this item.", "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" }, "nullable": false } } }, { "description": "The tree of folders that this file is contained in, starting at the root." }, { "nullable": false } ] }, "created_at": { "description": "The date and time when the file was created on Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": false }, "modified_at": { "description": "The date and time when the file was last updated on Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": false }, "trashed_at": { "description": "The time at which this file was put in the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { "description": "The time at which this file is expected to be purged from the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_created_at": { "description": "The date and time at which this file was originally created, which might be before it was uploaded to Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_modified_at": { "description": "The date and time at which this file was last updated, which might be before it was uploaded to Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this file." } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this file." }, { "nullable": false } ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this file." }, { "nullable": false } ] }, "shared_link": { "allOf": [ { "title": "Shared link", "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users.", "type": "object", "required": [ "url", "accessed", "effective_access", "effective_permission", "is_password_enabled", "download_count", "preview_count" ], "properties": { "url": { "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file can be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url` has been set for this shared link.", "type": "string", "format": "url", "example": "https://www.box.com/s/vspke7y05sb214wjokpk", "nullable": false }, "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.\n\nThis property will be `null` for folders.", "type": "string", "format": "url", "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", "nullable": true, "x-box-premium-feature": true }, "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.", "type": "string", "format": "url", "example": "https://acme.app.box.com/v/my_url/", "nullable": true }, "vanity_name": { "description": "The custom name of a shared link, as used in the `vanity_url` field.", "type": "string", "example": "my_url", "nullable": true }, "access": { "description": "The access level for this shared link.\n\n- `open` - provides access to this item to anyone with this link\n- `company` - only provides access to this item to people the same company\n- `collaborators` - only provides access to this item to people who are collaborators on this item\n\nIf 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.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ], "nullable": false }, "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.", "type": "string", "example": "company", "enum": [ "open", "company", "collaborators" ], "nullable": false }, "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.", "type": "string", "example": "can_download", "enum": [ "can_edit", "can_download", "can_preview", "no_access" ], "nullable": false }, "unshared_at": { "description": "The date and time when this link will be unshared. This field can only be set by users with paid accounts.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00", "nullable": true }, "is_password_enabled": { "description": "Defines if the shared link requires a password to access the item.", "type": "boolean", "example": true, "nullable": false }, "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.", "type": "object", "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.\n\nThis value can be set to `true` when the effective access level is set to `open` or `company`, not `collaborators`.", "type": "boolean", "example": true, "nullable": false }, "can_preview": { "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also applies to any items in the folder.", "type": "boolean", "example": true, "nullable": false }, "can_edit": { "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if the item has a type of `file`.", "type": "boolean", "example": false, "nullable": false } }, "required": [ "can_download", "can_preview", "can_edit" ] }, "download_count": { "description": "The number of times this item has been downloaded.", "type": "integer", "example": 3, "nullable": false }, "preview_count": { "description": "The number of times this item has been previewed.", "type": "integer", "example": 3, "nullable": false } } }, { "description": "The shared link for this file. This value will be `null` if no shared link has been created for this file." }, { "nullable": true } ] }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The folder that this file is located within. This value may be `null` for some folders such as the root folder or the trash folder." } ], "nullable": true }, "item_status": { "description": "Defines if this item has been deleted or not.\n\n- `active` when the item has is not in the trash\n- `trashed` when the item has been moved to the trash but not deleted\n- `deleted` when the item has been permanently deleted.", "type": "string", "example": "active", "enum": [ "active", "trashed", "deleted" ], "nullable": false } } } ], "title": "File", "x-box-resource-id": "file", "x-box-tag": "files", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier that represent a file.\n\nThe 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`.", "type": "string", "example": "12345", "nullable": false }, "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.", "type": "string", "example": "1", "nullable": true }, "type": { "description": "The value will always be `file`.", "type": "string", "example": "file", "enum": [ "file" ], "nullable": false } }, "nullable": true, "required": [ "id", "type" ], "title": "File (Base)", "x-box-resource-id": "file--base", "x-box-tag": "files", "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard", "full" ] }, "File--Full": { "description": "A full representation of a file, as can be returned from any file API endpoints by default.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/File" }, { "properties": { "version_number": { "description": "The version number of this file.", "type": "string", "example": "1" }, "comment_count": { "description": "The number of comments on this file.", "type": "integer", "example": 10 }, "permissions": { "allOf": [ { "type": "object", "description": "The permissions that the authenticated user has for a file.", "required": [ "can_annotate", "can_comment", "can_preview", "can_upload", "can_view_annotations_all", "can_view_annotations_self" ], "allOf": [ { "type": "object", "description": "The permissions that the authenticated user has for an item.", "required": [ "can_delete", "can_download", "can_invite_collaborator", "can_rename", "can_set_share_access", "can_share" ], "properties": { "can_delete": { "description": "Specifies if the current user can delete this item.", "type": "boolean", "example": true, "nullable": false }, "can_download": { "description": "Specifies if the current user can download this item.", "type": "boolean", "example": true, "nullable": false }, "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.", "type": "boolean", "example": true, "nullable": false }, "can_rename": { "description": "Specifies if the user can rename this item.", "type": "boolean", "example": true, "nullable": false }, "can_set_share_access": { "description": "Specifies if the user can change the access level of an existing shared link on this item.", "type": "boolean", "example": true, "nullable": false }, "can_share": { "description": "Specifies if the user can create a shared link for this item.", "type": "boolean", "example": true, "nullable": false } } }, { "properties": { "can_annotate": { "description": "Specifies if the user can place annotations on this file.", "type": "boolean", "example": true, "nullable": false }, "can_comment": { "description": "Specifies if the user can place comments on this file.", "type": "boolean", "example": true, "nullable": false }, "can_preview": { "description": "Specifies if the user can preview this file.", "type": "boolean", "example": true, "nullable": false }, "can_upload": { "description": "Specifies if the user can upload a new version of this file.", "type": "boolean", "example": true, "nullable": false }, "can_view_annotations_all": { "description": "Specifies if the user view all annotations placed on this file.", "type": "boolean", "example": true, "nullable": false }, "can_view_annotations_self": { "description": "Specifies if the user view annotations placed by themselves on this file.", "type": "boolean", "example": true, "nullable": false }, "can_apply_watermark": { "description": "Specifies if the user can apply a watermark to this file.", "type": "boolean", "example": true, "nullable": false } } } ] }, { "description": "Describes the permissions that the current user has for this file." }, { "nullable": false } ] }, "tags": { "allOf": [ { "type": "array", "example": [ "approved" ], "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags, modify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000 unique tags per enterprise." }, { "nullable": false } ] }, "lock": { "allOf": [ { "title": "Lock", "type": "object", "description": "The lock held on a file. A lock prevents a file from being moved, renamed, or otherwise changed by anyone else than the user who created the lock.", "properties": { "id": { "description": "The unique identifier for this lock.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `lock`.", "type": "string", "example": "lock", "enum": [ "lock" ] }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created the lock." } ] }, "created_at": { "description": "The time this lock was created at.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "expired_at": { "description": "The time this lock is to expire at, which might be in the past.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "is_download_prevented": { "description": "Whether or not the file can be downloaded while locked.", "type": "boolean", "example": true }, "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.", "type": "string", "example": "office_wopiplus", "enum": [ "gsuite", "office_wopi", "office_wopiplus", "other" ], "nullable": true } } }, { "description": "The lock held on this file. If there is no lock, this can either be `null` or have a timestamp in the past." } ], "nullable": true }, "extension": { "description": "Indicates the (optional) file extension for this file. By default, this is set to an empty string.", "type": "string", "example": "pdf" }, "is_package": { "description": "Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files.", "type": "boolean", "example": true }, "expiring_embed_link": { "allOf": [ { "title": "Expiring embed link", "type": "object", "description": "An expiring Box Embed Link.", "allOf": [ { "type": "object", "description": "The basics of an access token.", "properties": { "access_token": { "description": "The requested access token.", "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "expires_in": { "description": "The time in seconds by which this token will expire.", "type": "integer", "format": "int64", "example": 3600 }, "token_type": { "description": "The type of access token returned.", "type": "string", "example": "bearer", "enum": [ "bearer" ] }, "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.", "type": "array", "items": { "$ref": "#/components/schemas/ResourceScope" } } } }, { "properties": { "url": { "description": "The actual expiring embed URL for this file, constructed from the file ID and access tokens specified in this object.", "type": "string", "format": "url", "example": "https://cloud.app.box.com/preview/expiring_embed/..." } } } ] }, { "description": "Requesting this field creates an expiring Box Embed URL for an embedded preview session in an `iframe`.\n\nThis URL will expire after 60 seconds and the session will expire after 60 minutes.\n\nNot all file types are supported for these embed URLs. Box Embed is not optimized for mobile browsers and should not be used in web experiences designed for mobile devices. Many UI elements, like the **download** and **print** options might not show in mobile browsers." } ] }, "watermark_info": { "allOf": [ { "type": "object", "description": "Details about the watermark applied to this item.", "properties": { "is_watermarked": { "description": "Specifies if this item has a watermark applied.", "type": "boolean", "example": true, "nullable": false }, "is_watermark_inherited": { "description": "Specifies if the watermark is inherited from any parent folder in the hierarchy.", "type": "boolean", "example": false, "nullable": false }, "is_watermarked_by_access_policy": { "description": "Specifies if the watermark is enforced by an access policy.", "type": "boolean", "example": false, "nullable": false } } }, { "description": "Details about the watermark applied to this file." } ] }, "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.", "type": "boolean", "example": true }, "allowed_invitee_roles": { "description": "A list of the types of roles that user can be invited at when sharing this file.", "type": "array", "items": { "type": "string", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "example": [ "editor" ], "nullable": false }, "is_externally_owned": { "description": "Specifies if this file is owned by a user outside of the authenticated enterprise.", "type": "boolean", "example": true, "nullable": false }, "has_collaborations": { "description": "Specifies if this file has any other collaborators.", "type": "boolean", "example": true, "nullable": false }, "metadata": { "allOf": [ { "title": "Item metadata instances", "type": "object", "description": "A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`.\n\nTo access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise.\n\nThen use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID.\n\nTo request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata..`\n\nFor example, `?fields=metadata.enterprise_27335.marketingCollateral`.", "example": { "enterprise_27335": { "marketingCollateral": { "$canEdit": true, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_59449484661", "$scope": "enterprise_27335", "$template": "marketingCollateral", "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1 } } }, "additionalProperties": { "type": "object", "description": "A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`.", "example": { "marketingCollateral": { "$canEdit": true, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_59449484661", "$scope": "enterprise_27335", "$template": "marketingCollateral", "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1 } }, "additionalProperties": { "$ref": "#/components/schemas/Metadata--Full" } } }, { "description": "An object containing the metadata instances that have been attached to this file.\n\nEach metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each file. Each metadata instance is nested within an object with the `templateKey` as the key, which again itself is nested in an object with the `scope` as the key." } ] }, "expires_at": { "description": "When the file will automatically be deleted.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "representations": { "allOf": [ { "title": "Representations", "description": "A list of file representations.", "type": "object", "properties": { "entries": { "description": "A list of files.", "type": "array", "items": { "type": "object", "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.\n\nThis 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.\n\nFor paged representations, replace the `{+asset_path}` with the page to request plus the extension for the file, for example `1.pdf`.\n\nWhen requesting the download URL the following additional query params can be passed along.\n\n- `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.\n\n- `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.", "type": "string", "example": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567" } }, "type": "object" }, "info": { "description": "An object containing the URL that can be used to fetch more info on this representation.", "type": "object", "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.", "type": "string", "example": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048" } } }, "properties": { "description": "An object containing the size and type of this presentation.", "type": "object", "properties": { "dimensions": { "type": "string", "format": "x", "example": "2048x2048", "description": "The width by height size of this representation in pixels." }, "paged": { "type": "string", "example": "true", "description": "Indicates if the representation is build up out of multiple pages." }, "thumb": { "type": "string", "example": "true", "description": "Indicates if the representation can be used as a thumbnail of the file." } } }, "representation": { "description": "Indicates the file type of the returned representation.", "type": "string", "example": "png" }, "status": { "description": "An object containing the status of this representation.", "type": "object", "properties": { "state": { "description": "The status of the representation.\n\n- `success` defines the representation as ready to be viewed.\n- `viewable` defines a video to be ready for viewing.\n- `pending` defines the representation as to be generated. Retry this endpoint to re-check the status.\n- `none` defines that the representation will be created when requested. Request the URL defined in the `info` object to trigger this generation.", "type": "string", "example": "success", "enum": [ "success", "viewable", "pending", "none" ] } } } } } } } }, { "description": "A list of representations for a file that can be used to display a placeholder of the file in your application. By default this returns all representations and we recommend using the `x-rep-hints` header to further customize the desired representations." } ] }, "classification": { "allOf": [ { "type": "object", "description": "The classification applied to an item.", "properties": { "name": { "description": "The name of the classification.", "type": "string", "example": "Top Secret" }, "definition": { "description": "An explanation of the meaning of this classification.", "type": "string", "example": "Content that should not be shared outside the company." }, "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.", "type": "string", "example": "#FF0000" } } }, { "description": "Details about the classification applied to this file." }, { "nullable": true } ] }, "uploader_display_name": { "allOf": [ { "title": "Uploader display name", "type": "string", "example": "Ellis Wiggins", "nullable": false, "description": "The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload.\n\nIf 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`.\n\nIn all other anonymous cases where no email was provided this field will default to a value of `Someone`." } ] }, "disposition_at": { "description": "The retention expiration timestamp for the given file.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "shared_link_permission_options": { "description": "A list of the types of roles that user can be invited at when sharing this file.", "type": "array", "items": { "type": "string", "enum": [ "can_preview", "can_download", "can_edit" ] }, "example": [ "can_preview" ], "nullable": true }, "is_associated_with_app_item": { "description": "This field will return true if the file or any ancestor of the file is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the file.", "type": "boolean", "example": true, "nullable": false }, "collections": { "description": "The collections that this file belongs to.\n\nFor more information, see the [collections guide](/guides/collections).", "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "is_download_available": { "description": "Whether the file's binary content is eligible to be downloaded.\n\nThis is a content-level flag and does not reflect whether the current user is authorized to download the file. Use `permissions.can_download`, when available, for that.", "type": "boolean", "example": true }, "download_url": { "description": "A pre-authorized, expiring URL for directly downloading the file's content. Requires authentication and is valid only for the current session.\n\nThis field is only returned for files, not folders or web links.", "type": "string", "format": "url", "example": "https://dl.boxcloud.com/d/1/example_token/download" }, "authenticated_download_url": { "description": "A stable API URL for the file content endpoint, `/2.0/files/{id}/content`. Unlike `download_url`, authorization is evaluated when the URL is requested with a valid access token.\n\nThis field is only returned for files, not folders or web links.", "type": "string", "format": "url", "example": "https://api.box.com/2.0/files/12345/content" }, "allowed_shared_link_access_levels": { "description": "The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this file.\n\nThe list depends on item policy and user authorization, so it may be narrower than the levels available to the owner. An empty array means no access level is available to this user.", "type": "array", "items": { "title": "Shared link access level", "type": "string", "description": "The access level for a shared link.", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "example": [ "open" ], "nullable": false } } } ], "title": "File (Full)", "x-box-resource-id": "file--full", "x-box-tag": "files", "x-box-variant": "full" }, "File--Mini": { "description": "A mini representation of a file, used when nested under another resource.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/File--Base" }, { "properties": { "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "name": { "description": "The name of the file.", "type": "string", "example": "Contract.pdf" }, "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.", "type": "string", "format": "digest", "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", "nullable": false }, "file_version": { "allOf": [ { "$ref": "#/components/schemas/FileVersion--Mini" }, { "description": "The information about the current version of the file." } ] } } } ], "nullable": true, "title": "File (Mini)", "x-box-resource-id": "file--mini", "x-box-tag": "files", "x-box-variant": "mini" }, "FileConflict": { "description": "A representation of a file that is used to show.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/File--Mini" }, { "properties": { "sha1": { "description": "The SHA1 hash of the file.", "type": "string", "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37" }, "file_version": { "$ref": "#/components/schemas/FileVersion--Mini" } } } ], "title": "File (Conflict)", "x-box-resource-id": "file_conflict", "x-box-tag": null }, "FileRequest": { "description": "A standard representation of a file request, as returned from any file request API endpoints by default.", "type": "object", "properties": { "id": { "description": "The unique identifier for this file request.", "type": "string", "example": "42037322", "readOnly": true }, "type": { "description": "The value will always be `file_request`.", "type": "string", "example": "file_request", "enum": [ "file_request" ], "readOnly": true }, "title": { "description": "The title of file request. This is shown in the Box UI to users uploading files.\n\nThis defaults to title of the file request that was copied to create this file request.", "type": "string", "example": "Please upload documents" }, "description": { "description": "The optional description of this file request. This is shown in the Box UI to users uploading files.\n\nThis defaults to description of the file request that was copied to create this file request.", "type": "string", "example": "Following documents are requested for your process", "nullable": true }, "status": { "description": "The status of the file request. This defaults to `active`.\n\nWhen 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.\n\nThis defaults to status of file request that was copied to create this file request.", "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "is_email_required": { "description": "Whether a file request submitter is required to provide their email address.\n\nWhen this setting is set to true, the Box UI will show an email field on the file request form.\n\nThis defaults to setting of file request that was copied to create this file request.", "type": "boolean", "example": true }, "is_description_required": { "description": "Whether a file request submitter is required to provide a description of the files they are submitting.\n\nWhen this setting is set to true, the Box UI will show a description field on the file request form.\n\nThis defaults to setting of file request that was copied to create this file request.", "type": "boolean", "example": true }, "expires_at": { "description": "The date after which a file request will no longer accept new submissions.\n\nAfter this date, the `status` will automatically be set to `inactive`.", "type": "string", "format": "date-time", "example": "2020-09-28T10:53:43-08:00" }, "folder": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The folder that this file request is associated with.\n\nFiles submitted through the file request form will be uploaded to this folder." } ], "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.", "type": "string", "example": "/f/19e57f40ace247278a8e3d336678c64a", "readOnly": true }, "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.", "type": "string", "example": "1", "nullable": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this file request." } ] }, "created_at": { "description": "The date and time when the file request was created.", "type": "string", "format": "date-time", "example": "2020-09-28T10:53:43-08:00", "nullable": false }, "updated_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this file request." }, { "nullable": false } ] }, "updated_at": { "description": "The date and time when the file request was last updated.", "type": "string", "format": "date-time", "example": "2020-09-28T10:53:43-08:00", "nullable": false } }, "required": [ "id", "type", "folder", "created_at", "updated_at" ], "title": "File Request", "x-box-resource-id": "file_request", "x-box-tag": "file_requests" }, "FileRequestCopyRequest": { "description": "The request body to copy a file request.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileRequestUpdateRequest" }, { "properties": { "folder": { "description": "The folder to associate the new file request to.", "type": "object", "properties": { "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { "description": "The ID of the folder to associate the new file request to.", "type": "string", "example": "42037322" } }, "required": [ "id" ] } } } ], "required": [ "folder" ], "title": "File Request (Copy)" }, "FileRequestUpdateRequest": { "description": "The request body to update a file request.", "type": "object", "properties": { "title": { "description": "An optional new title for the file request. This can be used to change the title of the file request.\n\nThis will default to the value on the existing file request.", "type": "string", "example": "Please upload required documents" }, "description": { "description": "An optional new description for the file request. This can be used to change the description of the file request.\n\nThis will default to the value on the existing file request.", "type": "string", "example": "Please upload required documents" }, "status": { "description": "An optional new status of the file request.\n\nWhen 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.\n\nThis will default to the value on the existing file request.", "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "is_email_required": { "description": "Whether a file request submitter is required to provide their email address.\n\nWhen this setting is set to true, the Box UI will show an email field on the file request form.\n\nThis will default to the value on the existing file request.", "type": "boolean", "example": true }, "is_description_required": { "description": "Whether a file request submitter is required to provide a description of the files they are submitting.\n\nWhen this setting is set to true, the Box UI will show a description field on the file request form.\n\nThis will default to the value on the existing file request.", "type": "boolean", "example": true }, "expires_at": { "description": "The date after which a file request will no longer accept new submissions.\n\nAfter this date, the `status` will automatically be set to `inactive`.\n\nThis will default to the value on the existing file request.", "type": "string", "format": "date-time", "example": "2020-09-28T10:53:43-08:00" } }, "title": "File Request (Update)" }, "Files": { "description": "A list of files.", "type": "object", "properties": { "total_count": { "description": "The number of files.", "type": "integer", "format": "int64", "example": 1 }, "entries": { "description": "A list of files.", "type": "array", "items": { "$ref": "#/components/schemas/File--Full" } } }, "title": "Files", "x-box-resource-id": "files", "x-box-tag": "files" }, "FilesOnHold": { "description": "A list of files on hold for legal policy assignment.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of files.", "type": "array", "items": { "$ref": "#/components/schemas/File--Mini" } } } } ], "title": "Files on hold", "x-box-resource-id": "files_on_hold", "x-box-tag": "legal_hold_policy_assignments" }, "FilesUnderRetention": { "description": "A list of files under retention.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of files.", "type": "array", "items": { "$ref": "#/components/schemas/File--Mini" } } } } ], "title": "Files under retention", "x-box-resource-id": "files_under_retention", "x-box-tag": "retention_policy_assignments" }, "FileVersion": { "description": "A standard representation of a file version.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileVersion--Mini" }, { "properties": { "name": { "description": "The name of the file version.", "type": "string", "example": "tigers.jpeg" }, "size": { "description": "Size of the file version in bytes.", "type": "integer", "format": "int64", "example": 629644 }, "created_at": { "description": "When the file version object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the file version object was last updated.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last updated the file version." } ] }, "trashed_at": { "description": "When the file version object was trashed.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "trashed_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who trashed the file version." } ] }, "restored_at": { "description": "When the file version was restored from the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "restored_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who restored the file version from the trash." } ] }, "purged_at": { "description": "When the file version object will be permanently deleted.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "uploader_display_name": { "allOf": [ { "title": "Uploader display name", "type": "string", "example": "Ellis Wiggins", "nullable": false, "description": "The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload.\n\nIf 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`.\n\nIn all other anonymous cases where no email was provided this field will default to a value of `Someone`." } ] } } } ], "title": "File version", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier that represent a file version.", "type": "string", "example": "12345", "nullable": false }, "type": { "description": "The value will always be `file_version`.", "type": "string", "example": "file_version", "enum": [ "file_version" ], "nullable": false } }, "required": [ "id", "type" ], "title": "File version (Base)", "x-box-resource-id": "file_version--base", "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard", "full" ] }, "FileVersion--Full": { "description": "A full representation of a file version, as can be returned from any file version API endpoints by default.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileVersion" }, { "properties": { "version_number": { "description": "The version number of this file version.", "type": "string", "example": "1" } } } ], "title": "File version (Full)", "x-box-resource-id": "file_version--full", "x-box-variant": "full" }, "FileVersion--Mini": { "description": "A mini representation of a file version, used when nested within another resource.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/FileVersion--Base" }, { "properties": { "sha1": { "description": "The SHA1 hash of this version of the file.", "type": "string", "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } } } ], "title": "File version (Mini)", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for this file version legal hold.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `file_version_legal_hold`.", "type": "string", "example": "file_version_legal_hold", "enum": [ "file_version_legal_hold" ] }, "file_version": { "allOf": [ { "$ref": "#/components/schemas/FileVersion--Mini" }, { "description": "The file version that is held." } ] }, "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." } ] }, "legal_hold_policy_assignments": { "description": "List of assignments contributing to this Hold.", "type": "array", "items": { "$ref": "#/components/schemas/LegalHoldPolicyAssignment" } }, "deleted_at": { "description": "Time that this File-Version-Legal-Hold was deleted.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "title": "File version legal hold", "x-box-resource-id": "file_version_legal_hold", "x-box-tag": "file_version_legal_holds" }, "FileVersionLegalHolds": { "description": "A list of file versions with legal holds.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of file version legal holds.", "type": "array", "items": { "$ref": "#/components/schemas/FileVersionLegalHold" } } } } ], "title": "File version legal holds", "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 in your application management console.\n\n**Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", "type": "object", "properties": { "id": { "description": "The unique identifier for this file version retention.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `file_version_retention`.", "type": "string", "example": "file_version_retention", "enum": [ "file_version_retention" ] }, "file_version": { "allOf": [ { "$ref": "#/components/schemas/FileVersion--Mini" }, { "description": "The file version this file version retention was applied to." } ] }, "file": { "allOf": [ { "$ref": "#/components/schemas/File--Mini" }, { "description": "The file this file version retention was applied to." } ] }, "applied_at": { "description": "When this file version retention object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "disposition_at": { "description": "When the retention expires on this file version retention.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "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", "x-box-resource-id": "file_version_retention", "x-box-tag": "file_version_retentions" }, "FileVersionRetentions": { "description": "A list of file version retentions.\n\n**Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of file version retentions.", "type": "array", "items": { "$ref": "#/components/schemas/FileVersionRetention" } } } } ], "title": "File version retentions", "x-box-resource-id": "file_version_retentions", "x-box-tag": "file_version_retentions" }, "FileVersions": { "description": "A list of file versions.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "A list of file versions.", "type": "array", "items": { "$ref": "#/components/schemas/FileVersion--Full" } } } } ], "title": "File versions", "x-box-resource-id": "file_versions", "x-box-tag": "file_versions" }, "FileVersionsOnHold": { "description": "A list of files on hold for legal policy assignment.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of file versions on hold.", "type": "array", "items": { "$ref": "#/components/schemas/FileVersion" } } } } ], "title": "File versions on hold", "x-box-resource-id": "file_versions_on_hold", "x-box-tag": "legal_hold_policy_assignments" }, "Folder": { "description": "A standard representation of a folder, as returned from any folder API endpoints by default.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "properties": { "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "description": { "allOf": [ { "type": "string", "description": "The optional description of this folder.", "maxLength": 256, "example": "Legal contracts for the new ACME deal", "nullable": false }, { "nullable": false } ] }, "size": { "description": "The folder size in bytes.\n\nBe careful parsing this integer as its value can get very large.", "type": "integer", "format": "int64", "example": 629644, "nullable": false }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "The parent folders for this item.", "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" }, "nullable": false } } }, { "description": "The tree of folders that this folder is contained in, starting at the root." }, { "nullable": false } ] }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this folder." }, { "nullable": false } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this folder." }, { "nullable": false } ] }, "trashed_at": { "description": "The time at which this folder was put in the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { "description": "The time at which this folder is expected to be purged from the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_created_at": { "description": "The date and time at which this folder was originally created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_modified_at": { "description": "The date and time at which this folder was last updated.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this folder." }, { "nullable": false } ] }, "shared_link": { "allOf": [ { "title": "Shared link", "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users.", "type": "object", "required": [ "url", "accessed", "effective_access", "effective_permission", "is_password_enabled", "download_count", "preview_count" ], "properties": { "url": { "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file can be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url` has been set for this shared link.", "type": "string", "format": "url", "example": "https://www.box.com/s/vspke7y05sb214wjokpk", "nullable": false }, "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.\n\nThis property will be `null` for folders.", "type": "string", "format": "url", "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", "nullable": true, "x-box-premium-feature": true }, "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.", "type": "string", "format": "url", "example": "https://acme.app.box.com/v/my_url/", "nullable": true }, "vanity_name": { "description": "The custom name of a shared link, as used in the `vanity_url` field.", "type": "string", "example": "my_url", "nullable": true }, "access": { "description": "The access level for this shared link.\n\n- `open` - provides access to this item to anyone with this link\n- `company` - only provides access to this item to people the same company\n- `collaborators` - only provides access to this item to people who are collaborators on this item\n\nIf 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.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ], "nullable": false }, "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.", "type": "string", "example": "company", "enum": [ "open", "company", "collaborators" ], "nullable": false }, "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.", "type": "string", "example": "can_download", "enum": [ "can_edit", "can_download", "can_preview", "no_access" ], "nullable": false }, "unshared_at": { "description": "The date and time when this link will be unshared. This field can only be set by users with paid accounts.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00", "nullable": true }, "is_password_enabled": { "description": "Defines if the shared link requires a password to access the item.", "type": "boolean", "example": true, "nullable": false }, "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.", "type": "object", "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.\n\nThis value can be set to `true` when the effective access level is set to `open` or `company`, not `collaborators`.", "type": "boolean", "example": true, "nullable": false }, "can_preview": { "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also applies to any items in the folder.", "type": "boolean", "example": true, "nullable": false }, "can_edit": { "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if the item has a type of `file`.", "type": "boolean", "example": false, "nullable": false } }, "required": [ "can_download", "can_preview", "can_edit" ] }, "download_count": { "description": "The number of times this item has been downloaded.", "type": "integer", "example": 3, "nullable": false }, "preview_count": { "description": "The number of times this item has been previewed.", "type": "integer", "example": 3, "nullable": false } } }, { "description": "The shared link for this folder. This will be `null` if no shared link has been created for this folder." } ], "nullable": true }, "folder_upload_email": { "description": "The `folder_upload_email` parameter is not `null` if one of the following options is **true**:\n\n- The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted.\n\n- The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked).\n\nIf the conditions are not met, the parameter will have the following value: `folder_upload_email: null`.", "type": "object", "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.\n\nTo create an email address, set this property either when creating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email addresses for collaborators will be accepted. This includes any email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email address.", "type": "string", "example": "open", "enum": [ "open", "collaborators" ], "nullable": false }, "email": { "description": "The optional upload email address for this folder.", "type": "string", "format": "email", "example": "upload.Contracts.asd7asd@u.box.com", "nullable": false } } }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the root folder or the trash folder." } ], "nullable": true }, "item_status": { "description": "Defines if this item has been deleted or not.\n\n- `active` when the item has is not in the trash\n- `trashed` when the item has been moved to the trash but not deleted\n- `deleted` when the item has been permanently deleted.", "type": "string", "example": "active", "enum": [ "active", "trashed", "deleted" ], "nullable": false }, "item_collection": { "allOf": [ { "$ref": "#/components/schemas/Items" }, { "description": "A page of the items that are in the folder.\n\nThis field can only be requested when querying a folder's information, not when querying a folder's items." }, { "nullable": false } ] } } } ], "title": "Folder", "x-box-resource-id": "folder", "x-box-tag": "folders", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier that represent a folder.\n\nThe 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`.", "type": "string", "example": "12345", "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.", "type": "string", "example": "1", "nullable": true }, "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ], "nullable": false } }, "required": [ "id", "type" ], "title": "Folder (Base)", "x-box-resource-id": "folder--base", "x-box-tag": "folders", "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard", "full" ] }, "Folder--Full": { "description": "A full representation of a folder, as can be returned from any folder API endpoints by default.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Folder" }, { "properties": { "sync_state": { "allOf": [ { "type": "string", "example": "synced", "nullable": false, "description": "Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.", "enum": [ "synced", "not_synced", "partially_synced" ] } ] }, "has_collaborations": { "description": "Specifies if this folder has any other collaborators.", "type": "boolean", "example": true, "nullable": false }, "permissions": { "allOf": [ { "type": "object", "description": "The permissions that the authenticated user has for a folder.", "required": [ "can_upload" ], "allOf": [ { "type": "object", "description": "The permissions that the authenticated user has for an item.", "required": [ "can_delete", "can_download", "can_invite_collaborator", "can_rename", "can_set_share_access", "can_share" ], "properties": { "can_delete": { "description": "Specifies if the current user can delete this item.", "type": "boolean", "example": true, "nullable": false }, "can_download": { "description": "Specifies if the current user can download this item.", "type": "boolean", "example": true, "nullable": false }, "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.", "type": "boolean", "example": true, "nullable": false }, "can_rename": { "description": "Specifies if the user can rename this item.", "type": "boolean", "example": true, "nullable": false }, "can_set_share_access": { "description": "Specifies if the user can change the access level of an existing shared link on this item.", "type": "boolean", "example": true, "nullable": false }, "can_share": { "description": "Specifies if the user can create a shared link for this item.", "type": "boolean", "example": true, "nullable": false } } }, { "properties": { "can_upload": { "description": "Specifies if the user can upload into this folder.", "type": "boolean", "example": true, "nullable": false }, "can_apply_watermark": { "description": "Specifies if the user can apply a watermark to this folder and its contents.", "type": "boolean", "example": true, "nullable": false } } } ] }, { "description": "Describes the permissions that the current user has for this folder." }, { "nullable": false } ] }, "tags": { "allOf": [ { "type": "array", "example": [ "approved" ], "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags, modify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000 unique tags per enterprise." }, { "nullable": false } ] }, "can_non_owners_invite": { "allOf": [ { "type": "boolean", "example": true, "description": "Specifies if users who are not the owner of the folder can invite new collaborators to the folder." }, { "nullable": false } ] }, "is_externally_owned": { "description": "Specifies if this folder is owned by a user outside of the authenticated enterprise.", "type": "boolean", "example": true, "nullable": false }, "metadata": { "allOf": [ { "title": "Item metadata instances", "type": "object", "description": "A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`.\n\nTo access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise.\n\nThen use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID.\n\nTo request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata..`\n\nFor example, `?fields=metadata.enterprise_27335.marketingCollateral`.", "example": { "enterprise_27335": { "marketingCollateral": { "$canEdit": true, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_59449484661", "$scope": "enterprise_27335", "$template": "marketingCollateral", "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1 } } }, "additionalProperties": { "type": "object", "description": "A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`.", "example": { "marketingCollateral": { "$canEdit": true, "$id": "01234500-12f1-1234-aa12-b1d234cb567e", "$parent": "folder_59449484661", "$scope": "enterprise_27335", "$template": "marketingCollateral", "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0", "$typeVersion": 2, "$version": 1 } }, "additionalProperties": { "$ref": "#/components/schemas/Metadata--Full" } } }, { "description": "An object containing the metadata instances that have been attached to this folder.\n\nEach metadata instance is uniquely identified by its `scope` and `templateKey`. There can only be one instance of any metadata template attached to each folder. Each metadata instance is nested within an object with the `templateKey` as the key, which again itself is nested in an object with the `scope` as the key." } ] }, "is_collaboration_restricted_to_enterprise": { "allOf": [ { "type": "boolean", "example": true, "description": "Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations." }, { "nullable": false } ] }, "allowed_shared_link_access_levels": { "description": "The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this folder.\n\nThe list depends on item policy and user authorization. For some folders, like the root folder, this is always empty as sharing is not allowed at that level.", "type": "array", "items": { "title": "Shared link access level", "type": "string", "description": "The access level for a shared link.", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "example": [ "open" ], "nullable": false }, "allowed_invitee_roles": { "description": "A list of the types of roles that user can be invited at when sharing this folder.", "type": "array", "items": { "type": "string", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "example": [ "editor" ], "nullable": false }, "watermark_info": { "allOf": [ { "type": "object", "description": "Details about the watermark applied to this item.", "properties": { "is_watermarked": { "description": "Specifies if this item has a watermark applied.", "type": "boolean", "example": true, "nullable": false }, "is_watermark_inherited": { "description": "Specifies if the watermark is inherited from any parent folder in the hierarchy.", "type": "boolean", "example": false, "nullable": false }, "is_watermarked_by_access_policy": { "description": "Specifies if the watermark is enforced by an access policy.", "type": "boolean", "example": false, "nullable": false } } }, { "description": "Details about the watermark applied to this folder." }, { "nullable": false } ] }, "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.", "type": "boolean", "example": true }, "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.\n\nIt also restricts non-owners from inviting new collaborators.", "type": "boolean", "example": true }, "classification": { "allOf": [ { "type": "object", "description": "The classification applied to an item.", "properties": { "name": { "description": "The name of the classification.", "type": "string", "example": "Top Secret" }, "definition": { "description": "An explanation of the meaning of this classification.", "type": "string", "example": "Content that should not be shared outside the company." }, "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.", "type": "string", "example": "#FF0000" } } }, { "description": "Details about the classification applied to this folder." }, { "nullable": true } ] }, "is_associated_with_app_item": { "description": "This field will return true if the folder or any ancestor of the folder is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the folder.", "type": "boolean", "example": true, "nullable": false }, "collections": { "description": "The collections that this folder belongs to.\n\nFor more information, see the [collections guide](/guides/collections).", "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } ], "title": "Folder (Full)", "x-box-resource-id": "folder--full", "x-box-tag": "folders", "x-box-variant": "full" }, "Folder--Mini": { "description": "A mini representation of a file version, used when nested under another resource.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Folder--Base" }, { "properties": { "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "name": { "description": "The name of the folder.", "type": "string", "example": "Contracts", "nullable": false } } } ], "title": "Folder (Mini)", "x-box-resource-id": "folder--mini", "x-box-tag": "folders", "x-box-variant": "mini" }, "FolderLock": { "description": "Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.", "type": "object", "properties": { "folder": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The folder that the lock applies to." } ] }, "id": { "description": "The unique identifier for this folder lock.", "type": "string", "example": "12345678" }, "type": { "description": "The object type, always `folder_lock`.", "type": "string", "example": "folder_lock" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user or group that created the lock." } ] }, "created_at": { "description": "When the folder lock object was created.", "type": "string", "format": "date-time", "example": "2020-09-14T23:12:53Z" }, "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`.", "type": "object", "properties": { "move": { "description": "Whether moving the folder is restricted.", "type": "boolean", "example": true, "nullable": false }, "delete": { "description": "Whether deleting the folder is restricted.", "example": true, "nullable": false, "type": "boolean" } }, "required": [ "move", "delete" ] }, "lock_type": { "description": "The lock type, always `freeze`.", "type": "string", "example": "freeze" } }, "title": "Folder Lock", "x-box-resource-id": "folder_lock", "x-box-tag": "folder_locks" }, "FolderLocks": { "description": "A list of folder locks.", "type": "object", "properties": { "entries": { "description": "A list of folder locks.", "type": "array", "items": { "$ref": "#/components/schemas/FolderLock" } }, "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.", "type": "string", "example": "1000" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } }, "title": "Folder Locks", "x-box-resource-id": "folder_locks", "x-box-tag": "folder_locks" }, "FolderReference": { "description": "Folder reference.", "type": "object", "properties": { "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ], "nullable": false }, "id": { "description": "ID of the folder.", "type": "string", "example": "42037322" } }, "required": [ "type", "id" ], "title": "Folder reference" }, "GenericSource": { "description": "A generic event source type.", "type": "object", "additionalProperties": { "allOf": [ {}, { "description": "A definition of a generic event source object. The set of parameters depends on the object type. For example, a Box Shield event source would have the following set of parameters:\n\n````yaml\n{\n\"barrier_id\": 123456,\n\"barrier_status\": \"ENABLED\",\n\"barrier_segments\": [\n {\n \"name\": \"8\",\n \"member_count\": 1\n },\n {\n \"name\": \"9\",\n \"member_count\": 1\n }\n ]\n}\n```.\n````" } ] }, "title": "Generic source", "x-box-resource-id": "generic_source" }, "Group": { "description": "A standard representation of a group, as returned from any group API endpoints by default.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group--Mini" }, { "properties": { "created_at": { "description": "When the group object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the group object was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } } } ], "title": "Group", "x-box-resource-id": "group", "x-box-tag": "groups", "x-box-variant": "standard" }, "Group--Base": { "description": "A base representation of a group.", "type": "object", "properties": { "id": { "description": "The unique identifier for this object.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `group`.", "type": "string", "example": "group", "enum": [ "group" ] } }, "required": [ "id", "type" ], "title": "Group (Base)", "x-box-resource-id": "group--base", "x-box-tag": "groups", "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard", "full" ] }, "Group--Full": { "description": "Groups contain a set of users, and can be used in place of users in some operations, such as collaborations.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group" }, { "properties": { "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.", "type": "string", "example": "Active Directory", "maxLength": 255 }, "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.", "type": "string", "example": "AD:123456" }, "description": { "description": "Human readable description of the group.", "type": "string", "example": "Support Group - as imported from Active Directory", "maxLength": 255 }, "invitability_level": { "description": "Specifies who can invite the group to collaborate on items.\n\nWhen set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group.\n\nWhen set to `admins_and_members` all the admins listed above and group members can invite the group.\n\nWhen set to `all_managed_users` all managed users in the enterprise can invite the group.", "type": "string", "example": "admins_only", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "member_viewability_level": { "description": "Specifies who can view the members of the group (Get Memberships for Group).\n\n- `admins_only` - the enterprise admin, co-admins, group's group admin.\n- `admins_and_members` - all admins and group members.\n- `all_managed_users` - all managed users in the enterprise.", "type": "string", "example": "admins_only", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "permissions": { "allOf": [ { "type": "object", "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.", "type": "boolean", "example": true } } }, { "description": "Describes the permissions that the current user has for this group." } ] } } } ], "title": "Group (Full)", "x-box-resource-id": "group--full", "x-box-tag": "groups", "x-box-variant": "full" }, "Group--Mini": { "description": "Mini representation of a group, including id and name of group.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Group--Base" }, { "properties": { "name": { "description": "The name of the group.", "type": "string", "example": "Support" }, "group_type": { "description": "The type of the group.", "type": "string", "example": "managed_group", "enum": [ "managed_group", "all_users_group" ] } } } ], "title": "Group (Mini)", "x-box-resource-id": "group--mini", "x-box-tag": "groups", "x-box-variant": "mini" }, "GroupMembership": { "description": "Membership is used to signify that a user is part of a group.", "type": "object", "properties": { "id": { "description": "The unique identifier for this group membership.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `group_membership`.", "type": "string", "example": "group_membership", "enum": [ "group_membership" ] }, "user": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user that the membership applies to." } ] }, "group": { "allOf": [ { "$ref": "#/components/schemas/Group--Mini" }, { "description": "The group that the membership applies to." } ] }, "role": { "description": "The role of the user in the group.", "type": "string", "example": "member", "enum": [ "member", "admin" ] }, "created_at": { "description": "The time this membership was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "The time this membership was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "title": "Group membership", "x-box-resource-id": "group_membership", "x-box-tag": "memberships" }, "GroupMemberships": { "description": "A list of group memberships.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "A list of group memberships.", "type": "array", "items": { "$ref": "#/components/schemas/GroupMembership" } } } } ], "title": "Group memberships", "x-box-resource-id": "group_memberships", "x-box-tag": "memberships" }, "Groups": { "description": "A list of groups.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "A list of groups.", "type": "array", "items": { "$ref": "#/components/schemas/Group--Full" } } } } ], "title": "Groups", "x-box-resource-id": "groups", "x-box-tag": "groups" }, "IntegrationMapping": { "description": "A Slack specific representation of an integration mapping object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingBase" }, { "properties": { "integration_type": { "description": "Identifies the Box partner app, with which the mapping is associated. Currently only supports Slack. (part of the composite key together with `id`).", "type": "string", "example": "slack", "enum": [ "slack" ] }, "is_manually_created": { "description": "Identifies whether the mapping has been manually set (as opposed to being automatically created).", "type": "boolean", "example": true }, "options": { "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingSlackOptions" } ] }, "created_by": { "description": "An object representing the user who created the integration mapping.", "allOf": [ { "$ref": "#/components/schemas/UserIntegrationMappings" } ] }, "modified_by": { "description": "The user who last modified the integration mapping.", "allOf": [ { "$ref": "#/components/schemas/UserIntegrationMappings" } ] }, "partner_item": { "description": "Mapped item object for Slack.", "example": { "id": "C12378991223", "type": "channel", "slack_org_id": "E1234567" }, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" } ] }, "box_item": { "description": "The Box folder, to which the object from the partner app domain (referenced in `partner_item_id`) is mapped.", "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" } ] }, "created_at": { "description": "When the integration mapping object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the integration mapping object was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } } } ], "required": [ "partner_item", "box_item" ], "title": "Integration mapping Slack", "x-box-resource-id": "integration_mapping_slack", "x-box-tag": "integration_mappings" }, "IntegrationMappingBase": { "description": "A base representation of an integration mapping object.", "type": "object", "properties": { "id": { "description": "A unique identifier of a folder mapping (part of a composite key together with `integration_type`).", "type": "string", "example": "12345" }, "type": { "description": "Mapping type.", "type": "string", "example": "integration_mapping", "enum": [ "integration_mapping" ] } }, "required": [ "id", "type" ], "title": "Integration mapping" }, "IntegrationMappingBoxItemSlack": { "description": "The schema for an integration mapping Box item object for type Slack.", "type": "object", "properties": { "type": { "description": "Type of the mapped item referenced in `id`.", "type": "string", "example": "folder", "enum": [ "folder" ], "nullable": false }, "id": { "description": "ID of the mapped item (of type referenced in `type`).", "type": "string", "example": "1234567891", "nullable": false } }, "required": [ "id", "type" ], "title": "Integration mapping Box item schema for type Slack" }, "IntegrationMappingPartnerItemSlack": { "description": "The schema for an integration mapping mapped item object for type Slack.\n\nDepending if Box for Slack is installed at the org or workspace level, provide **either** `slack_org_id` **or** `slack_workspace_id`. Do not use both parameters at the same time.", "type": "object", "properties": { "type": { "description": "Type of the mapped item referenced in `id`.", "type": "string", "example": "channel", "enum": [ "channel" ], "nullable": false }, "id": { "description": "ID of the mapped item (of type referenced in `type`).", "type": "string", "example": "C12378991223", "nullable": false }, "slack_workspace_id": { "description": "ID of the Slack workspace with which the item is associated. Use this parameter if Box for Slack is installed at a workspace level. Do not use `slack_org_id` at the same time.", "type": "string", "example": "T12352314", "nullable": true }, "slack_org_id": { "description": "ID of the Slack org with which the item is associated. Use this parameter if Box for Slack is installed at the org level. Do not use `slack_workspace_id` at the same time.", "type": "string", "example": "E1234567", "nullable": true } }, "required": [ "id", "type" ], "title": "Integration mapping mapped item schema for type Slack" }, "IntegrationMappingPartnerItemTeams": { "description": "The schema for an integration mapping mapped item object for type Teams.", "type": "object", "properties": { "type": { "description": "Type of the mapped item referenced in `id`.", "type": "string", "example": "channel", "enum": [ "channel", "team" ] }, "id": { "description": "ID of the mapped item (of type referenced in `type`).", "type": "string", "example": "19%ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2" }, "tenant_id": { "description": "ID of the tenant that is registered with Microsoft Teams.", "type": "string", "example": "abcd-defg-1235-7890" } }, "required": [ "id", "type", "tenant_id" ], "title": "Integration mapping mapped item schema for type Teams" }, "IntegrationMappingPartnerItemTeamsCreateRequest": { "description": "The schema for an integration mapping mapped item object for type Teams.", "type": "object", "properties": { "type": { "description": "Type of the mapped item referenced in `id`.", "type": "string", "example": "channel", "enum": [ "channel", "team" ] }, "id": { "description": "ID of the mapped item (of type referenced in `type`).", "type": "string", "example": "19%ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2" }, "tenant_id": { "description": "ID of the tenant that is registered with Microsoft Teams.", "type": "string", "example": "abcd-defg-1235-7890" }, "team_id": { "description": "ID of the team that is registered with Microsoft Teams.", "type": "string", "example": "hjgjgjg-bhhj-564a-b643-hghgj685u" } }, "required": [ "id", "type", "tenant_id", "team_id" ], "title": "Integration mapping mapped item schema for type Teams" }, "IntegrationMappings": { "description": "A list of integration mapping objects.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } }, { "properties": { "entries": { "description": "A list of integration mappings.", "type": "array", "items": { "$ref": "#/components/schemas/IntegrationMapping" } } } } ], "title": "Integration mappings Slack", "x-box-resource-id": "integration_mappings_slack", "x-box-tag": "integration_mappings" }, "IntegrationMappingSlackCreateRequest": { "description": "A request to create a Slack Integration Mapping object.", "type": "object", "properties": { "partner_item": { "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingPartnerItemSlack" } ] }, "box_item": { "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingBoxItemSlack" } ] }, "options": { "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingSlackOptions" } ] } }, "required": [ "partner_item", "box_item" ], "title": "Create Slack integration mapping request", "x-box-resource-id": "integration_mapping_slack_create_request" }, "IntegrationMappingSlackOptions": { "description": "The schema for an integration mapping options object for Slack type.", "type": "object", "properties": { "is_access_management_disabled": { "description": "Indicates whether or not channel member access to the underlying box item should be automatically managed. Depending on type of channel, access is managed through creating collaborations or shared links.", "type": "boolean", "example": true } }, "title": "Integration mapping options for type Slack" }, "IntegrationMappingsTeams": { "description": "A list of integration mapping objects.", "type": "object", "allOf": [ { "properties": { "entries": { "description": "A list of integration mappings.", "type": "array", "items": { "$ref": "#/components/schemas/IntegrationMappingTeams" } } } } ], "title": "Integration mappings Teams", "x-box-resource-id": "integration_mappings_teams", "x-box-tag": "integration_mappings" }, "IntegrationMappingTeams": { "description": "A Microsoft Teams specific representation of an integration mapping object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingBase" }, { "properties": { "integration_type": { "description": "Identifies the Box partner app, with which the mapping is associated. Supports Slack and Teams. (part of the composite key together with `id`).", "type": "string", "example": "teams", "enum": [ "teams" ] }, "is_overridden_by_manual_mapping": { "description": "Identifies whether the mapping has been manually set by the team owner from UI for channels (as opposed to being automatically created).", "type": "boolean", "example": true }, "partner_item": { "description": "Mapped item object for Teams.", "example": { "id": "19%3ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2", "type": "channel", "tenant_id": "E1234567", "team_id": "hjgjgjg-bhhj-564a-b643-hghgj685u" }, "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingPartnerItemTeams" } ] }, "box_item": { "allOf": [ { "$ref": "#/components/schemas/FolderReference" }, { "description": "The Box folder, to which the object from the partner app domain (referenced in `partner_item_id`) is mapped." } ] }, "created_at": { "description": "When the integration mapping object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the integration mapping object was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } } } ], "required": [ "partner_item", "box_item" ], "title": "Integration mapping Teams", "x-box-resource-id": "integration_mapping_teams", "x-box-tag": "integration_mappings", "x-box-variant": "standard" }, "IntegrationMappingTeamsCreateRequest": { "description": "A request to create a Teams Integration Mapping object.", "type": "object", "properties": { "partner_item": { "allOf": [ { "$ref": "#/components/schemas/IntegrationMappingPartnerItemTeamsCreateRequest" } ] }, "box_item": { "allOf": [ { "$ref": "#/components/schemas/FolderReference" }, { "description": "The Box folder, to which the object from the partner app domain (referenced in `partner_item_id`) is mapped." } ] } }, "required": [ "partner_item", "box_item" ], "title": "Create teams integration mapping request", "x-box-resource-id": "integration_mapping_teams_create_request" }, "Invite": { "description": "An invite for a user to an enterprise.", "type": "object", "properties": { "id": { "description": "The unique identifier for this invite.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `invite`.", "type": "string", "example": "invite", "enum": [ "invite" ] }, "invited_to": { "description": "A representation of a Box enterprise.", "type": "object", "properties": { "id": { "description": "The unique identifier for this enterprise.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise.", "type": "string", "example": "Acme Inc." } }, "title": "Enterprise" }, "actionable_by": { "$ref": "#/components/schemas/User--Mini" }, "invited_by": { "$ref": "#/components/schemas/User--Mini" }, "status": { "description": "The status of the invite.", "type": "string", "example": "pending" }, "created_at": { "description": "When the invite was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the invite was modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "required": [ "id", "type" ], "title": "Invite", "x-box-resource-id": "invite", "x-box-tag": "invites" }, "Item": { "description": "An item represents a file, folder, or web link.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/File--Full" }, { "$ref": "#/components/schemas/Folder--Mini" }, { "$ref": "#/components/schemas/WebLink" } ], "title": "Item" }, "Items": { "description": "A list of files, folders, and web links in their mini representation.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "The items in this collection.", "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ], "title": "Items", "x-box-resource-id": "items", "x-box-tag": "folders" }, "ItemsOffsetPaginated": { "description": "A list of files, folders, and web links in their mini representation.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "The items in this collection.", "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ], "title": "Items", "x-box-resource-id": "items_offset_paginated", "x-box-tag": "folders" }, "KeywordSkillCard": { "description": "A skill card that contains a set of keywords.", "type": "object", "properties": { "created_at": { "description": "The optional date and time this card was created at.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00" }, "type": { "description": "The value will always be `skill_card`.", "type": "string", "example": "skill_card", "enum": [ "skill_card" ] }, "skill_card_type": { "description": "The value will always be `keyword`.", "type": "string", "example": "keyword", "enum": [ "keyword" ] }, "skill_card_title": { "description": "The title of the card.", "type": "object", "properties": { "code": { "description": "An optional identifier for the title.", "type": "string", "example": "labels" }, "message": { "description": "The actual title to show in the UI.", "type": "string", "example": "Labels" } }, "required": [ "message" ] }, "skill": { "description": "The service that applied this metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `service`.", "type": "string", "example": "service", "enum": [ "service" ] }, "id": { "description": "A custom identifier that represent the service that applied this metadata.", "type": "string", "example": "image-recognition-service" } }, "required": [ "type", "id" ] }, "invocation": { "description": "The invocation of this service, used to track which instance of a service applied the metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `skill_invocation`.", "type": "string", "example": "skill_invocation", "enum": [ "skill_invocation" ] }, "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.", "type": "string", "example": "image-recognition-service-123" } }, "required": [ "type", "id" ] }, "entries": { "description": "An list of entries in the metadata card.", "type": "array", "items": { "type": "object", "description": "An entry in the `entries` attribute of a metadata card.", "properties": { "text": { "description": "The text of the keyword.", "type": "string", "example": "keyword1" } } } } }, "required": [ "type", "skill_card_type", "skill", "invocation", "entries" ], "title": "Keyword Skill Card", "x-box-resource-id": "keyword_skill_card", "x-box-tag": "skills" }, "LegalHoldPolicies": { "description": "A list of legal hold policies.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of legal hold policies.", "type": "array", "items": { "$ref": "#/components/schemas/LegalHoldPolicy" } } } } ], "title": "Legal hold policies", "x-box-resource-id": "legal_hold_policies", "x-box-tag": "legal_hold_policies" }, "LegalHoldPolicy": { "description": "Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/LegalHoldPolicy--Mini" }, { "properties": { "policy_name": { "description": "Name of the legal hold policy.", "type": "string", "example": "Policy 4", "maxLength": 254 }, "description": { "description": "Description of the legal hold policy. Optional property with a 500 character limit.", "type": "string", "example": "Postman created policy", "maxLength": 500 }, "status": { "description": "Possible values:\n\n- 'active' - the policy is not in a transition state.\n- 'applying' - that the policy is in the process of being applied.\n- 'releasing' - that the process is in the process of being released.\n- 'released' - the policy is no longer active.", "type": "string", "example": "active", "enum": [ "active", "applying", "releasing", "released" ] }, "assignment_counts": { "description": "Counts of assignments within a legal hold policy by item type.", "type": "object", "properties": { "user": { "description": "The number of users this policy is applied to with the `access` type assignment.", "type": "integer", "format": "int64", "example": 1 }, "folder": { "description": "The number of folders this policy is applied to.", "type": "integer", "format": "int64", "example": 2 }, "file": { "description": "The number of files this policy is applied to.", "type": "integer", "format": "int64", "example": 3 }, "file_version": { "description": "The number of file versions this policy is applied to.", "type": "integer", "format": "int64", "example": 4 }, "ownership": { "description": "The number of users this policy is applied to with the `ownership` type assignment.", "type": "integer", "format": "int64", "example": 5 }, "interactions": { "description": "The number of users this policy is applied to with the `interactions` type assignment.", "type": "integer", "format": "int64", "example": 6 } } }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created the legal hold policy object." } ] }, "created_at": { "description": "When the legal hold policy object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the legal hold policy object was modified. Does not update when assignments are added or removed.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "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).\n\nIf `null`, the policy was not deleted.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "filter_started_at": { "description": "User-specified, optional date filter applies to Custodian assignments only.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "filter_ended_at": { "description": "User-specified, optional date filter applies to Custodian assignments only.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "release_notes": { "description": "Optional notes about why the policy was created.", "type": "string", "example": "Example", "maxLength": 500 } } } ], "title": "Legal hold policy", "x-box-resource-id": "legal_hold_policy", "x-box-tag": "legal_hold_policies", "x-box-variant": "standard" }, "LegalHoldPolicy--Mini": { "description": "A mini legal hold policy.", "type": "object", "properties": { "id": { "description": "The unique identifier for this legal hold policy.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `legal_hold_policy`.", "type": "string", "example": "legal_hold_policy", "enum": [ "legal_hold_policy" ] } }, "required": [ "id", "type" ], "title": "Legal hold policy (Mini)", "x-box-resource-id": "legal_hold_policy--mini", "x-box-tag": "legal_hold_policies", "x-box-variant": "mini", "x-box-variants": [ "mini", "standard" ] }, "LegalHoldPolicyAssignedItem": { "description": "The item that the legal hold policy is assigned to. Includes type and ID.", "type": "object", "properties": { "type": { "description": "The type of item the policy is assigned to.", "type": "string", "example": "folder", "enum": [ "file", "file_version", "folder", "user", "ownership", "interactions" ] }, "id": { "description": "The ID of the item the policy is assigned to.", "type": "string", "example": "6564564" } }, "required": [ "type", "id" ], "title": "Legal hold policy item" }, "LegalHoldPolicyAssignment": { "description": "Legal Hold Assignments are used to assign Legal Hold Policies to an item type of: Users, Folders, Files, File Versions, Ownership, or Interactions.\n\nCreating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/LegalHoldPolicyAssignment--Base" }, { "properties": { "legal_hold_policy": { "allOf": [ { "$ref": "#/components/schemas/LegalHoldPolicy--Mini" }, { "description": "The policy that the legal hold policy assignment is part of." } ] }, "assigned_to": { "allOf": [ { "$ref": "#/components/schemas/LegalHoldPolicyAssignedItem" }, { "description": "The item that the legal hold policy is assigned to. Includes type and ID." } ] }, "assigned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created the legal hold policy assignment." } ] }, "assigned_at": { "description": "When the legal hold policy assignment object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } } } ], "title": "Legal hold policy assignment", "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.\n\nCreating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity.", "type": "object", "properties": { "id": { "description": "The unique identifier for this legal hold assignment.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `legal_hold_policy_assignment`.", "type": "string", "example": "legal_hold_policy_assignment", "enum": [ "legal_hold_policy_assignment" ] } }, "title": "Legal hold policy assignment (Base)", "x-box-resource-id": "legal_hold_policy_assignment--base", "x-box-tag": "legal_hold_policy_assignments", "x-box-variant": "base", "x-box-variants": [ "base", "standard" ] }, "LegalHoldPolicyAssignments": { "description": "A list of legal hold policies assignments.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of legal hold policy assignments.", "type": "array", "items": { "$ref": "#/components/schemas/LegalHoldPolicyAssignment" } } } } ], "title": "Legal hold policy assignments", "x-box-resource-id": "legal_hold_policy_assignments", "x-box-tag": "legal_hold_policy_assignments" }, "Metadata": { "description": "An instance of a metadata template, which has been applied to a file or folder.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Metadata--Base" } ], "title": "Metadata instance", "x-box-resource-id": "metadata", "x-box-tag": "file_metadata", "x-box-variant": "standard" }, "Metadata--Base": { "description": "The base representation of a metadata instance.", "type": "object", "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}`.", "type": "string", "example": "folder_59449484661," }, "$template": { "description": "The name of the template.", "type": "string", "example": "marketingCollateral" }, "$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.", "type": "string", "example": "enterprise_27335" }, "$version": { "description": "The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.", "type": "integer", "example": 1 } }, "title": "Metadata instance (Base)", "x-box-resource-id": "metadata--base", "x-box-tag": "file_metadata", "x-box-variant": "base", "x-box-variants": [ "base", "standard", "full" ] }, "Metadata--Full": { "description": "An instance of a metadata template, which has been applied to a file or folder.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Metadata" }, { "properties": { "$canEdit": { "description": "Whether the user can edit this metadata instance.", "type": "boolean", "example": true }, "$id": { "description": "A UUID to identify the metadata instance.", "type": "string", "format": "uuid", "example": "01234500-12f1-1234-aa12-b1d234cb567e", "maxLength": 36 }, "$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.", "type": "string", "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0" }, "$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.", "type": "integer", "example": 2 } } }, { "additionalProperties": { "allOf": [ {}, { "example": "Aaron Levie" }, { "description": "A value for each of the fields that are present on the metadata template. For the `global.properties` template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template." } ], "x-box-example-key": "name" } } ], "title": "Metadata instance (Full)", "x-box-resource-id": "metadata--full", "x-box-tag": "file_metadata", "x-box-variant": "full" }, "MetadataCascadePolicies": { "description": "A list of metadata cascade policies.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of metadata cascade policies.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataCascadePolicy" } } } } ], "title": "Metadata cascade policies", "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.", "type": "object", "properties": { "id": { "description": "The ID of the metadata cascade policy object.", "type": "string", "example": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7" }, "type": { "description": "The value will always be `metadata_cascade_policy`.", "type": "string", "example": "metadata_cascade_policy", "enum": [ "metadata_cascade_policy" ] }, "owner_enterprise": { "description": "The enterprise that owns this policy.", "type": "object", "properties": { "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "id": { "description": "The ID of the enterprise that owns the policy.", "type": "string", "example": "690678" } } }, "parent": { "description": "Represent the folder the policy is applied to.", "type": "object", "properties": { "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { "description": "The ID of the folder the policy is applied to.", "type": "string", "example": "1234567" } } }, "scope": { "description": "The scope of the metadata cascade policy can either be `global` or `enterprise_*`. The `global` scope is used for policies that are available to any Box enterprise. The `enterprise_*` scope represents policies that have been created within a specific enterprise, where `*` will be the ID of that enterprise.", "type": "string", "example": "enterprise_123456" }, "templateKey": { "description": "The key of the template that is cascaded down to the folder's children.\n\nIn 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.\n\nPlease [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template's key.\n\n[list]: /reference/get-metadata-templates-enterprise\n[file]: /reference/get-files-id-metadata\n[folder]: /reference/get-folders-id-metadata", "type": "string", "example": "productInfo" } }, "required": [ "id", "type" ], "title": "Metadata cascade policy", "x-box-resource-id": "metadata_cascade_policy", "x-box-tag": "metadata_cascade_policies" }, "MetadataError": { "description": "A generic metadata operation error.", "type": "object", "properties": { "code": { "description": "A Box-specific error code.", "type": "string", "example": "bad_request" }, "message": { "description": "A short message describing the error.", "type": "string", "example": "Encountered invalid value for template field key=someKey field type=properties", "nullable": false }, "request_id": { "description": "A unique identifier for this response, which can be used when contacting Box support.", "type": "string", "example": "abcdef123456", "nullable": false } }, "title": "Metadata Error", "x-box-resource-id": "metadata_error" }, "MetadataFieldFilterDateRange": { "description": "Specifies which `date` field on the template to filter the search results by, specifying a range of dates that can match.", "type": "object", "properties": { "lt": { "description": "Specifies the (inclusive) upper bound for the metadata field value. The value of a field must be lower than (`lt`) or equal to this value for the search query to match this template.", "type": "string", "format": "date-time", "example": "2017-08-01T00:00:00Z" }, "gt": { "description": "Specifies the (inclusive) lower bound for the metadata field value. The value of a field must be greater than (`gt`) or equal to this value for the search query to match this template.", "type": "string", "format": "date-time", "example": "2016-08-01T00:00:00Z" } }, "title": "Metadata field filter (date range)", "x-box-resource-id": "metadata_field_filter_date_range" }, "MetadataFieldFilterFloatRange": { "description": "Specifies which `float` field on the template to filter the search results by, specifying a range of values that can match.", "type": "object", "properties": { "lt": { "description": "Specifies the (inclusive) upper bound for the metadata field value. The value of a field must be lower than (`lt`) or equal to this value for the search query to match this template.", "type": "number", "example": 200000 }, "gt": { "description": "Specifies the (inclusive) lower bound for the metadata field value. The value of a field must be greater than (`gt`) or equal to this value for the search query to match this template.", "type": "number", "example": 100000 } }, "title": "Metadata field filter (float range)", "x-box-resource-id": "metadata_field_filter_float_range" }, "MetadataFilter": { "description": "A metadata template used to filter the search results.", "type": "object", "properties": { "scope": { "description": "Specifies the scope of the template to filter search results by.\n\nThis will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box.", "type": "string", "example": "enterprise", "enum": [ "global", "enterprise", "enterprise_{enterprise_id}" ] }, "templateKey": { "description": "The key of the template used to filter search results.\n\nIn 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.\n\nPlease [list the templates for an enterprise][list], or get all instances on a [file][file] or [folder][folder] to inspect a template's key.\n\n[list]: /reference/get-metadata-templates-enterprise\n[file]: /reference/get-files-id-metadata\n[folder]: /reference/get-folders-id-metadata", "type": "string", "example": "contract" }, "filters": { "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.", "type": "object", "example": { "category": "online" }, "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/MetadataFilterValue" }, { "example": "online" }, { "x-box-example-key": "category" } ] } } }, "title": "Metadata filter", "x-box-resource-id": "metadata_filter", "x-box-tag": "search" }, "MetadataFilterValue": { "description": "A value of metadata filter.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "title": "Metadata field filter (multi-select)", "type": "array", "items": { "type": "string" }, "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": [ "online", "enterprise" ] }, { "$ref": "#/components/schemas/MetadataFieldFilterFloatRange" }, { "$ref": "#/components/schemas/MetadataFieldFilterDateRange" } ], "title": "Metadata filter value" }, "MetadataInstanceValue": { "description": "The value to be set or tested.\n\nRequired 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.\n\nFor `test`, the existing value at the `path` location must match the specified value.", "example": "reviewed", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number", "format": "float" }, { "type": "array", "items": { "type": "string" } } ], "title": "Metadata Instance Value" }, "MetadataQuery": { "description": "Create a search using SQL-like syntax to return items that match specific metadata.", "type": "object", "properties": { "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.", "type": "string", "example": "enterprise_123456.someTemplate" }, "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.\n\nFor example, a value of `:amount` would represent the `amount` value in `query_params` object.", "type": "string", "example": "value >= :amount" }, "query_params": { "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.", "type": "object", "example": { "amount": "100" }, "additionalProperties": { "allOf": [ {}, { "description": "The value for the argument being used in the metadata search.\n\nThe type of this parameter must match the type of the corresponding metadata template field." }, { "example": "100" } ], "x-box-example-key": "amount" } }, "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.", "type": "string", "example": "0" }, "order_by": { "description": "A list of template fields and directions to sort the metadata query results by.\n\nThe ordering `direction` must be the same for each item in the array.", "type": "array", "items": { "type": "object", "description": "An object representing one of the metadata template fields to sort the metadata query results by.", "properties": { "field_key": { "description": "The metadata template field to order by.\n\nThe `field_key` represents the `key` value of a field from the metadata template being searched for.", "type": "string", "example": "amount" }, "direction": { "description": "The direction to order by, either ascending or descending.\n\nThe `ordering` direction must be the same for each item in the array.", "type": "string", "example": "asc", "enum": [ "ASC", "DESC", "asc", "desc" ] } } } }, "limit": { "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.", "type": "integer", "example": 50, "default": 100, "maximum": 100, "minimum": 0 }, "marker": { "description": "Marker to use for requesting the next page.", "type": "string", "example": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff" }, "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.\n\nThis attribute takes a list of item fields, metadata template identifiers, or metadata template field identifiers.\n\nFor example:\n\n- `created_by` will add the details of the user who created the item to the response.\n- `metadata..` will return the mini-representation of the metadata instance identified by the `scope` and `templateKey`.\n- `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.", "type": "array", "items": { "type": "string" }, "example": [ "extension", "created_at", "item_status", "metadata.enterprise_1234.contracts", "metadata.enterprise_1234.regions.location" ] } }, "required": [ "from", "ancestor_folder_id" ], "title": "Metadata query search request" }, "MetadataQueryResultItem": { "description": "The mini representation of a file or folder.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/File--Full" }, { "$ref": "#/components/schemas/Folder--Full" } ], "title": "Metadata query search result item" }, "MetadataQueryResults": { "description": "A page of files and folders that matched the metadata query.", "type": "object", "properties": { "entries": { "description": "The mini representation of the files and folders that match the search terms.\n\nBy default, this endpoint returns only the most basic info about the items. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataQueryResultItem" }, "x-box-resource-variant": 1 }, "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.", "type": "integer", "format": "int64", "example": 100, "default": 100 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ.." } }, "title": "Metadata query search results", "x-box-resource-id": "metadata_query_results", "x-box-tag": "search" }, "Metadatas": { "description": "A list of metadata instances that have been applied to a file or folder.", "type": "object", "properties": { "entries": { "description": "A list of metadata instances, as applied to this file or folder.", "type": "array", "items": { "$ref": "#/components/schemas/Metadata" } }, "limit": { "description": "The limit that was used for this page of results.", "type": "integer", "example": 100 } }, "title": "Metadata instances", "x-box-resource-id": "metadatas", "x-box-tag": "file_metadata" }, "MetadataTaxonomies": { "description": "A list of metadata taxonomies.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of metadata taxonomies.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataTaxonomy" } } } } ], "title": "Metadata taxonomies", "x-box-resource-id": "metadata_taxonomies", "x-box-tag": "metadata_taxonomies" }, "MetadataTaxonomy": { "description": "A taxonomy object for metadata that can be used in metadata templates.", "type": "object", "properties": { "id": { "description": "A unique identifier of the metadata taxonomy.", "type": "string", "example": "822227e0-47a5-921b-88a8-494760b2e6d2" }, "key": { "description": "A unique identifier of the metadata taxonomy. The identifier must be unique within the namespace to which it belongs.", "type": "string", "example": "geography", "maxLength": 256, "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" }, "displayName": { "description": "The display name of the metadata taxonomy. This can be seen in the Box web app.", "type": "string", "example": "Geography", "maxLength": 4096 }, "namespace": { "description": "A namespace that the metadata taxonomy is associated with.", "type": "string", "example": "enterprise_123456", "maxLength": 4096 }, "levels": { "description": "Levels of the metadata taxonomy.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataTaxonomyLevel" } } }, "required": [ "id", "displayName", "namespace" ], "title": "Metadata taxonomy", "x-box-resource-id": "metadata_taxonomy", "x-box-tag": "metadata_taxonomies" }, "MetadataTaxonomyAncestor": { "description": "A node object in the metadata taxonomy that represents an ancestor.", "type": "object", "properties": { "id": { "description": "A unique identifier of the metadata taxonomy node.", "type": "string", "example": "14d3d433-c77f-49c5-b146-9dea370f6e32" }, "displayName": { "description": "The display name of the metadata taxonomy node.", "type": "string", "example": "France" }, "level": { "description": "An index of the level to which the node belongs.", "type": "integer", "example": 2 } }, "title": "Metadata taxonomy ancestor" }, "MetadataTaxonomyLevel": { "description": "A level in the metadata taxonomy represents a hierarchical category within the taxonomy structure.", "type": "object", "properties": { "displayName": { "description": "The display name of the level as it is shown to the user.", "type": "string", "example": "Continent" }, "description": { "description": "A description of the level.", "type": "string", "example": "Continent" }, "level": { "description": "An index of the level within the taxonomy. Levels are indexed starting from 1.", "type": "integer", "format": "int32", "example": 1 } }, "title": "Metadata taxonomy level", "x-box-resource-id": "metadata_taxonomy_level", "x-box-tag": "metadata_taxonomies" }, "MetadataTaxonomyLevels": { "description": "Levels in the metadata taxonomy represent hierarchical categories within the taxonomy structure.", "type": "object", "allOf": [ { "properties": { "entries": { "description": "An array of all taxonomy levels.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataTaxonomyLevel" } } } } ], "title": "Metadata taxonomy levels", "x-box-resource-id": "metadata_taxonomy_levels", "x-box-tag": "metadata_taxonomies" }, "MetadataTaxonomyNode": { "description": "A node object for metadata taxonomy that can be used in metadata templates.", "type": "object", "properties": { "id": { "description": "A unique identifier of the metadata taxonomy node.", "type": "string", "example": "14d3d433-c77f-49c5-b146-9dea370f6e32" }, "displayName": { "description": "The display name of the metadata taxonomy node.", "type": "string", "example": "France" }, "level": { "description": "An index of the level to which the node belongs.", "type": "integer", "example": 2 }, "parentId": { "description": "The identifier of the parent node.", "type": "string", "example": "99df4513-7102-4896-8228-94635ee9d330" }, "nodePath": { "description": "An array of identifiers for all ancestor nodes. \nNot returned for root-level nodes.", "type": "array", "items": { "type": "string" }, "example": [ "99df4513-7102-4896-8228-94635ee9d330" ] }, "ancestors": { "description": "An array of objects for all ancestor nodes. \nNot returned for root-level nodes.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataTaxonomyAncestor" } } }, "required": [ "id", "displayName", "level" ], "title": "Metadata taxonomy node", "x-box-resource-id": "metadata_taxonomy_node", "x-box-tag": "metadata_taxonomies" }, "MetadataTaxonomyNodes": { "description": "A list of metadata taxonomy nodes.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of metadata taxonomy nodes.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataTaxonomyNode" } } } } ], "title": "Metadata taxonomy nodes", "x-box-resource-id": "metadata_taxonomy_nodes", "x-box-tag": "metadata_taxonomies" }, "MetadataTemplate": { "description": "A template for metadata that can be applied to files and folders.", "type": "object", "properties": { "id": { "description": "The ID of the metadata template.", "type": "string", "example": "58063d82-4128-7b43-bba9-92f706befcdf" }, "type": { "description": "The value will always be `metadata_template`.", "type": "string", "example": "metadata_template", "enum": [ "metadata_template" ], "nullable": false }, "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.", "type": "string", "example": "enterprise_123456" }, "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.", "type": "string", "example": "productInfo", "maxLength": 64, "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" }, "displayName": { "description": "The display name of the template. This can be seen in the Box web app and mobile apps.", "type": "string", "example": "Product Info", "maxLength": 4096 }, "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.", "type": "boolean", "example": true }, "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.", "type": "array", "items": { "type": "object", "description": "A field within a metadata template. Fields can be a basic text, date, or number field, or a list of options.", "allOf": [ { "title": "Metadata Field (Read)", "description": "A field within a metadata template. Fields can be a basic text, date, or number field, a list of options, or a taxonomy.", "required": [ "type", "key", "displayName" ], "type": "object", "properties": { "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.\n\nAdditionally, 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.\n\nMetadata taxonomies are also supported as a `taxonomy` field type with a specific set of additional properties, which describe its structure.\n\n**Note**: The `integer` value is deprecated. It is still present in the response, but cannot be used in the POST request.", "type": "string", "example": "string", "enum": [ "string", "float", "date", "enum", "multiSelect", "taxonomy", "integer" ] }, "key": { "description": "A unique identifier for the field. The identifier must be unique within the template to which it belongs.", "type": "string", "example": "category", "maxLength": 256 }, "displayName": { "description": "The display name of the field as it is shown to the user in the web and mobile apps.", "type": "string", "example": "Category", "maxLength": 4096 }, "description": { "description": "A description of the field. This is not shown to the user.", "type": "string", "example": "The category", "maxLength": 4096 }, "hidden": { "description": "Whether this field is hidden in the UI for the user and can only be set through the API instead.", "type": "boolean", "example": true }, "options": { "description": "A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types.", "type": "array", "items": { "title": "Metadata Option (Write)", "type": "object", "description": "An option for a Metadata Template Field.\n\nOptions 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.", "required": [ "key" ], "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.", "type": "string", "example": "Category 1" } } } }, "taxonomyKey": { "description": "The unique key of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "string", "example": "locationTaxonomy" }, "taxonomyId": { "description": "The unique ID of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "string", "example": "05ece6d7-fec4-4d3f-bfd2-36fd4dddea97" }, "namespace": { "description": "The namespace of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "string", "example": "enterprise_123456" }, "optionsRules": { "description": "An object defining additional rules for the options of the taxonomy field. This property is required when the field `type` is set to `taxonomy`.", "type": "object", "properties": { "multiSelect": { "description": "Whether to allow users to select multiple values.", "type": "boolean", "example": true }, "selectableLevels": { "description": "An array of integers defining which levels of the taxonomy are selectable by users.", "type": "array", "items": { "type": "integer" }, "example": [ 1, 2 ] } } } } }, { "properties": { "id": { "description": "The unique ID of the metadata template field.", "type": "string", "example": "822227e0-47a5-921b-88a8-494760b2e6d2" }, "options": { "description": "A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types.", "type": "array", "items": { "type": "object", "description": "An option for a Metadata Template Field.\n\nOptions 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.", "allOf": [ { "title": "Metadata Option (Write)", "type": "object", "description": "An option for a Metadata Template Field.\n\nOptions 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.", "required": [ "key" ], "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.", "type": "string", "example": "Category 1" } } }, { "properties": { "id": { "description": "The internal unique identifier of the option.", "type": "string", "example": "45dc2849-a4a7-40a9-a751-4a699a589190" } } } ] } } } } ] } }, "copyInstanceOnItemCopy": { "description": "Whether or not to include the metadata when a file or folder is copied.", "type": "boolean", "example": true } }, "required": [ "type", "id" ], "title": "Metadata template", "x-box-resource-id": "metadata_template", "x-box-tag": "metadata_templates" }, "MetadataTemplates": { "description": "A list of metadata templates.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of metadata templates.", "type": "array", "items": { "$ref": "#/components/schemas/MetadataTemplate" } } } } ], "title": "Metadata templates", "x-box-resource-id": "metadata_templates", "x-box-tag": "metadata_templates" }, "OAuth2Error": { "description": "An OAuth 2.0 error.", "type": "object", "properties": { "error": { "description": "The type of the error returned.", "type": "string", "example": "invalid_client" }, "error_description": { "description": "The type of the error returned.", "type": "string", "example": "The client credentials are not valid" } }, "title": "OAuth 2.0 error", "x-box-resource-id": "oauth2_error", "x-box-tag": "authorization" }, "Outcome": { "description": "An instance of an outcome.", "type": "object", "properties": { "id": { "description": "ID of a specific outcome.", "type": "string", "example": "17363629" }, "collaborators": { "allOf": [ { "$ref": "#/components/schemas/CollaboratorVariable" }, { "description": "Lists collaborators affected by the workflow result." } ] }, "completion_rule": { "allOf": [ { "$ref": "#/components/schemas/CompletionRuleVariable" }, { "description": "Determines if an action should be completed by all or any assignees." } ] }, "file_collaborator_role": { "allOf": [ { "$ref": "#/components/schemas/RoleVariable" }, { "description": "Determines if the workflow outcome for a file affects a specific collaborator role." } ] }, "task_collaborators": { "allOf": [ { "$ref": "#/components/schemas/CollaboratorVariable" }, { "description": "Lists collaborators affected by the task workflow result." } ] }, "role": { "allOf": [ { "$ref": "#/components/schemas/RoleVariable" }, { "description": "Determines if the workflow outcome affects a specific collaborator role." } ] } }, "required": [ "id" ], "title": "Outcome" }, "PostOAuth2Revoke": { "description": "A request to revoke an OAuth 2.0 token.", "type": "object", "properties": { "client_id": { "description": "The Client ID of the application requesting to revoke the access token.", "type": "string", "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, "client_secret": { "description": "The client secret of the application requesting to revoke an access token.", "type": "string", "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" }, "token": { "description": "The access token to revoke.", "type": "string", "format": "token", "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" } }, "required": [ "grant_type" ], "title": "Token revocation request" }, "PostOAuth2Token": { "description": "A request for a new OAuth 2.0 token.", "type": "object", "properties": { "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.", "type": "string", "format": "urn", "example": "authorization_code", "enum": [ "authorization_code", "refresh_token", "client_credentials", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "client_id": { "description": "The Client ID of the application requesting an access token.\n\nUsed in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.", "type": "string", "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, "client_secret": { "description": "The client secret of the application requesting an access token.\n\nUsed in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.", "type": "string", "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" }, "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.\n\nUsed in combination with `authorization_code` as the `grant_type`.", "type": "string", "format": "token", "example": "n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW" }, "refresh_token": { "description": "A refresh token used to get a new access token with.\n\nUsed in combination with `refresh_token` as the `grant_type`.", "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "assertion": { "description": "A JWT assertion for which to request a new access token.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.", "type": "string", "format": "jwt", "example": "xxxxx.yyyyy.zzzzz" }, "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.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`.", "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "subject_token_type": { "description": "The type of `subject_token` passed in.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`.", "type": "string", "example": "urn:ietf:params:oauth:token-type:access_token", "enum": [ "urn:ietf:params:oauth:token-type:access_token" ] }, "actor_token": { "description": "The token used to create an annotator token. This is a JWT assertion.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`.", "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" }, "actor_token_type": { "description": "The type of `actor_token` passed in.\n\nUsed in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`.", "type": "string", "format": "urn", "example": "urn:ietf:params:oauth:token-type:id_token", "enum": [ "urn:ietf:params:oauth:token-type:id_token" ] }, "scope": { "description": "The space-delimited list of scopes that you want apply to the new access token.\n\nThe `subject_token` will need to have all of these scopes or the call will error with **401 Unauthorized**..", "type": "string", "format": "space_delimited_list", "example": "item_upload item_preview base_explorer" }, "resource": { "description": "Full URL for the file that the token should be generated for.", "type": "string", "format": "url", "example": "https://api.box.com/2.0/files/123456" }, "box_subject_type": { "description": "Used in combination with `client_credentials` as the `grant_type`.", "type": "string", "example": "enterprise", "enum": [ "enterprise", "user" ] }, "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.", "type": "string", "example": "123456789" }, "box_shared_link": { "description": "Full URL of the shared link on the file or folder that the token should be generated for.", "type": "string", "format": "url", "example": "https://cloud.box.com/s/123456" } }, "required": [ "grant_type" ], "title": "Token request" }, "PostOAuth2Token--RefreshAccessToken": { "description": "A request to refresh an Access Token. Use this API to refresh an expired Access Token using a valid Refresh Token.", "type": "object", "properties": { "grant_type": { "description": "The type of request being made, in this case a refresh request.", "type": "string", "format": "urn", "example": "refresh_token", "enum": [ "refresh_token" ] }, "client_id": { "description": "The client ID of the application requesting to refresh the token.", "type": "string", "example": "ly1nj6n11vionaie65emwzk575hnnmrk" }, "client_secret": { "description": "The client secret of the application requesting to refresh the token.", "type": "string", "example": "hOzsTeFlT6ko0dme22uGbQal04SBPYc1" }, "refresh_token": { "description": "The refresh token to refresh.", "type": "string", "format": "token", "example": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" } }, "required": [ "grant_type", "client_id", "client_secret", "refresh_token" ], "title": "Refresh access token" }, "RealtimeServer": { "description": "A real-time server that can be used for long polling user events.", "type": "object", "properties": { "type": { "description": "The value will always be `realtime_server`.", "type": "string", "example": "realtime_server" }, "url": { "description": "The URL for the server.", "type": "string", "example": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all" }, "ttl": { "description": "The time in minutes for which this server is available.", "type": "string", "example": "10" }, "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](/reference/options-events).", "type": "string", "example": "10" }, "retry_timeout": { "description": "The maximum number of seconds without a response after which you should retry the long poll connection.\n\nThis helps to overcome network issues where the long poll looks to be working but no packages are coming through.", "type": "integer", "example": 610 } }, "title": "Real-time server", "x-box-resource-id": "realtime_server" }, "RealtimeServers": { "description": "A list of real-time servers that can be used for long-polling.", "type": "object", "properties": { "chunk_size": { "description": "The number of items in this response.", "type": "integer", "format": "int64", "example": 1 }, "entries": { "description": "A list of real-time servers.", "type": "array", "items": { "$ref": "#/components/schemas/RealtimeServer" } } }, "title": "Real-time servers", "x-box-resource-id": "realtime_servers", "x-box-tag": "events" }, "RecentItem": { "description": "A recent item accessed by a user.", "type": "object", "properties": { "type": { "description": "The value will always be `recent_item`.", "type": "string", "example": "recent_item" }, "item": { "allOf": [ { "$ref": "#/components/schemas/RecentItemResource" }, { "description": "The item that was recently accessed." } ] }, "interaction_type": { "description": "The most recent type of access the user performed on the item.", "type": "string", "example": "item_preview", "enum": [ "item_preview", "item_upload", "item_comment", "item_open", "item_modify" ] }, "interacted_at": { "description": "The time of the most recent interaction.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00" }, "interaction_shared_link": { "description": "If the item was accessed through a shared link it will appear here, otherwise this will be null.", "type": "string", "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg" } }, "title": "Recent item", "x-box-resource-id": "recent_item", "x-box-tag": "recent_items" }, "RecentItemResource": { "description": "A recently accessed item resource. This can be a file, folder, or web link.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/File--Full" }, { "$ref": "#/components/schemas/Folder--Full" }, { "$ref": "#/components/schemas/WebLink" } ], "title": "Recent item resource" }, "RecentItems": { "description": "A list of recent items.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of recent items.", "type": "array", "items": { "$ref": "#/components/schemas/RecentItem" } } } } ], "title": "Recent items", "x-box-resource-id": "recent_items" }, "Resource": { "description": "The file or folder resource.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "$ref": "#/components/schemas/File--Mini" } ], "title": "Resource" }, "ResourceScope": { "description": "A relation between a resource (file or folder) and the scopes for which the resource can be accessed.", "type": "object", "properties": { "scope": { "description": "The scopes for the resource access.", "type": "string", "example": "item_download", "enum": [ "annotation_edit", "annotation_view_all", "annotation_view_self", "base_explorer", "base_picker", "base_preview", "base_upload", "item_delete", "item_download", "item_preview", "item_rename", "item_share", "item_upload", "item_read" ] }, "object": { "$ref": "#/components/schemas/Resource" } }, "title": "Resource scope" }, "RetentionPolicies": { "description": "A list of retention policies.", "type": "object", "allOf": [ { "properties": { "entries": { "description": "A list in which each entry represents a retention policy object.", "type": "array", "items": { "$ref": "#/components/schemas/RetentionPolicy" } } } }, { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } } ], "title": "Retention policies", "x-box-resource-id": "retention_policies", "x-box-tag": "retention_policies" }, "RetentionPolicy": { "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.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RetentionPolicy--Mini" }, { "properties": { "description": { "description": "The additional text description of the retention policy.", "type": "string", "example": "Policy to retain all reports for at least one month" }, "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.", "type": "string", "example": "finite", "enum": [ "finite", "indefinite" ] }, "retention_type": { "description": "Specifies the retention type:\n\n- `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.\n\n- `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.", "type": "string", "example": "non_modifiable", "enum": [ "modifiable", "non_modifiable" ] }, "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.", "type": "string", "example": "active", "enum": [ "active", "retired" ] }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "A mini user object representing the user that created the retention policy." } ] }, "created_at": { "description": "When the retention policy object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the retention policy object was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "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.", "type": "boolean", "example": false }, "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.", "type": "boolean", "example": false }, "custom_notification_recipients": { "description": "A list of users notified when the retention policy duration is about to end.", "type": "array", "items": { "$ref": "#/components/schemas/User--Mini" } }, "assignment_counts": { "description": "Counts the retention policy assignments for each item type.", "type": "object", "properties": { "enterprise": { "description": "The number of enterprise assignments this policy has. The maximum value is 1.", "type": "integer", "format": "int64", "example": 1 }, "folder": { "description": "The number of folder assignments this policy has.", "type": "integer", "format": "int64", "example": 1 }, "metadata_template": { "description": "The number of metadata template assignments this policy has.", "type": "integer", "format": "int64", "example": 1 } } } } } ], "title": "Retention policy", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier that represents a retention policy.", "type": "string", "example": "12345", "nullable": false }, "type": { "description": "The value will always be `retention_policy`.", "type": "string", "example": "retention_policy", "enum": [ "retention_policy" ], "nullable": false } }, "required": [ "id", "type" ], "title": "Retention policy (Base)", "x-box-resource-id": "retention_policy--base", "x-box-tag": "retention_policies", "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard" ] }, "RetentionPolicy--Mini": { "description": "A mini representation of a retention policy, used when nested within another resource.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RetentionPolicy--Base" }, { "properties": { "policy_name": { "description": "The name given to the retention policy.", "type": "string", "example": "Some Policy Name" }, "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`.", "type": "string", "format": "int32", "example": "365", "minimum": 1 }, "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.", "type": "string", "example": "permanently_delete", "enum": [ "permanently_delete", "remove_retention" ] }, "max_extension_length": { "$ref": "#/components/schemas/RetentionPolicyMaxExtensionLengthResponse" } } } ], "title": "Retention policy (Mini)", "x-box-resource-id": "retention_policy--mini", "x-box-tag": "retention_policies", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for a retention policy assignment.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `retention_policy_assignment`.", "type": "string", "example": "retention_policy_assignment", "enum": [ "retention_policy_assignment" ] }, "retention_policy": { "allOf": [ { "$ref": "#/components/schemas/RetentionPolicy--Mini" }, { "description": "A mini representation of a retention policy object that has been assigned to the content." } ] }, "assigned_to": { "description": "The `type` and `id` of the content that is under retention. The `type` can either be `folder` `enterprise`, or `metadata_template`.", "type": "object", "properties": { "id": { "description": "The ID of the folder, enterprise, or metadata template the policy is assigned to. Set to null or omit when type is set to enterprise.", "type": "string", "example": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65", "nullable": true }, "type": { "description": "The type of resource the policy is assigned to.", "type": "string", "example": "metadata_template", "enum": [ "folder", "enterprise", "metadata_template" ] } } }, "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.", "type": "array", "items": { "type": "object", "nullable": true, "properties": { "field": { "description": "The metadata attribute key id.", "type": "string", "example": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4", "nullable": true }, "value": { "description": "The metadata attribute field id. For value, only enum and multiselect types are supported.", "type": "string", "example": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e", "nullable": true } } }, "nullable": true }, "assigned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "A mini user object representing the user that created the retention policy assignment." } ] }, "assigned_at": { "description": "When the retention policy assignment object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "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.", "type": "string", "example": "upload_date" } }, "required": [ "id", "type" ], "title": "Retention policy assignment", "x-box-resource-id": "retention_policy_assignment", "x-box-tag": "retention_policy_assignments" }, "RetentionPolicyAssignments": { "description": "A list of retention policy assignments.", "type": "object", "allOf": [ { "properties": { "entries": { "description": "A list of retention policy assignments.", "type": "array", "items": { "$ref": "#/components/schemas/RetentionPolicyAssignment" } } } }, { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } } ], "title": "Retention policy assignments", "x-box-resource-id": "retention_policy_assignments", "x-box-tag": "retention_policy_assignments" }, "RetentionPolicyMaxExtensionLengthRequest": { "description": "The maximum extension length of the retention date. This value specifies the duration in days for which the retention date of the file under policy can be extended. It can be specified only for the 'finite' policy type where the disposition action is 'permanently delete', otherwise the server will return status 400. If this value is 'none', it won't be possible to extend the retention.", "example": "365", "nullable": false, "oneOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "pattern": "^[1-9]\\d*$", "format": "int32" }, { "type": "integer", "format": "int32", "minimum": 1, "multipleOf": 1 } ], "title": "Retention policy max extension length (request)" }, "RetentionPolicyMaxExtensionLengthResponse": { "description": "The maximum extension length of the retention date. This value specifies the duration in days for which the retention date of the file under policy can be extended. If the policy type is other than 'finite' or the disposition action is other than 'permanently delete', or the maximum extension length is undefined, this field will be set to 'none'.", "example": "365", "oneOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "pattern": "^[1-9]\\d*$", "format": "int32", "minimum": 1 } ], "title": "Retention policy max extension length (response)" }, "RoleVariable": { "description": "Determines if the workflow outcome affects a specific collaborator role.", "type": "object", "properties": { "type": { "description": "Role object type.", "type": "string", "example": "variable", "enum": [ "variable" ] }, "variable_type": { "description": "The variable type used by the object.", "type": "string", "example": "collaborator_role", "enum": [ "collaborator_role" ] }, "variable_value": { "allOf": [ { "type": "string", "description": "The level of access granted.", "example": "editor", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, { "description": "Variable values you can use for the role parameter." } ] } }, "required": [ "type", "variable_type", "variable_value" ], "title": "Role variable" }, "SearchResultItem": { "description": "An item in search results. This can be a file, folder, or web link.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/File--Full" }, { "$ref": "#/components/schemas/Folder--Full" }, { "$ref": "#/components/schemas/WebLink" } ], "title": "Search results item" }, "SearchResults": { "description": "A list of files, folders and web links that matched the search query.", "type": "object", "allOf": [ { "type": "object", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than `total_count`.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter used.", "type": "integer", "format": "int64", "example": 2000 } } }, { "properties": { "type": { "description": "Specifies the response as search result items without shared links.", "type": "string", "example": "search_results_items", "enum": [ "search_results_items" ], "nullable": false }, "entries": { "description": "The search results for the query provided.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultItem" } } } } ], "required": [ "type" ], "title": "Search Results", "x-box-resource-id": "search_results", "x-box-tag": "search" }, "SearchResultsResponse": { "description": "Search result from the content search endpoint.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SearchResults" }, { "$ref": "#/components/schemas/SearchResultsWithSharedLinks" } ], "title": "Search results response" }, "SearchResultsWithSharedLinks": { "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.\n\nThis response format is only returned when the `include_recent_shared_links` query parameter has been set to `true`.", "type": "object", "allOf": [ { "type": "object", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than `total_count`.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter used.", "type": "integer", "format": "int64", "example": 2000 } } }, { "properties": { "type": { "description": "Specifies the response as search result items with shared links.", "type": "string", "example": "search_results_with_shared_links", "enum": [ "search_results_with_shared_links" ], "nullable": false }, "entries": { "description": "The search results for the query provided, including the additional information about any shared links through which the item has been shared with the user.", "type": "array", "items": { "$ref": "#/components/schemas/SearchResultWithSharedLink" } } } } ], "required": [ "type" ], "title": "Search Results (including Shared Links)", "x-box-resource-id": "search_results_with_shared_links", "x-box-tag": "search" }, "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.\n\nThis response format is only returned when the `include_recent_shared_links` query parameter has been set to `true`.", "type": "object", "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`.", "type": "string", "format": "url", "example": "https://www.box.com/s/vspke7y05sb214wjokpk" }, "item": { "allOf": [ { "$ref": "#/components/schemas/SearchResultWithSharedLinkItem" }, { "description": "The file, folder or web link that matched the search query." } ] }, "type": { "description": "The result type. The value is always `search_result`.", "type": "string", "example": "search_result" } }, "title": "Search Result (including Shared Link)", "x-box-resource-id": "search_result_with_shared_link", "x-box-tag": "search" }, "SearchResultWithSharedLinkItem": { "description": "An item in search results with a shared link. This can be a file, folder, or web link.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/File--Full" }, { "$ref": "#/components/schemas/Folder--Full" }, { "$ref": "#/components/schemas/WebLink" } ], "title": "Search result item" }, "SessionTerminationMessage": { "description": "A message informing about the termination job status.", "type": "object", "properties": { "message": { "description": "The unique identifier for the termination job status.", "type": "string", "example": "Request is successful, please check the admin\nevents for the status of the job" } }, "title": "Session termination message", "x-box-resource-id": "session_termination", "x-box-tag": "session_termination" }, "ShieldInformationBarrier": { "description": "A standard representation of a shield information barrier object.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shield information barrier.", "type": "string", "example": "11446498" }, "type": { "description": "The type of the shield information barrier.", "type": "string", "example": "shield_information_barrier", "enum": [ "shield_information_barrier" ] }, "enterprise": { "description": "The `type` and `id` of enterprise this barrier is under.", "allOf": [ { "$ref": "#/components/schemas/Enterprise--Base" } ] }, "status": { "description": "Status of the shield information barrier.", "type": "string", "example": "draft", "enum": [ "draft", "pending", "disabled", "enabled", "invalid" ] }, "created_at": { "description": "ISO date time string when this shield information barrier object was created.", "type": "string", "format": "date-time", "example": "2020-06-26T18:44:45.869Z" }, "created_by": { "description": "The user who created this shield information barrier.", "allOf": [ { "$ref": "#/components/schemas/User--Base" } ] }, "updated_at": { "description": "ISO date time string when this shield information barrier was updated.", "type": "string", "format": "date-time", "example": "2020-07-26T18:44:45.869Z" }, "updated_by": { "description": "The user that updated this shield information barrier.", "allOf": [ { "$ref": "#/components/schemas/User--Base" } ] }, "enabled_at": { "description": "ISO date time string when this shield information barrier was enabled.", "type": "string", "format": "date-time", "example": "2020-07-26T18:44:45.869Z" }, "enabled_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user that enabled this shield information barrier." } ] } }, "title": "Shield information barrier", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shield information barrier.", "type": "string", "example": "11446498" }, "type": { "description": "The type of the shield information barrier.", "type": "string", "example": "shield_information_barrier", "enum": [ "shield_information_barrier" ] } }, "title": "Shield information barrier (Base)", "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.", "type": "object", "properties": { "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" } }, "title": "Shield information barrier reference", "x-box-resource-id": "shield_information_barrier_reference", "x-box-tag": "shield_information_barrier_reports" }, "ShieldInformationBarrierReport": { "description": "A standard representation of a shield information barrier report object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShieldInformationBarrierReport--Base" }, { "properties": { "shield_information_barrier": { "allOf": [ { "$ref": "#/components/schemas/ShieldInformationBarrierReference" } ] }, "status": { "description": "Status of the shield information report.", "type": "string", "example": "pending", "enum": [ "pending", "error", "done", "cancelled" ] }, "details": { "allOf": [ { "$ref": "#/components/schemas/ShieldInformationBarrierReportDetails" } ] }, "created_at": { "description": "ISO date time string when this shield information barrier report object was created.", "type": "string", "format": "date-time", "example": "2020-06-26T18:44:45.869Z" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user who created this shield information barrier report." } ] }, "updated_at": { "description": "ISO date time string when this shield information barrier report was updated.", "type": "string", "format": "date-time", "example": "2020-07-26T18:44:45.869Z" } } } ], "title": "Shield information barrier report", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shield information barrier report.", "type": "string", "example": "11446498" }, "type": { "description": "The type of the shield information barrier report.", "type": "string", "example": "shield_information_barrier_report", "enum": [ "shield_information_barrier_report" ] } }, "title": "Shield information barrier report (Base)", "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.", "type": "object", "properties": { "details": { "type": "object", "properties": { "folder_id": { "description": "Folder ID for locating this report.", "type": "string", "example": "124235" } } } }, "title": "Shield information barrier report details", "x-box-resource-id": "shield_information_barrier_report_details", "x-box-tag": "shield_information_barrier_reports" }, "ShieldInformationBarrierReports": { "description": "A list of shield barrier reports.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } }, { "properties": { "entries": { "description": "A list of shield information barrier reports.", "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierReport" } } } } ], "title": "List of Shield Information Barrier Reports", "x-box-resource-id": "shield_information_barrier_reports", "x-box-tag": "shield_information_barrier_reports" }, "ShieldInformationBarriers": { "description": "List of Shield Information Barrier objects.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } }, { "properties": { "entries": { "description": "A list of shield information barrier objects.", "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrier" } } } } ], "title": "List of Shield Information Barriers", "x-box-resource-id": "shield_information_barriers", "x-box-tag": "shield_information_barriers" }, "ShieldInformationBarrierSegment": { "description": "A shield information barrier segment object.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shield information barrier segment.", "type": "string", "example": "11446498" }, "type": { "description": "The type of the shield information barrier segment.", "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] }, "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "name": { "description": "Name of the shield information barrier segment.", "type": "string", "example": "Investment Banking" }, "description": { "description": "Description of the shield information barrier segment.", "type": "string", "example": "'Corporate division that engages in advisory_based financial\n transactions on behalf of individuals, corporations, and governments.'" }, "created_at": { "description": "ISO date time string when this shield information barrier object was created.", "type": "string", "format": "date-time", "example": "2020-06-26T18:44:45.869Z" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user who created this shield information barrier segment." } ] }, "updated_at": { "description": "ISO date time string when this shield information barrier segment was updated.", "type": "string", "format": "date-time", "example": "2020-07-26T18:44:45.869Z" }, "updated_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user that updated this shield information barrier segment." } ] } }, "title": "Shield information barrier segment", "x-box-resource-id": "shield_information_barrier_segment", "x-box-tag": "shield_information_barrier_segments" }, "ShieldInformationBarrierSegmentMember": { "description": "A standard representation of a shield information barrier segment member object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember--Mini" }, { "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.", "type": "object", "properties": { "id": { "description": "The ID reference of the requesting shield information barrier segment.", "type": "string", "example": "432554" }, "type": { "description": "The type of the shield information barrier segment.", "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } } }, "user": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The `type` and `id` of the requested shield information barrier segment member." } ] }, "created_at": { "description": "ISO date time string when this shield information barrier object was created.", "type": "string", "format": "date-time", "example": "2020-06-26T18:44:45.869Z" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user who created this shield information barrier segment member." } ] }, "updated_at": { "description": "ISO date time string when this shield information barrier segment Member was updated.", "type": "string", "format": "date-time", "example": "2020-07-26T18:44:45.869Z" }, "updated_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user that updated this shield information barrier segment Member." } ] } } } ], "title": "Shield information barrier segment member", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for the shield information barrier segment member.", "type": "string", "example": "11446498" }, "type": { "description": "The type of the shield information barrier segment member.", "type": "string", "example": "shield_information_barrier_segment_member", "enum": [ "shield_information_barrier_segment_member" ] } }, "title": "Shield information barrier segment member (Base)", "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": { "description": "A mini representation of a shield information barrier segment member object.", "type": "object", "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." } ] } } } ], "title": "Shield information barrier segment member (Mini)", "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" ] }, "ShieldInformationBarrierSegmentMembers": { "description": "List of Shield Information Barrier Member objects.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } }, { "properties": { "entries": { "description": "A list of shield information barrier segment members.", "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentMember" } } } } ], "title": "List of Shield Information Barrier Segment Members", "x-box-resource-id": "shield_information_barrier_segment_members", "x-box-tag": "shield_information_barrier_segment_members" }, "ShieldInformationBarrierSegmentRestriction": { "description": "A standard representation of a segment restriction of a shield information barrier object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Mini" }, { "properties": { "shield_information_barrier": { "$ref": "#/components/schemas/ShieldInformationBarrier--Base" }, "created_at": { "description": "ISO date time string when this shield information barrier Segment Restriction object was created.", "type": "string", "format": "date-time", "example": "2020-06-26T18:44:45.869Z" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user who created this shield information barrier segment Restriction." } ] }, "updated_at": { "description": "ISO date time string when this shield information barrier segment Restriction was updated.", "type": "string", "format": "date-time", "example": "2020-07-26T18:44:45.869Z" }, "updated_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user that updated this shield information barrier segment Restriction." } ] } } } ], "required": [ "shield_information_barrier_segment", "restricted_segment" ], "title": "Shield information barrier segment restriction", "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.", "type": "object", "properties": { "type": { "description": "Shield information barrier segment restriction.", "type": "string", "example": "shield_information_barrier_segment_restriction", "enum": [ "shield_information_barrier_segment_restriction" ] }, "id": { "description": "The unique identifier for the shield information barrier segment restriction.", "type": "string", "example": "11446498" } }, "required": [ "shield_information_barrier_segment", "restricted_segment" ], "title": "Shield information barrier segment restriction (Base)", "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": { "description": "A mini representation of a segment restriction object for the shield information barrier.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Base" }, { "properties": { "shield_information_barrier_segment": { "description": "The `type` and `id` of the requested shield information barrier segment.", "type": "object", "properties": { "id": { "description": "The ID reference of the requesting shield information barrier segment.", "type": "string", "example": "1910967" }, "type": { "description": "The type of the shield information barrier segment.", "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } } }, "restricted_segment": { "description": "The `type` and `id` of the restricted shield information barrier segment.", "type": "object", "properties": { "id": { "description": "The ID reference of the restricted shield information barrier segment.", "type": "string", "example": "1910967" }, "type": { "description": "The type of the shield information segment.", "type": "string", "example": "shield_information_barrier_segment", "enum": [ "shield_information_barrier_segment" ] } } } } } ], "required": [ "shield_information_barrier_segment", "restricted_segment" ], "title": "Shield information barrier segment restriction (Mini)", "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" ] }, "ShieldInformationBarrierSegmentRestrictions": { "description": "List of shield information barrier segment restriction objects.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } }, { "properties": { "entries": { "description": "A list of shield information barrier segment restriction objects.", "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierSegmentRestriction" } } } } ], "title": "List of Shield Information Barrier Segment Restrictions", "x-box-resource-id": "shield_information_barrier_segment_restrictions", "x-box-tag": "shield_information_barrier_segment_restrictions" }, "ShieldInformationBarrierSegments": { "description": "List of Shield Information Barrier Segment objects.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } }, { "properties": { "entries": { "description": "A list of shield information barrier segments.", "type": "array", "items": { "$ref": "#/components/schemas/ShieldInformationBarrierSegment" } } } } ], "title": "List of Shield Information Barrier Segments", "x-box-resource-id": "shield_information_barrier_segments", "x-box-tag": "shield_information_barrier_segments" }, "SignRequest": { "description": "A Box Sign request object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SignRequest--Base" }, { "properties": { "type": { "description": "The value will always be `sign-request`.", "type": "string", "example": "sign-request", "enum": [ "sign-request" ] }, "source_files": { "description": "List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file.", "type": "array", "items": { "$ref": "#/components/schemas/File--Base" } }, "signers": { "description": "Array of signers for the signature request.", "type": "array", "items": { "$ref": "#/components/schemas/SignRequestSigner" } }, "signature_color": { "description": "Force a specific color for the signature (blue, black, or red).", "type": "string", "example": "blue", "nullable": true }, "id": { "description": "Box Sign request ID.", "type": "string", "example": "12345" }, "prepare_url": { "description": "This URL is returned if `is_document_preparation_needed` is set to `true` in the request. The parameter is used to prepare the signature request using the UI. The signature request is not sent until the preparation phase is complete.", "type": "string", "example": "https://prepareurl.com", "nullable": true }, "signing_log": { "allOf": [ { "$ref": "#/components/schemas/File--Mini" }, { "description": "Reference to a file that holds a log of all signer activity for the request." } ] }, "status": { "description": "Describes the status of the signature request.", "type": "string", "example": "converting", "enum": [ "converting", "created", "sent", "viewed", "signed", "cancelled", "declined", "error", "error_converting", "error_sending", "expired", "finalizing", "error_finalizing" ] }, "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.", "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/File--Mini" } }, "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.", "type": "boolean", "example": true } } }, "auto_expire_at": { "description": "Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned.", "type": "string", "format": "date-time", "example": "2021-04-26T08:12:13.982Z", "nullable": true }, "parent_folder": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The destination folder to place final, signed document and signing log.\n\nWhen this value was not passed in when the signature request was created, then we will use a default folder which is either the parent folder of the first source file in the payload if we have the permission to upload to that folder or a folder called \"My Sign Requests\"." } ], "nullable": false }, "collaborator_level": { "description": "The collaborator level of the user to the sign request. Values can include \"owner\", \"editor\", and \"viewer\".", "type": "string", "example": "owner", "nullable": true }, "short_id": { "description": "Short identifier for the sign request.", "type": "string", "example": "SR-12345", "nullable": false }, "created_at": { "description": "Timestamp marking when the sign request was created.", "type": "string", "format": "date-time", "example": "2025-02-01T12:00:00Z", "nullable": false }, "finished_at": { "description": "Timestamp indicating when all signing actions completed.", "type": "string", "format": "date-time", "example": "2025-02-02T12:00:00Z", "nullable": true }, "error_code": { "description": "When the sign request is in an error state, identifies the specific reason. Null when no error code applies.", "type": "string", "example": "cfr11_validation_failed", "nullable": true, "readOnly": true }, "sender_email": { "description": "The email address of the sender of the sign request.", "type": "string", "example": "sender@box.com", "nullable": true }, "sender_id": { "description": "The user ID of the sender of the sign request.", "type": "integer", "example": 12345, "nullable": true } } } ], "title": "Box Sign request", "x-box-resource-id": "sign_request", "x-box-tag": "sign_requests" }, "SignRequest--Base": { "description": "A standard representation of a signature request object.", "type": "object", "properties": { "is_document_preparation_needed": { "description": "Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI.", "type": "boolean", "example": true }, "redirect_url": { "description": "When specified, the signature request will be redirected to this url when a document is signed.", "type": "string", "example": "https://www.example.com", "nullable": true }, "declined_redirect_url": { "description": "The uri that a signer will be redirected to after declining to sign a document.", "type": "string", "example": "https://declined-redirect.com", "nullable": true }, "are_text_signatures_enabled": { "description": "Disables the usage of signatures generated by typing (text).", "type": "boolean", "example": true, "default": true }, "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.", "type": "string", "example": "Sign Request from Acme", "nullable": true }, "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.", "type": "string", "example": "Hello! Please sign the document below", "nullable": true }, "are_reminders_enabled": { "description": "Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.", "type": "boolean", "example": true }, "name": { "description": "Name of the signature request.", "type": "string", "example": "name" }, "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.", "type": "array", "items": { "$ref": "#/components/schemas/SignRequestPrefillTag" } }, "days_valid": { "description": "Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.", "type": "integer", "example": 2, "maximum": 730, "minimum": 0, "nullable": true }, "external_id": { "description": "This can be used to reference an ID in an external system that the sign request is related to.", "type": "string", "example": "123", "nullable": true }, "template_id": { "description": "When a signature request is created from a template this field will indicate the id of that template.", "type": "string", "example": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb", "nullable": true }, "external_system_name": { "description": "Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`.", "type": "string", "example": "Box", "nullable": true }, "request_flow": { "description": "The flow type of the sign request. Values can include `standard` or `cfr11`. When not specified during creation, a default is chosen based on admin settings.", "type": "string", "example": "standard", "nullable": true } }, "title": "Box Sign request (Base)", "x-box-tag": "sign_requests" }, "SignRequestCancelRequest": { "description": "Request body for cancelling a sign request.", "type": "object", "properties": { "reason": { "description": "An optional reason for cancelling the sign request.", "type": "string", "example": "Project cancelled" } }, "title": "Sign request cancel request" }, "SignRequestCreateRequest": { "description": "Creates a Box Sign request object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SignRequest--Base" }, { "properties": { "source_files": { "description": "List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file.", "type": "array", "items": { "$ref": "#/components/schemas/File--Base" }, "maxItems": 10, "nullable": true }, "signature_color": { "description": "Force a specific color for the signature (blue, black, or red).", "type": "string", "example": "blue", "enum": [ "blue", "black", "red" ], "nullable": true }, "signers": { "description": "Array of signers for the signature request. 35 is the max number of signers permitted.\n\n**Note**: It may happen that some signers belong to conflicting [segments](/reference/resources/shield-information-barrier-segment-member) (user groups). This means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts. In such a case, an attempt to send the sign request will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ).", "type": "array", "items": { "$ref": "#/components/schemas/SignRequestCreateSigner" } }, "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 and can also not be null.\n\nWhen this value is not passed in when the signature request, then we will use a default folder which is either the parent folder of the first source file in the payload if we have the permission to upload to that folder or a folder called \"My Sign Requests\"." } ] } } } ], "required": [ "signers" ], "title": "Create a Box Sign request", "x-box-resource-id": "sign_request_create_request" }, "SignRequestCreateSigner": { "description": "The schema for a Signer object used in for creating a Box Sign request object.", "type": "object", "properties": { "email": { "description": "Email address of the signer. The email address of the signer is required when making signature requests, except when using templates that are configured to include emails.", "type": "string", "example": "example@gmail.com", "nullable": true }, "role": { "description": "Defines the role of the signer in the signature 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.", "type": "string", "example": "signer", "default": "signer", "enum": [ "signer", "approver", "final_copy_reader" ] }, "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.", "type": "boolean", "example": true }, "order": { "description": "Order of the signer.", "type": "integer", "example": 2, "minimum": 0 }, "embed_url_external_user_id": { "description": "User ID for the signer in an external application responsible for authentication when accessing the embed URL.", "type": "string", "example": "1234", "nullable": 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.", "type": "string", "example": "https://example.com", "nullable": true }, "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.", "type": "string", "example": "https://declined-example.com", "nullable": true }, "login_required": { "description": "If set to true, the signer will need to log in to a Box account before signing the request. If the signer does not have an existing account, they will have the option to create a free Box account.", "type": "boolean", "example": true, "nullable": true }, "verification_phone_number": { "description": "If set, this phone number will be used to verify the signer via two-factor authentication before they are able to sign the document. Cannot be selected in combination with `login_required`.", "type": "string", "example": "6314578901", "nullable": true }, "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.", "type": "string", "example": "SecretPassword123", "nullable": true, "writeOnly": true }, "signer_group_id": { "description": "If set, signers who have the same value will be assigned to the same input and to the same signer group. A signer group is not a Box Group. It is an entity that belongs to a Sign Request and can only be used/accessed within this Sign Request. A signer group is expected to have more than one signer. If the provided value is only used for one signer, this value will be ignored and request will be handled as it was intended for an individual signer. The value provided can be any string and only used to determine which signers belongs to same group. A successful response will provide a generated UUID value instead for signers in the same signer group.", "type": "string", "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", "nullable": true }, "suppress_notifications": { "description": "If true, no emails about the sign request will be sent.", "type": "boolean", "example": false, "nullable": true }, "language": { "description": "The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format.", "type": "string", "example": "en", "nullable": true } }, "title": "Signer fields used to create a Box Sign request object." }, "SignRequestPrefillTag": { "description": "Prefill tags are used to prefill placeholders with signer input data. Only one value field can be included.", "type": "object", "properties": { "document_tag_id": { "description": "This references the ID of a specific tag contained in a file of the signature request.", "type": "string", "example": "1234", "nullable": true }, "text_value": { "description": "Text prefill value.", "type": "string", "example": "text", "nullable": true }, "checkbox_value": { "description": "Checkbox prefill value.", "type": "boolean", "example": true, "nullable": true }, "date_value": { "description": "Date prefill value.", "type": "string", "format": "date", "example": "2021-04-26", "nullable": true } }, "title": "Sign request prefill tag" }, "SignRequests": { "description": "A standard representation of a signature request, as returned from any Box Sign API endpoints by default.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true } } }, { "properties": { "entries": { "description": "A list of Box Sign requests.", "type": "array", "items": { "$ref": "#/components/schemas/SignRequest" } } } } ], "title": "Box Sign requests", "x-box-resource-id": "sign_requests", "x-box-tag": "sign_requests" }, "SignRequestSigner": { "description": "The schema for a Signer object used on the body of a Box Sign request object.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SignRequestCreateSigner" }, { "properties": { "has_viewed_document": { "description": "Set to `true` if the signer views the document.", "type": "boolean", "example": true, "readOnly": true }, "signer_decision": { "description": "Final decision made by the signer.", "type": "object", "nullable": true, "properties": { "type": { "description": "Type of decision made by the signer.", "type": "string", "example": "signed", "enum": [ "signed", "declined" ] }, "finalized_at": { "description": "Date and Time that the decision was made.", "type": "string", "format": "date-time", "example": "2021-04-26T08:12:13.982Z" }, "additional_info": { "description": "Additional info about the decision, such as the decline reason from the signer.", "type": "string", "example": "Requesting changes before signing.", "nullable": true } } }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/SignRequestSignerInput" }, "readOnly": true }, "embed_url": { "description": "URL to direct a signer to for signing.", "type": "string", "example": "https://example.com", "nullable": true, "readOnly": true }, "iframeable_embed_url": { "description": "This URL is specifically designed for signing documents within an HTML `iframe` tag. It will be returned in the response only if the `embed_url_external_user_id` parameter was passed in the `create Box Sign request` call.", "type": "string", "example": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4", "nullable": true }, "attachments": { "description": "Attachments that the signer uploaded.", "type": "array", "items": { "$ref": "#/components/schemas/SignRequestSignerAttachment" }, "nullable": true } } } ], "required": [ "email" ], "title": "Signer fields for Box Sign request response" }, "SignRequestSignerAttachment": { "description": "Metadata describing a file uploaded by a signer as an attachment.", "type": "object", "properties": { "id": { "description": "Identifier of the attachment file.", "type": "string", "example": "12345", "nullable": true }, "name": { "description": "Display name of the attachment file.", "type": "string", "example": "proof_of_identity.pdf", "nullable": true } }, "title": "Signer Attachment" }, "SignRequestSignerInput": { "description": "Input created by a Signer on a Sign Request.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SignRequestPrefillTag" }, { "properties": { "type": { "description": "Type of input.", "type": "string", "example": "text", "enum": [ "signature", "date", "text", "checkbox", "radio", "dropdown" ] }, "content_type": { "description": "Content type of input.", "type": "string", "example": "signature", "enum": [ "signature", "initial", "stamp", "date", "checkbox", "text", "full_name", "first_name", "last_name", "company", "title", "email", "attachment", "radio", "dropdown" ] }, "page_index": { "description": "Index of page that the input is on.", "type": "integer", "example": 4 }, "read_only": { "description": "Indicates whether this input is read-only (cannot be modified by signers).", "type": "boolean", "example": true }, "validation": { "description": "Specifies the formatting rules that signers must follow for text field inputs. If set, this validation is mandatory.", "example": { "validation_type": "email" }, "anyOf": [ { "$ref": "#/components/schemas/SignRequestSignerInputValidation" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] }, "reason": { "description": "The reason for the signer's input, applicable to signature or initial content types in a `cfr11` request flow. The value is `null` when not applicable.", "type": "string", "example": "I read and approve this document", "nullable": true }, "is_validated": { "description": "Indicates whether the signer's input has been validated through re-authentication. Applicable only for signature or initial content types in a `cfr11` request flow. The value is `null` for standard request flows or non-applicable input types.", "type": "boolean", "example": true, "nullable": true } } } ], "required": [ "page_index" ], "title": "Sign Request Signer Input" }, "SignRequestSignerInputCustomValidation": { "description": "Specifies the custom validation rules for a text field input by the signer. If set, this validation is mandatory.", "type": "object", "properties": { "validation_type": { "description": "Defines the validation format for the text input as custom. A custom regular expression is used for validation.", "type": "string", "example": "custom", "enum": [ "custom" ] }, "custom_regex": { "description": "Regular expression used for validation.", "type": "string", "example": "(^[a-zA-Z0-9._%+-]+)", "nullable": true }, "custom_error_message": { "description": "Error message shown if input fails custom regular expression validation.", "type": "string", "example": "Please enter a valid value.", "nullable": true } }, "required": [ "validation_type", "custom_regex", "custom_error_message" ], "title": "Sign Request Signer Input Custom Validation" }, "SignRequestSignerInputDateAsiaValidation": { "description": "Specifies the date formatting rules used in Asia for a text field input by the signer. If set, this validation is mandatory. The date format follows `YYYY/MM/DD` pattern.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input uses the Asian date format `YYYY/MM/DD`.", "type": "string", "example": "date_asia", "enum": [ "date_asia" ] } }, "title": "Sign Request Signer Input Date Asia Validation" }, "SignRequestSignerInputDateEUValidation": { "description": "Specifies the date formatting rules used in Europe for a text field input by the signer. If set, this validation is mandatory. The date format follows `DD/MM/YYYY` pattern.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input uses the European date format `DD/MM/YYYY`.", "type": "string", "example": "date_eu", "enum": [ "date_eu" ] } }, "title": "Sign Request Signer Input Date EU Validation" }, "SignRequestSignerInputDateISOValidation": { "description": "Specifies the ISO date formatting rules for a text field input by the signer. If set, this validation is mandatory. The date format follows `YYYY-MM-DD` pattern.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input uses the ISO date format `YYYY-MM-DD`.", "type": "string", "example": "date_iso", "enum": [ "date_iso" ] } }, "title": "Sign Request Signer Input Date ISO Validation" }, "SignRequestSignerInputDateUSValidation": { "description": "Specifies the US date formatting rules for a text field input by the signer. If set, this validation is mandatory. The date format follows `MM/DD/YYYY` pattern.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input uses the US date format `MM/DD/YYYY`.", "type": "string", "example": "date_us", "enum": [ "date_us" ] } }, "title": "Sign Request Signer Input Date US Validation" }, "SignRequestSignerInputEmailValidation": { "description": "Specifies the formatting rules that signers must follow for text field inputs. If set, this validation is mandatory.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input is an email address.", "type": "string", "example": "email", "enum": [ "email" ] } }, "required": [ "validation_type" ], "title": "Sign Request Signer Input Email Validation" }, "SignRequestSignerInputNumberWithCommaValidation": { "description": "Specifies the number with comma formatting rules for a text field input by the signer. If set, this validation is mandatory.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input uses a number format with a comma as the decimal separator (for example, 1,23).", "type": "string", "example": "number_with_comma", "enum": [ "number_with_comma" ] } }, "title": "Sign Request Signer Input Number With Comma Validation" }, "SignRequestSignerInputNumberWithPeriodValidation": { "description": "Specifies the number with period formatting rules for a text field input by the signer. If set, this validation is mandatory.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input uses a number format with a period as the decimal separator (for example, 1.23).", "type": "string", "example": "number_with_period", "enum": [ "number_with_period" ] } }, "title": "Sign Request Signer Input Number With Period Validation" }, "SignRequestSignerInputSSNValidation": { "description": "Specifies the validation rules for a text field input by the signer. If set, this validation is mandatory.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input is a Social Security Number (SSN).", "type": "string", "example": "ssn", "enum": [ "ssn" ] } }, "required": [ "validation_type" ], "title": "Sign Request Signer Input SSN Validation" }, "SignRequestSignerInputValidation": { "description": "Specifies the formatting rules that signers must follow for text field inputs. If set, this validation is mandatory. The format can be selected from a predefined list of options (e.g., email, phone number, date) or defined using a custom regular expression.", "oneOf": [ { "$ref": "#/components/schemas/SignRequestSignerInputEmailValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputCustomValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputZIPValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputZIP4Validation" }, { "$ref": "#/components/schemas/SignRequestSignerInputSSNValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputNumberWithPeriodValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputNumberWithCommaValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputDateISOValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputDateUSValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputDateEUValidation" }, { "$ref": "#/components/schemas/SignRequestSignerInputDateAsiaValidation" } ], "title": "Sign Request Signer Input Validation" }, "SignRequestSignerInputZIP4Validation": { "description": "Specifies the validation rules for a text field input by the signer. If set, this validation is mandatory.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input is a ZIP+4 code.", "type": "string", "example": "zip_4", "enum": [ "zip_4" ] } }, "required": [ "validation_type" ], "title": "Sign Request Signer Input ZIP 4 Validation" }, "SignRequestSignerInputZIPValidation": { "description": "Specifies the validation rules for a text field input by the signer. If set, this validation is mandatory.", "type": "object", "properties": { "validation_type": { "description": "Validates that the text input is a ZIP code.", "type": "string", "example": "zip", "enum": [ "zip" ] } }, "required": [ "validation_type" ], "title": "Sign Request Signer Input ZIP Validation" }, "SignTemplate": { "description": "A Box Sign template object.", "type": "object", "allOf": [ { "properties": { "type": { "description": "The value will always be `sign-template`.", "type": "string", "example": "sign-template", "enum": [ "sign-template" ] }, "id": { "description": "Template identifier.", "type": "string", "example": "4206996024-14944f75-c34b-478a-95a1-264b1ff80d35" }, "name": { "description": "The name of the template.", "type": "string", "example": "Official contract", "nullable": true }, "email_subject": { "description": "Subject of signature request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.", "type": "string", "example": "Sign Request from Acme", "nullable": true }, "email_message": { "description": "Message to include in signature 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.", "type": "string", "example": "Hello! Please sign the document below", "nullable": true }, "days_valid": { "description": "Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.", "type": "integer", "example": 2, "maximum": 730, "minimum": 0, "nullable": true }, "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." } ] }, "source_files": { "description": "List of files to create a signing document from. Only the ID and type fields are required for each file.", "type": "array", "items": { "$ref": "#/components/schemas/File--Mini" } }, "are_fields_locked": { "description": "Indicates if the template input fields are editable or not.", "type": "boolean", "example": false }, "are_options_locked": { "description": "Indicates if the template document options are editable or not, for example renaming the document.", "type": "boolean", "example": true }, "are_recipients_locked": { "description": "Indicates if the template signers are editable or not.", "type": "boolean", "example": false }, "are_email_settings_locked": { "description": "Indicates if the template email settings are editable or not.", "type": "boolean", "example": true }, "are_files_locked": { "description": "Indicates if the template files are editable or not. This includes deleting or renaming template files.", "type": "boolean", "example": true }, "signers": { "description": "Array of signers for the template.\n\n**Note**: It may happen that some signers specified in the template belong to conflicting [segments](/reference/resources/shield-information-barrier-segment-member) (user groups). This means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts. In such a case, an attempt to send a sign request based on a template that lists signers in conflicting segments will result in an error.\n\nRead more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ).", "type": "array", "items": { "$ref": "#/components/schemas/TemplateSigner" } }, "additional_info": { "description": "Additional information on which fields are required and which fields are not editable.", "type": "object", "properties": { "non_editable": { "description": "Non editable fields.", "type": "array", "items": { "type": "string", "enum": [ "email_subject", "email_message", "name", "days_valid", "signers", "source_files" ] }, "example": [ "email_subject", "name" ] }, "required": { "description": "Required fields.", "type": "object", "properties": { "signers": { "description": "Required signer fields.", "type": "array", "items": { "type": "array", "items": { "type": "string", "enum": [ "email" ] }, "example": [ "email" ] }, "example": [ [ "email" ], [ "email" ] ] } } } } }, "ready_sign_link": { "description": "Box's ready-sign link feature enables you to create a link to a signature request that you've created from a template. Use this link when you want to post a signature request on a public form — such as an email, social media post, or web page — without knowing who the signers will be. Note: The ready-sign link feature is limited to Enterprise Plus customers and not available to Box Verified Enterprises.", "type": "object", "nullable": true, "properties": { "url": { "description": "The URL that can be sent to signers.", "type": "string", "example": "\"https://app.box.com/sign/\nready-sign-link/a1cdf2c7-fa81-4a67-8163-1e5f4dbe5178\"" }, "name": { "description": "Request name.", "type": "string", "example": "Official contract", "nullable": true }, "instructions": { "description": "Extra instructions for all signers.", "type": "string", "example": "Hello! Please sign the document below", "nullable": true }, "folder_id": { "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.", "type": "string", "example": "12345", "nullable": true }, "is_notification_disabled": { "description": "Whether to disable notifications when a signer has signed.", "type": "boolean", "example": true }, "is_active": { "description": "Whether the ready sign link is enabled or not.", "type": "boolean", "example": false } } }, "custom_branding": { "description": "Custom branding applied to notifications and signature requests.", "type": "object", "nullable": true, "properties": { "company_name": { "description": "Name of the company.", "type": "string", "example": "Corporation inc.", "nullable": true }, "logo_uri": { "description": "Custom branding logo URI in the form of a base64 image.", "type": "string", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA\nAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A\n8AAQUBAScY42YAAAAASUVORK5CYII=", "nullable": true }, "branding_color": { "description": "Custom branding color in hex.", "type": "string", "example": "9E5E6F", "nullable": true }, "email_footer_text": { "description": "Content of the email footer.", "type": "string", "example": "Contact email email@mail.com", "nullable": true } } }, "request_flow": { "description": "The sign flow of sign requests created from the template. Values can include `standard` or `cfr11`.", "type": "string", "example": "standard", "nullable": true } } } ], "title": "Box Sign template", "x-box-resource-id": "sign_template", "x-box-tag": "sign_templates" }, "SignTemplates": { "description": "A list of templates, as returned from any Box Sign API endpoints by default.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of templates.", "type": "array", "items": { "$ref": "#/components/schemas/SignTemplate" } } } } ], "title": "Box Sign templates", "x-box-resource-id": "sign_templates", "x-box-tag": "sign_templates" }, "SkillCard": { "description": "Box Skill card.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KeywordSkillCard" }, { "$ref": "#/components/schemas/TimelineSkillCard" }, { "$ref": "#/components/schemas/TranscriptSkillCard" }, { "$ref": "#/components/schemas/StatusSkillCard" } ], "title": "Box Skill card" }, "SkillCardsMetadata": { "description": "The metadata assigned to a using for Box skills.", "type": "object", "properties": { "$canEdit": { "description": "Whether the user can edit this metadata.", "type": "boolean", "example": true }, "$id": { "description": "A UUID to identify the metadata object.", "type": "string", "format": "uuid", "example": "01234500-12f1-1234-aa12-b1d234cb567e", "maxLength": 36 }, "$parent": { "description": "An ID for the parent folder.", "type": "string", "example": "folder_59449484661," }, "$scope": { "description": "An ID for the scope in which this template has been applied.", "type": "string", "example": "enterprise_27335" }, "$template": { "description": "The name of the template.", "type": "string", "example": "properties" }, "$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.", "type": "string", "example": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0" }, "$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.", "type": "integer", "example": 2 }, "$version": { "description": "The version of the metadata object. Starts at 0 and increases every time a user-defined property is modified.", "type": "integer", "example": 1 }, "cards": { "description": "A list of Box Skill cards that have been applied to this file.", "type": "array", "items": { "$ref": "#/components/schemas/SkillCard" } } }, "title": "Skills metadata instance", "x-box-resource-id": "skill_cards_metadata", "x-box-tag": "skills" }, "StatusSkillCard": { "description": "A Box Skill metadata card that puts a status message in the metadata sidebar.", "type": "object", "properties": { "created_at": { "description": "The optional date and time this card was created at.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00" }, "type": { "description": "The value will always be `skill_card`.", "type": "string", "example": "skill_card", "enum": [ "skill_card" ] }, "skill_card_type": { "description": "The value will always be `status`.", "type": "string", "example": "status", "enum": [ "status" ] }, "skill_card_title": { "description": "The title of the card.", "type": "object", "properties": { "code": { "description": "An optional identifier for the title.", "type": "string", "example": "status" }, "message": { "description": "The actual title to show in the UI.", "type": "string", "example": "Status" } }, "required": [ "message" ] }, "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.", "type": "object", "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.", "type": "string", "example": "success", "enum": [ "invoked", "processing", "success", "transient_failure", "permanent_failure" ] }, "message": { "description": "A custom message that can be provided with this status. This will be shown in the web app to the end user.", "type": "string", "example": "We're preparing to process your file. Please hold on!" } }, "required": [ "code" ] }, "skill": { "description": "The service that applied this metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `service`.", "type": "string", "example": "service", "enum": [ "service" ] }, "id": { "description": "A custom identifier that represent the service that applied this metadata.", "type": "string", "example": "image-recognition-service" } }, "required": [ "type", "id" ] }, "invocation": { "description": "The invocation of this service, used to track which instance of a service applied the metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `skill_invocation`.", "type": "string", "example": "skill_invocation", "enum": [ "skill_invocation" ] }, "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.", "type": "string", "example": "image-recognition-service-123" } }, "required": [ "type", "id" ] } }, "required": [ "type", "skill_card_type", "skill", "invocation", "status" ], "title": "Status Skill Card", "x-box-resource-id": "status_skill_card", "x-box-tag": "skills" }, "StoragePolicies": { "description": "A list of storage policies.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of storage policies.", "type": "array", "items": { "$ref": "#/components/schemas/StoragePolicy" } } } } ], "title": "Storage policies", "x-box-resource-id": "storage_policies", "x-box-tag": "storage_policies" }, "StoragePolicy": { "description": "The Storage Policy object describes the storage zone.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/StoragePolicy--Mini" }, { "properties": { "name": { "description": "A descriptive name of the region.", "type": "string", "example": "Montreal / Dublin" } } } ], "title": "Storage policy", "x-box-resource-id": "storage_policy", "x-box-tag": "storage_policies", "x-box-variant": "standard" }, "StoragePolicy--Mini": { "description": "A mini description of a Storage Policy object.", "type": "object", "properties": { "id": { "description": "The unique identifier for this storage policy.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `storage_policy`.", "type": "string", "example": "storage_policy", "enum": [ "storage_policy" ] } }, "required": [ "id", "type" ], "title": "Storage policy (Mini)", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for a storage policy assignment.", "type": "string", "example": "ZW50ZXJwcmlzZV8xMjM0NTY3ODkw" }, "type": { "description": "The value will always be `storage_policy_assignment`.", "type": "string", "example": "storage_policy_assignment", "enum": [ "storage_policy_assignment" ] }, "storage_policy": { "allOf": [ { "$ref": "#/components/schemas/StoragePolicy--Mini" }, { "description": "The assigned storage policy." } ] }, "assigned_to": { "allOf": [ { "title": "Reference", "description": "The bare basic reference for an object.", "type": "object", "properties": { "id": { "description": "The unique identifier for this object.", "type": "string", "example": "11446498" }, "type": { "description": "The type for this object.", "type": "string", "example": "file" } } }, { "description": "The enterprise or use the policy is assigned to." } ] } }, "required": [ "id", "type" ], "title": "Storage policy assignment", "x-box-resource-id": "storage_policy_assignment", "x-box-tag": "storage_policy_assignments" }, "StoragePolicyAssignments": { "description": "A list of storage policy assignments.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of storage policy assignments.", "type": "array", "items": { "$ref": "#/components/schemas/StoragePolicyAssignment" } } } } ], "title": "Storage policy assignments", "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.", "type": "object", "properties": { "id": { "description": "The unique identifier for this task.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `task`.", "type": "string", "example": "task", "enum": [ "task" ] }, "item": { "allOf": [ { "$ref": "#/components/schemas/File--Mini" }, { "description": "The file associated with the task." } ] }, "due_at": { "description": "When the task is due.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "action": { "description": "The type of task the task assignee will be prompted to perform.", "type": "string", "example": "review", "enum": [ "review", "complete" ] }, "message": { "description": "A message that will be included with the task.", "type": "string", "example": "Legal review" }, "task_assignment_collection": { "allOf": [ { "$ref": "#/components/schemas/TaskAssignments" }, { "description": "A collection of task assignment objects associated with the task." } ] }, "is_completed": { "description": "Whether the task has been completed.", "type": "boolean", "example": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created the task." } ] }, "created_at": { "description": "When the task object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "completion_rule": { "description": "Defines which assignees need to complete this task before the task is considered completed.\n\n- `all_assignees` requires all assignees to review or approve the task in order for it to be considered completed.\n- `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed.", "type": "string", "example": "all_assignees", "enum": [ "all_assignees", "any_assignee" ] } }, "title": "Task", "x-box-resource-id": "task", "x-box-tag": "tasks" }, "TaskAssignment": { "description": "A task assignment defines which task is assigned to which user to complete.", "type": "object", "properties": { "id": { "description": "The unique identifier for this task assignment.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `task_assignment`.", "type": "string", "example": "task_assignment", "enum": [ "task_assignment" ] }, "item": { "allOf": [ { "$ref": "#/components/schemas/File--Mini" }, { "description": "The file that the task has been assigned to." } ] }, "assigned_to": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user 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.", "type": "string", "example": "Please review" }, "completed_at": { "description": "The date at which this task assignment was completed. This will be `null` if the task is not completed yet.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "assigned_at": { "description": "The date at which this task was assigned to the user.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "reminded_at": { "description": "The date at which the assigned user was reminded of this task assignment.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "resolution_state": { "description": "The current state of the assignment. The available states depend on the `action` value of the task object.", "type": "string", "example": "incomplete", "enum": [ "completed", "incomplete", "approved", "rejected" ] }, "assigned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who assigned this task." } ] } }, "title": "Task assignment", "x-box-resource-id": "task_assignment", "x-box-tag": "task_assignments" }, "TaskAssignments": { "description": "A list of task assignments.", "type": "object", "properties": { "total_count": { "description": "The total number of items in this collection.", "type": "integer", "format": "int64", "example": 100 }, "entries": { "description": "A list of task assignments.", "type": "array", "items": { "$ref": "#/components/schemas/TaskAssignment" } } }, "title": "Task assignments", "x-box-resource-id": "task_assignments", "x-box-tag": "task_assignments" }, "Tasks": { "description": "A list of tasks.", "type": "object", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.", "type": "integer", "format": "int64", "example": 5000 }, "entries": { "description": "A list of tasks.", "type": "array", "items": { "$ref": "#/components/schemas/Task" } } }, "title": "Tasks", "x-box-resource-id": "tasks", "x-box-tag": "tasks" }, "TemplateSigner": { "description": "The schema for a Signer for Templates.", "type": "object", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateSignerInput" }, "readOnly": true }, "email": { "description": "Email address of the signer.", "type": "string", "example": "example@mail.com", "nullable": true }, "role": { "description": "Defines the role of the signer in the signature request. A role of `signer` needs to sign the document, a role `approver` approves the document and a `final_copy_reader` role only receives the final signed document and signing log.", "type": "string", "example": "signer", "default": "signer", "enum": [ "signer", "approver", "final_copy_reader" ] }, "is_in_person": { "description": "Used in combination with an embed URL for a sender. After the sender signs, they will be redirected to the next `in_person` signer.", "type": "boolean", "example": true }, "order": { "description": "Order of the signer.", "type": "integer", "example": 2, "minimum": 0 }, "signer_group_id": { "description": "If provided, this value points signers that are assigned the same inputs and belongs to same signer group. A signer group is not a Box Group. It is an entity that belongs to the template itself and can only be used within Box Sign requests created from it.", "type": "string", "example": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7", "nullable": true }, "label": { "description": "A placeholder label for the signer set by the template creator to differentiate between signers.", "type": "string", "example": "Jane Doe", "nullable": true }, "public_id": { "description": "An identifier for the signer. This can be used to identify a signer within the template.", "type": "string", "example": "RJZYYVPR" }, "is_password_required": { "description": "If true for signers with a defined email, the password provided when the template was created is used by default. If true for signers without a specified / defined email, the creator needs to provide a password when using the template.", "type": "boolean", "example": true, "nullable": true }, "is_phone_number_required": { "description": "If true for signers with a defined email, the phone number provided when the template was created is used by default. If true for signers without a specified / defined email, the template creator needs to provide a phone number when creating a request.", "type": "boolean", "example": true, "nullable": true }, "login_required": { "description": "If true, the signer is required to login to access the document.", "type": "boolean", "example": true, "nullable": true } }, "title": "Signer fields for Templates" }, "TemplateSignerInput": { "description": "Input created by a Signer on a Template.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SignRequestPrefillTag" }, { "properties": { "type": { "description": "Type of input.", "type": "string", "example": "text", "enum": [ "signature", "date", "text", "checkbox", "attachment", "radio", "dropdown" ] }, "content_type": { "description": "Content type of input.", "type": "string", "example": "text", "enum": [ "signature", "initial", "stamp", "date", "checkbox", "text", "full_name", "first_name", "last_name", "company", "title", "email", "attachment", "radio", "dropdown" ] }, "is_required": { "description": "Whether or not the input is required.", "type": "boolean", "example": true }, "page_index": { "description": "Index of page that the input is on.", "type": "integer", "example": 4 }, "document_id": { "description": "Document identifier.", "type": "string", "example": "123075213-eb54b537-8b25-445e-87c1-5a1c67d8cbd7", "nullable": true }, "dropdown_choices": { "description": "When the input is of the type `dropdown` this values will be filled with all the dropdown options.", "type": "array", "items": { "type": "string" }, "example": [ "Yes", "No", "Maybe" ], "nullable": true }, "group_id": { "description": "When the input is of type `radio` they can be grouped to gather with this identifier.", "type": "string", "example": "da317330-225a-4c72-89ad-0d6dcaaf4df6", "nullable": true }, "coordinates": { "description": "Where the input is located on a page.", "type": "object", "properties": { "x": { "description": "Relative x coordinate to the page the input is on, ranging from 0 to 1.", "type": "number", "example": 0.672258592471358 }, "y": { "description": "Relative y coordinate to the page the input is on, ranging from 0 to 1.", "type": "number", "example": 0.18654283173599448 } } }, "dimensions": { "description": "The size of the input.", "type": "object", "properties": { "width": { "description": "Relative width to the page the input is on, ranging from 0 to 1.", "type": "number", "example": 0.2618657937806874 }, "height": { "description": "Relative height to the page the input is on, ranging from 0 to 1.", "type": "number", "example": 0.05311728090109673 } } }, "label": { "description": "The label field is used especially for text, attachment, radio, and checkbox type inputs.", "type": "string", "example": "Legal name", "nullable": true }, "read_only": { "description": "Indicates whether this input is read-only (cannot be modified by signers).", "type": "boolean", "example": true }, "validation": { "description": "Specifies the formatting rules that signers must follow for text field inputs. If set, this validation is mandatory.", "example": { "validation_type": "email" }, "anyOf": [ { "$ref": "#/components/schemas/SignRequestSignerInputValidation" }, { "title": "OpenAPI 3.0 null schema type", "description": "The definition for a null schema type in OpenAPI `3.0`.", "type": "object", "nullable": true, "additionalProperties": false } ] } } } ], "required": [ "page_index" ], "title": "Template Signer Input" }, "TermsOfService": { "description": "The root-level record that is supposed to represent a single Terms of Service.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/TermsOfService--Base" }, { "properties": { "status": { "description": "Whether these terms are enabled or not.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise.", "properties": { "id": { "description": "The unique identifier for this enterprise.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise.", "type": "string", "example": "Acme Inc." } } }, { "description": "The enterprise these terms apply to." } ] }, "tos_type": { "description": "Whether to apply these terms to managed users or external users.", "type": "string", "example": "managed", "enum": [ "managed", "external" ] }, "text": { "description": "The text for your terms and conditions. This text could be empty if the `status` is set to `disabled`.", "type": "string", "example": "By using this service, you agree to ..." }, "created_at": { "description": "When the legal item was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the legal item was modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } } } ], "title": "Terms of service", "x-box-resource-id": "terms_of_service", "x-box-tag": "terms_of_services", "x-box-variant": "standard" }, "TermsOfService--Base": { "description": "The root-level record that is supposed to represent a single Terms of Service.", "type": "object", "properties": { "id": { "description": "The unique identifier for this terms of service.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `terms_of_service`.", "type": "string", "example": "terms_of_service", "enum": [ "terms_of_service" ] } }, "required": [ "id", "type" ], "title": "Terms of service (Base)", "x-box-resource-id": "terms_of_service--base", "x-box-tag": "terms_of_services", "x-box-variant": "base", "x-box-variants": [ "base", "standard" ] }, "TermsOfServices": { "description": "A list of terms of services.", "type": "object", "properties": { "total_count": { "description": "The total number of objects.", "type": "integer", "format": "int64", "example": 2 }, "entries": { "description": "A list of terms of service objects.", "type": "array", "items": { "$ref": "#/components/schemas/TermsOfService" } } }, "title": "Terms of services", "x-box-resource-id": "terms_of_services", "x-box-tag": "terms_of_services" }, "TermsOfServiceUserStatus": { "description": "The association between a Terms of Service and a user.", "type": "object", "properties": { "id": { "description": "The unique identifier for this terms of service user status.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `terms_of_service_user_status`.", "type": "string", "example": "terms_of_service_user_status", "enum": [ "terms_of_service_user_status" ] }, "tos": { "allOf": [ { "$ref": "#/components/schemas/TermsOfService--Base" }, { "description": "The terms of service." } ] }, "user": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user." } ] }, "is_accepted": { "description": "If the user has accepted the terms of services.", "type": "boolean", "example": true }, "created_at": { "description": "When the legal item was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the legal item was modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } }, "required": [ "id", "type" ], "title": "Terms of service user status", "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.", "type": "object", "properties": { "total_count": { "description": "The total number of objects.", "type": "integer", "format": "int64", "example": 2 }, "entries": { "description": "A list of terms of service user statuses.", "type": "array", "items": { "$ref": "#/components/schemas/TermsOfServiceUserStatus" } } }, "title": "Terms of service user statuses", "x-box-resource-id": "terms_of_services_user_statuses", "x-box-tag": "terms_of_service_user_statuses" }, "TimelineSkillCard": { "description": "A Box Skill metadata card that places a list of images on a timeline.", "type": "object", "properties": { "created_at": { "description": "The optional date and time this card was created at.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00" }, "type": { "description": "The value will always be `skill_card`.", "type": "string", "example": "skill_card", "enum": [ "skill_card" ] }, "skill_card_type": { "description": "The value will always be `timeline`.", "type": "string", "example": "timeline", "enum": [ "timeline" ] }, "skill_card_title": { "description": "The title of the card.", "type": "object", "properties": { "code": { "description": "An optional identifier for the title.", "type": "string", "example": "Faces" }, "message": { "description": "The actual title to show in the UI.", "type": "string", "example": "Faces" } }, "required": [ "message" ] }, "skill": { "description": "The service that applied this metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `service`.", "type": "string", "example": "service", "enum": [ "service" ] }, "id": { "description": "A custom identifier that represent the service that applied this metadata.", "type": "string", "example": "image-recognition-service" } }, "required": [ "type", "id" ] }, "invocation": { "description": "The invocation of this service, used to track which instance of a service applied the metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `skill_invocation`.", "type": "string", "example": "skill_invocation", "enum": [ "skill_invocation" ] }, "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.", "type": "string", "example": "image-recognition-service-123" } }, "required": [ "type", "id" ] }, "duration": { "description": "An total duration in seconds of the timeline.", "type": "integer", "example": 1000 }, "entries": { "description": "A list of entries on the timeline.", "type": "array", "items": { "type": "object", "description": "An single item that's placed on multiple items on the timeline.", "properties": { "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.", "type": "string", "example": "John" }, "appears": { "description": "Defines a list of timestamps for when this item should appear on the timeline.", "type": "array", "items": { "type": "object", "description": "The timestamp for an entry.", "properties": { "start": { "description": "The time in seconds when an entry should start appearing on a timeline.", "type": "integer", "example": 1 }, "end": { "description": "The time in seconds when an entry should stop appearing on a timeline.", "type": "integer", "example": 20 } } }, "required": [ "start", "end" ] }, "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.\n\nThe 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.", "type": "string", "example": "https://example.com/image1.jpg" } } } } }, "required": [ "type", "skill_card_type", "skill", "invocation", "entries" ], "title": "Timeline Skill Card", "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.", "type": "object", "properties": { "type": { "description": "The value will always be `tracking_code`.", "type": "string", "example": "tracking_code", "enum": [ "tracking_code" ] }, "name": { "description": "The name of the tracking code, which must be preconfigured in the Admin Console.", "type": "string", "example": "department" }, "value": { "description": "The value of the tracking code.", "type": "string", "example": "Sales" } }, "title": "Tracking code" }, "TranscriptSkillCard": { "description": "A Box Skill metadata card that adds a transcript to a file.", "type": "object", "properties": { "created_at": { "description": "The optional date and time this card was created at.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00" }, "type": { "description": "The value will always be `skill_card`.", "type": "string", "example": "skill_card", "enum": [ "skill_card" ] }, "skill_card_type": { "description": "The value will always be `transcript`.", "type": "string", "example": "transcript", "enum": [ "transcript" ] }, "skill_card_title": { "description": "The title of the card.", "type": "object", "properties": { "code": { "description": "An optional identifier for the title.", "type": "string", "example": "my_transcripts" }, "message": { "description": "The actual title to show in the UI.", "type": "string", "example": "My Transcripts" } }, "required": [ "message" ] }, "skill": { "description": "The service that applied this metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `service`.", "type": "string", "example": "service", "enum": [ "service" ] }, "id": { "description": "A custom identifier that represent the service that applied this metadata.", "type": "string", "example": "transciption-service" } }, "required": [ "type", "id" ] }, "invocation": { "description": "The invocation of this service, used to track which instance of a service applied the metadata.", "type": "object", "properties": { "type": { "description": "The value will always be `skill_invocation`.", "type": "string", "example": "skill_invocation", "enum": [ "skill_invocation" ] }, "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.", "type": "string", "example": "transciption-service-123" } }, "required": [ "type", "id" ] }, "duration": { "description": "An optional total duration in seconds.\n\nUsed with a `skill_card_type` of `transcript` or `timeline`.", "type": "integer", "example": 1000 }, "entries": { "description": "An list of entries for the card. This represents the individual entries of the transcription.", "type": "array", "items": { "type": "object", "description": "An entry in the `entries` attribute of a metadata card.", "properties": { "text": { "description": "The text of the entry. This would be the transcribed text assigned to the entry on the timeline.", "type": "string", "example": "Hi, and welcome to this video..." }, "appears": { "description": "Defines when a transcribed bit of text appears. This only includes a start time and no end time.", "type": "array", "items": { "type": "object", "description": "The timestamp for an entry.", "properties": { "start": { "description": "The time in seconds when an entry should start appearing on a timeline.", "type": "integer", "example": 1 } } }, "required": [ "start" ] } } } } }, "required": [ "type", "skill_card_type", "skill", "invocation", "entries" ], "title": "Transcript Skill Card.", "x-box-resource-id": "transcript_skill_card", "x-box-tag": "skills" }, "TrashFile": { "description": "Represents a trashed file.", "type": "object", "properties": { "id": { "description": "The unique identifier that represent a file.\n\nThe 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`.", "type": "string", "example": "123456789", "nullable": false }, "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.", "type": "string", "example": "1", "nullable": true }, "type": { "description": "The value will always be `file`.", "type": "string", "example": "file", "enum": [ "file" ], "nullable": false }, "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "name": { "description": "The name of the file.", "type": "string", "example": "Contract.pdf" }, "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.", "type": "string", "format": "digest", "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", "nullable": false }, "file_version": { "allOf": [ { "$ref": "#/components/schemas/FileVersion--Mini" }, { "description": "The information about the current version of the file." } ] }, "description": { "description": "The optional description of this file.", "type": "string", "example": "Contract for Q1 renewal", "maxLength": 256, "nullable": false }, "size": { "description": "The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.", "type": "integer", "example": 629644, "nullable": false }, "path_collection": { "allOf": [ { "title": "Path collection (Trash)", "description": "A list of parent folders for an item in the trash.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "Array of folders for this item's path collection.", "type": "array", "items": { "type": "object", "description": "The parent folder for this item.", "properties": { "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { "description": "The unique identifier that represent a folder.", "type": "string", "example": "123456789" }, "sequence_id": { "description": "This field is null for the Trash folder.", "type": "string", "example": null, "nullable": true }, "etag": { "description": "This field is null for the Trash folder.", "type": "string", "example": null, "nullable": true }, "name": { "description": "The name of the Trash folder.", "type": "string", "example": "Trash", "nullable": false } } } } } }, { "description": "The tree of folders that this file is contained in, starting at the root." }, { "nullable": false } ] }, "created_at": { "description": "The date and time when the file was created on Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": false }, "modified_at": { "description": "The date and time when the file was last updated on Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": false }, "trashed_at": { "description": "The time at which this file was put in the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { "description": "The time at which this file is expected to be purged from the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_created_at": { "description": "The date and time at which this file was originally created, which might be before it was uploaded to Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_modified_at": { "description": "The date and time at which this file was last updated, which might be before it was uploaded to Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this file." } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this file." }, { "nullable": false } ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this file." }, { "nullable": false } ] }, "shared_link": { "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.", "type": "string", "example": null, "nullable": true }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The folder that this file is located within." }, { "nullable": true } ] }, "item_status": { "description": "Defines if this item has been deleted or not.\n\n- `active` when the item has is not in the trash\n- `trashed` when the item has been moved to the trash but not deleted\n- `deleted` when the item has been permanently deleted.", "type": "string", "example": "trashed", "enum": [ "active", "trashed", "deleted" ], "nullable": false } }, "required": [ "id", "type", "sequence_id", "sha1", "description", "size", "path_collection", "created_at", "modified_at", "modified_by", "owned_by", "item_status" ], "title": "Trashed File", "x-box-resource-id": "trash_file", "x-box-tag": "trashed_files" }, "TrashFileRestored": { "description": "Represents a file restored from the trash.", "type": "object", "properties": { "id": { "description": "The unique identifier that represent a file.\n\nThe 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`.", "type": "string", "example": "123456789", "nullable": false }, "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.", "type": "string", "example": "1", "nullable": true }, "type": { "description": "The value will always be `file`.", "type": "string", "example": "file", "enum": [ "file" ], "nullable": false }, "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "name": { "description": "The name of the file.", "type": "string", "example": "Contract.pdf" }, "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.", "type": "string", "format": "digest", "example": "85136C79CBF9FE36BB9D05D0639C70C265C18D37", "nullable": false }, "file_version": { "allOf": [ { "$ref": "#/components/schemas/FileVersion--Mini" }, { "description": "The information about the current version of the file." } ] }, "description": { "description": "The optional description of this file.", "type": "string", "example": "Contract for Q1 renewal", "maxLength": 256, "nullable": false }, "size": { "description": "The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow.", "type": "integer", "example": 629644, "nullable": false }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "The parent folders for this item.", "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" }, "nullable": false } } }, { "description": "The tree of folders that this file is contained in, starting at the root." }, { "nullable": false } ] }, "created_at": { "description": "The date and time when the file was created on Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": false }, "modified_at": { "description": "The date and time when the file was last updated on Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": false }, "trashed_at": { "description": "The time at which this file was put in the trash - becomes `null` after restore.", "type": "string", "example": null, "nullable": true }, "purged_at": { "description": "The time at which this file is expected to be purged from the trash - becomes `null` after restore.", "type": "string", "example": null, "nullable": true }, "content_created_at": { "description": "The date and time at which this file was originally created, which might be before it was uploaded to Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_modified_at": { "description": "The date and time at which this file was last updated, which might be before it was uploaded to Box.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this file." } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this file." }, { "nullable": false } ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this file." }, { "nullable": false } ] }, "shared_link": { "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.", "type": "string", "example": null, "nullable": true }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The folder that this file is located within." }, { "nullable": true } ] }, "item_status": { "description": "Defines if this item has been deleted or not.\n\n- `active` when the item has is not in the trash\n- `trashed` when the item has been moved to the trash but not deleted\n- `deleted` when the item has been permanently deleted.", "type": "string", "example": "active", "enum": [ "active", "trashed", "deleted" ], "nullable": false } }, "required": [ "id", "type", "sequence_id", "sha1", "description", "size", "path_collection", "created_at", "modified_at", "modified_by", "owned_by", "item_status" ], "title": "Trashed File (Restored)", "x-box-resource-id": "trash_file_restored", "x-box-tag": "trashed_files" }, "TrashFolder": { "description": "Represents a trashed folder.", "type": "object", "properties": { "id": { "description": "The unique identifier that represent a folder.\n\nThe 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`.", "type": "string", "example": "123456789", "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.", "type": "string", "example": "1", "nullable": true }, "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ], "nullable": false }, "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "name": { "description": "The name of the folder.", "type": "string", "example": "Contracts", "nullable": false }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "description": { "allOf": [ { "type": "string", "description": "The optional description of this folder.", "maxLength": 256, "example": "Legal contracts for the new ACME deal", "nullable": false }, { "nullable": false } ] }, "size": { "description": "The folder size in bytes.\n\nBe careful parsing this integer as its value can get very large.", "type": "integer", "format": "int64", "example": 629644, "nullable": false }, "path_collection": { "allOf": [ { "title": "Path collection (Trash)", "description": "A list of parent folders for an item in the trash.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "Array of folders for this item's path collection.", "type": "array", "items": { "type": "object", "description": "The parent folder for this item.", "properties": { "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { "description": "The unique identifier that represent a folder.", "type": "string", "example": "123456789" }, "sequence_id": { "description": "This field is null for the Trash folder.", "type": "string", "example": null, "nullable": true }, "etag": { "description": "This field is null for the Trash folder.", "type": "string", "example": null, "nullable": true }, "name": { "description": "The name of the Trash folder.", "type": "string", "example": "Trash", "nullable": false } } } } } }, { "description": "The tree of folders that this file is contained in, starting at the root." }, { "nullable": false } ] }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this folder." }, { "nullable": false } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this folder." }, { "nullable": false } ] }, "trashed_at": { "description": "The time at which this folder was put in the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { "description": "The time at which this folder is expected to be purged from the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_created_at": { "description": "The date and time at which this folder was originally created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_modified_at": { "description": "The date and time at which this folder was last updated.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this folder." }, { "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.", "type": "string", "example": null, "nullable": true }, "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.", "type": "string", "example": null, "nullable": true }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the root folder or the trash folder." }, { "nullable": true } ] }, "item_status": { "description": "Defines if this item has been deleted or not.\n\n- `active` when the item has is not in the trash\n- `trashed` when the item has been moved to the trash but not deleted\n- `deleted` when the item has been permanently deleted.", "type": "string", "example": "trashed", "enum": [ "active", "trashed", "deleted" ], "nullable": false } }, "required": [ "id", "type", "name", "description", "size", "path_collection", "created_by", "modified_by", "owned_by", "item_status" ], "title": "Trashed Folder", "x-box-resource-id": "trash_folder", "x-box-tag": "trashed_folders" }, "TrashFolderRestored": { "description": "Represents a folder restored from the trash.", "type": "object", "properties": { "id": { "description": "The unique identifier that represent a folder.\n\nThe 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`.", "type": "string", "example": "123456789", "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.", "type": "string", "example": "1", "nullable": true }, "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ], "nullable": false }, "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "name": { "description": "The name of the folder.", "type": "string", "example": "Contracts", "nullable": false }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "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.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "description": { "allOf": [ { "type": "string", "description": "The optional description of this folder.", "maxLength": 256, "example": "Legal contracts for the new ACME deal", "nullable": false }, { "nullable": false } ] }, "size": { "description": "The folder size in bytes.\n\nBe careful parsing this integer as its value can get very large.", "type": "integer", "format": "int64", "example": 629644, "nullable": false }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "The parent folders for this item.", "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" }, "nullable": false } } }, { "description": "The tree of folders that this file is contained in, starting at the root." }, { "nullable": false } ] }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this folder." }, { "nullable": false } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this folder." }, { "nullable": false } ] }, "trashed_at": { "description": "The time at which this folder was put in the trash - becomes `null` after restore.", "type": "string", "example": null, "nullable": true }, "purged_at": { "description": "The time at which this folder is expected to be purged from the trash - becomes `null` after restore.", "type": "string", "example": null, "nullable": true }, "content_created_at": { "description": "The date and time at which this folder was originally created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "content_modified_at": { "description": "The date and time at which this folder was last updated.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this folder." }, { "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.", "type": "string", "example": null, "nullable": true }, "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.", "type": "string", "example": null, "nullable": true }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the root folder or the trash folder." }, { "nullable": true } ] }, "item_status": { "description": "Defines if this item has been deleted or not.\n\n- `active` when the item has is not in the trash,\n- `trashed` when the item has been moved to the trash but not deleted,\n- `deleted` when the item has been permanently deleted.", "type": "string", "example": "active", "enum": [ "active", "trashed", "deleted" ], "nullable": false } }, "title": "Trashed Folder (Restored)", "x-box-resource-id": "trash_folder_restored", "x-box-tag": "trashed_folders" }, "TrashWebLink": { "description": "Represents a trashed web link.", "type": "object", "properties": { "type": { "description": "The value will always be `web_link`.", "type": "string", "example": "web_link", "enum": [ "web_link" ] }, "id": { "description": "The unique identifier for this web link.", "type": "string", "example": "11446498" }, "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "etag": { "description": "The entity tag of this web link. Used with `If-Match` headers.", "type": "string", "example": "1" }, "name": { "description": "The name of the web link.", "type": "string", "example": "My Bookmark" }, "url": { "description": "The URL this web link points to.", "type": "string", "example": "https://www.example.com/example/1234" }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The parent object the web link belongs to." } ] }, "description": { "description": "The description accompanying the web link. This is visible within the Box web application.", "type": "string", "example": "Example page" }, "path_collection": { "allOf": [ { "title": "Path collection (Trash)", "description": "A list of parent folders for an item in the trash.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "Array of folders for this item's path collection.", "type": "array", "items": { "type": "object", "description": "The parent folder for this item.", "properties": { "type": { "description": "The value will always be `folder`.", "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { "description": "The unique identifier that represent a folder.", "type": "string", "example": "123456789" }, "sequence_id": { "description": "This field is null for the Trash folder.", "type": "string", "example": null, "nullable": true }, "etag": { "description": "This field is null for the Trash folder.", "type": "string", "example": null, "nullable": true }, "name": { "description": "The name of the Trash folder.", "type": "string", "example": "Trash", "nullable": false } } } } } }, { "description": "The tree of folders that this web link is contained in, starting at the root." }, { "nullable": false } ] }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this web link." } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this web link." } ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this web link." } ] }, "shared_link": { "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.", "type": "string", "example": null, "nullable": true }, "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.", "type": "string", "example": "trashed", "enum": [ "active", "trashed", "deleted" ] } }, "title": "Trashed Web Link", "x-box-resource-id": "trash_web_link", "x-box-tag": "trashed_web_links" }, "TrashWebLinkRestored": { "description": "Represents a web link restored from the trash.", "type": "object", "properties": { "type": { "description": "The value will always be `web_link`.", "type": "string", "example": "web_link", "enum": [ "web_link" ] }, "id": { "description": "The unique identifier for this web link.", "type": "string", "example": "11446498" }, "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "etag": { "description": "The entity tag of this web link. Used with `If-Match` headers.", "type": "string", "example": "1" }, "name": { "description": "The name of the web link.", "type": "string", "example": "My Bookmark" }, "url": { "description": "The URL this web link points to.", "type": "string", "example": "https://www.example.com/example/1234" }, "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The parent object the web link belongs to." } ] }, "description": { "description": "The description accompanying the web link. This is visible within the Box web application.", "type": "string", "example": "Example page" }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "The parent folders for this item.", "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" }, "nullable": false } } }, { "description": "The tree of folders that this web link is contained in, starting at the root." }, { "nullable": false } ] }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "trashed_at": { "description": "The time at which this bookmark was put in the trash - becomes `null` after restore.", "type": "string", "example": null, "nullable": true }, "purged_at": { "description": "The time at which this bookmark will be permanently deleted - becomes `null` after restore.", "type": "string", "example": null, "nullable": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this web link." } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this web link." } ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this web link." } ] }, "shared_link": { "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.", "type": "string", "example": null, "nullable": true }, "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.", "type": "string", "example": "trashed", "enum": [ "active", "trashed", "deleted" ] } }, "required": [ "sequence_id", "path_collection" ], "title": "Trashed Web Link (Restored)", "x-box-resource-id": "trash_web_link_restored", "x-box-tag": "trashed_web_links" }, "UploadedPart": { "description": "A chunk of a file uploaded as part of an upload session, as returned by some endpoints.", "type": "object", "properties": { "part": { "$ref": "#/components/schemas/UploadPart" } }, "title": "Uploaded part", "x-box-resource-id": "uploaded_part", "x-box-tag": "chunked_uploads" }, "UploadPart": { "description": "The representation of an upload session chunk.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UploadPart--Mini" }, { "properties": { "sha1": { "description": "The SHA1 hash of the chunk.", "type": "string", "example": "134b65991ed521fcfe4724b7d814ab8ded5185dc" } } } ], "title": "Upload part", "x-box-resource-id": "upload_part", "x-box-tag": "chunked_uploads", "x-box-variant": "standard" }, "UploadPart--Mini": { "description": "The basic representation of an upload session chunk.", "type": "object", "properties": { "part_id": { "description": "The unique ID of the chunk.", "type": "string", "example": "6F2D3486" }, "offset": { "description": "The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file.", "type": "integer", "format": "int64", "example": 16777216 }, "size": { "description": "The size of the chunk in bytes.", "type": "integer", "format": "int64", "example": 3222784 } }, "title": "Upload part (Mini)", "x-box-resource-id": "upload_part--mini", "x-box-tag": "chunked_uploads", "x-box-variant": "mini", "x-box-variants": [ "mini", "standard" ] }, "UploadParts": { "description": "A list of uploaded chunks for an upload session.", "type": "object", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "A list of uploaded chunks for an upload session.", "type": "array", "items": { "$ref": "#/components/schemas/UploadPart" } } } } ], "title": "Upload parts", "x-box-resource-id": "upload_parts", "x-box-tag": "chunked_uploads" }, "UploadSession": { "description": "An upload session for chunk uploading a file.", "type": "object", "properties": { "id": { "description": "The unique identifier for this session.", "type": "string", "example": "F971964745A5CD0C001BBE4E58196BFD" }, "type": { "description": "The value will always be `upload_session`.", "type": "string", "example": "upload_session", "enum": [ "upload_session" ] }, "session_expires_at": { "description": "The date and time when this session expires.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "part_size": { "description": "The size in bytes that must be used for all parts of of the upload.\n\nOnly the last part is allowed to be of a smaller size.", "type": "integer", "format": "int64", "example": 1024 }, "total_parts": { "description": "The total number of parts expected in this upload session, as determined by the file size and part size.", "type": "integer", "format": "int32", "example": 1000 }, "num_parts_processed": { "description": "The number of parts that have been uploaded and processed by the server. This starts at `0`.\n\nWhen committing a file files, inspecting this property can provide insight if all parts have been uploaded correctly.", "type": "integer", "format": "int32", "example": 455 }, "session_endpoints": { "allOf": [ { "title": "Session endpoints", "description": "A list of endpoints for a chunked upload session.", "type": "object", "properties": { "upload_part": { "description": "The URL to upload parts to.", "type": "string", "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" }, "commit": { "description": "The URL used to commit the file.", "type": "string", "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit" }, "abort": { "description": "The URL for used to abort the session.", "type": "string", "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" }, "list_parts": { "description": "The URL users to list all parts.", "type": "string", "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts" }, "status": { "description": "The URL used to get the status of the upload.", "type": "string", "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" }, "log_event": { "description": "The URL used to get the upload log from.", "type": "string", "example": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log" } } }, { "description": "A list of endpoints for this session." } ] } }, "title": "Upload session", "x-box-resource-id": "upload_session", "x-box-tag": "chunked_uploads" }, "UploadUrl": { "description": "The details for the upload session for the file.", "type": "object", "properties": { "upload_url": { "description": "A URL for an upload session that can be used to upload the file.", "type": "string", "example": "https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234" }, "upload_token": { "description": "An optional access token to use to upload the file.", "type": "string", "example": "Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP" } }, "title": "Upload URL", "x-box-resource-id": "upload_url", "x-box-tag": "uploads" }, "User": { "description": "A standard representation of a user, as returned from any user API endpoints by default.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "properties": { "created_at": { "description": "When the user object was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When the user object was last modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "language": { "description": "The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format.", "type": "string", "example": "en" }, "timezone": { "description": "The user's timezone.", "type": "string", "format": "timezone", "example": "Africa/Bujumbura" }, "space_amount": { "description": "The user’s total available space amount in bytes.", "type": "integer", "format": "int64", "example": 11345156112 }, "space_used": { "description": "The amount of space in use by the user.", "type": "integer", "format": "int64", "example": 1237009912 }, "max_upload_size": { "description": "The maximum individual file size in bytes the user can have.", "type": "integer", "format": "int64", "example": 2147483648 }, "status": { "description": "The user's account status.", "type": "string", "example": "active", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ] }, "job_title": { "description": "The user’s job title.", "type": "string", "example": "CEO", "maxLength": 100 }, "phone": { "description": "The user’s phone number.", "type": "string", "example": "6509241374", "maxLength": 100 }, "address": { "description": "The user’s address.", "type": "string", "example": "900 Jefferson Ave, Redwood City, CA 94063", "maxLength": 255 }, "avatar_url": { "description": "URL of the user’s avatar image.", "type": "string", "example": "https://www.box.com/api/avatar/large/181216415" }, "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.", "type": "object", "nullable": true, "properties": { "email": { "description": "The email address to send the notifications to.", "type": "string", "example": "notifications@example.com" }, "is_confirmed": { "description": "Specifies if this email address has been confirmed.", "type": "boolean", "example": true } } } } } ], "title": "User", "x-box-resource-id": "user", "x-box-tag": "users", "x-box-variant": "standard" }, "User--Base": { "description": "A mini representation of a user, used when nested within another resource.", "type": "object", "properties": { "id": { "description": "The unique identifier for this user.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `user`.", "type": "string", "example": "user", "enum": [ "user" ], "nullable": false } }, "required": [ "type", "id" ], "title": "User (Base)", "x-box-resource-id": "user--base", "x-box-tag": "users", "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard", "full" ] }, "User--Collaborations": { "description": "A mini representation of a user, can be returned only when the status is `pending`.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "properties": { "name": { "description": "The display name of this user. If the collaboration status is `pending`, an empty string is returned.", "type": "string", "example": "Aaron Levie", "maxLength": 50 }, "login": { "description": "The primary email address of this user. If the collaboration status is `pending`, a login value is returned.", "type": "string", "format": "email", "example": "ceo@example.com" }, "is_active": { "description": "If set to `false`, the user is either deactivated or deleted.", "type": "boolean", "example": true } } } ], "title": "User (Collaborations)", "x-box-resource-id": "user_collaborations", "x-box-tag": "users" }, "User--Full": { "description": "A full representation of a user, as can be returned from any user API endpoint.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User" }, { "properties": { "role": { "description": "The user’s enterprise role.", "type": "string", "example": "admin", "enum": [ "admin", "coadmin", "user" ] }, "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.", "type": "array", "items": { "$ref": "#/components/schemas/TrackingCode" } }, "can_see_managed_users": { "description": "Whether the user can see other enterprise users in their contact list.", "type": "boolean", "example": true }, "is_sync_enabled": { "description": "Whether the user can use Box Sync.", "type": "boolean", "example": true }, "is_external_collab_restricted": { "description": "Whether the user is allowed to collaborate with users outside their enterprise.", "type": "boolean", "example": true }, "is_exempt_from_device_limits": { "description": "Whether to exempt the user from Enterprise device limits.", "type": "boolean", "example": true }, "is_exempt_from_login_verification": { "description": "Whether the user must use two-factor authentication.", "type": "boolean", "example": true }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise.", "properties": { "id": { "description": "The unique identifier for this enterprise.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `enterprise`.", "type": "string", "example": "enterprise", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise.", "type": "string", "example": "Acme Inc." } } }, { "description": "Representation of the user’s enterprise." } ] }, "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.", "type": "array", "items": { "type": "string" }, "example": [ "important" ] }, "hostname": { "description": "The root (protocol, subdomain, domain) of any links that need to be generated for the user.", "type": "string", "example": "https://example.app.box.com/" }, "is_platform_access_only": { "description": "Whether the user is an App User.", "type": "boolean", "example": true }, "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.", "type": "string", "example": "my-user-1234" } } } ], "title": "User (Full)", "x-box-resource-id": "user--full", "x-box-tag": "users", "x-box-variant": "full" }, "User--Mini": { "description": "A mini representation of a user, as can be returned when nested within other resources.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "properties": { "name": { "description": "The display name of this user.", "type": "string", "example": "Aaron Levie", "maxLength": 50, "nullable": false }, "login": { "description": "The primary email address of this user.", "type": "string", "format": "email", "example": "ceo@example.com", "nullable": false } } } ], "title": "User (Mini)", "x-box-resource-id": "user--mini", "x-box-tag": "users", "x-box-variant": "mini" }, "UserAvatar": { "description": "A resource holding URLs to the avatar uploaded to a Box application.", "type": "object", "properties": { "pic_urls": { "description": "Represents an object with user avatar URLs.", "type": "object", "properties": { "small": { "description": "The location of a small-sized avatar.", "type": "string", "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\n" }, "large": { "description": "The location of a large-sized avatar.", "type": "string", "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks\npac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw\njtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc\ngSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC\nao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r" }, "preview": { "description": "The location of the avatar preview.", "type": "string", "example": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks!\npac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW\nk-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ\n04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl\nsSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc\n9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g" } } } }, "title": "User avatar", "x-box-resource-id": "user_avatar", "x-box-tag": "avatars" }, "UserIntegrationMappings": { "description": "A user representation for integration mappings API purposes. Fields name and login are not required.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "properties": { "name": { "description": "The display name of this user.", "type": "string", "example": "Aaron Levie", "maxLength": 50, "nullable": false }, "login": { "description": "The primary email address of this user.", "type": "string", "format": "email", "example": "ceo@example.com", "nullable": false } } } ], "title": "User (Integration Mappings)", "x-box-resource-id": "user_integration_mappings_reference", "x-box-tag": "users" }, "Users": { "description": "A list of users.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "type": "object", "description": "The part of an API response that describes pagination.", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 5000 }, "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.", "type": "integer", "format": "int64", "example": 1000 }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64", "example": 2000 }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted.", "type": "array", "items": { "type": "object", "description": "The order in which a pagination is ordered.", "properties": { "by": { "description": "The field to order by.", "type": "string", "example": "type" }, "direction": { "description": "The direction to order by, either ascending or descending.", "type": "string", "example": "ASC", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "A list of users.", "type": "array", "items": { "$ref": "#/components/schemas/User--Full" } } } } ], "title": "Users", "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.", "type": "object", "properties": { "watermark": { "type": "object", "properties": { "created_at": { "description": "When this watermark was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When this task was modified.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" } } } }, "title": "Watermark", "x-box-resource-id": "watermark", "x-box-tag": "file_watermarks" }, "Webhook": { "description": "Represents a configured webhook.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Webhook--Mini" }, { "properties": { "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created the webhook." } ] }, "created_at": { "description": "A timestamp identifying the time that the webhook was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "address": { "description": "The URL that is notified by this webhook.", "type": "string", "example": "https://example.com/webhooks" }, "triggers": { "description": "An array of event names that this webhook is to be triggered for.", "type": "array", "items": { "title": "Webhook Trigger", "example": "FILE.UPLOADED", "type": "string", "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", "SIGN_REQUEST.SIGNER_EMAIL_BOUNCED", "SIGN_REQUEST.SIGN_SIGNER_SIGNED", "SIGN_REQUEST.SIGN_DOCUMENT_CREATED", "SIGN_REQUEST.SIGN_ERROR_FINALIZING" ] }, "example": [ "FILE.UPLOADED" ] } } } ], "title": "Webhook", "x-box-resource-id": "webhook", "x-box-tag": "webhooks", "x-box-variant": "standard" }, "Webhook--Mini": { "description": "Represents a configured webhook.", "type": "object", "properties": { "id": { "description": "The unique identifier for this webhook.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `webhook`.", "type": "string", "example": "webhook", "enum": [ "webhook" ] }, "target": { "description": "The item that will trigger the webhook.", "type": "object", "properties": { "id": { "description": "The ID of the item to trigger a webhook.", "type": "string", "example": "1231232" }, "type": { "description": "The type of item to trigger a webhook.", "type": "string", "example": "file", "enum": [ "file", "folder" ] } } } }, "title": "Webhook (Mini)", "x-box-resource-id": "webhook--mini", "x-box-tag": "webhooks", "x-box-variant": "mini", "x-box-variants": [ "mini", "standard" ] }, "Webhooks": { "description": "A list of webhooks.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of webhooks.", "type": "array", "items": { "$ref": "#/components/schemas/Webhook--Mini" } } } } ], "title": "Webhooks", "x-box-resource-id": "webhooks", "x-box-tag": "webhooks" }, "WebLink": { "description": "Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects, they will also support most actions that apply to regular files.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WebLink--Mini" }, { "properties": { "parent": { "allOf": [ { "$ref": "#/components/schemas/Folder--Mini" }, { "description": "The parent object the web link belongs to." } ] }, "description": { "description": "The description accompanying the web link. This is visible within the Box web application.", "type": "string", "example": "Example page" }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "required": [ "total_count", "entries" ], "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64", "example": 1, "nullable": false }, "entries": { "description": "The parent folders for this item.", "type": "array", "items": { "$ref": "#/components/schemas/Folder--Mini" }, "nullable": false } } }, { "description": "The tree of folders that this web link is contained in, starting at the root." }, { "nullable": false } ] }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "trashed_at": { "description": "When this file was moved to the trash.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00", "nullable": true }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who created this web link." } ] }, "modified_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who last modified this web link." } ] }, "owned_by": { "allOf": [ { "$ref": "#/components/schemas/User--Mini" }, { "description": "The user who owns this web link." } ] }, "shared_link": { "allOf": [ { "title": "Shared link", "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users.", "type": "object", "required": [ "url", "accessed", "effective_access", "effective_permission", "is_password_enabled", "download_count", "preview_count" ], "properties": { "url": { "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file can be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url` has been set for this shared link.", "type": "string", "format": "url", "example": "https://www.box.com/s/vspke7y05sb214wjokpk", "nullable": false }, "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.\n\nThis property will be `null` for folders.", "type": "string", "format": "url", "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", "nullable": true, "x-box-premium-feature": true }, "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.", "type": "string", "format": "url", "example": "https://acme.app.box.com/v/my_url/", "nullable": true }, "vanity_name": { "description": "The custom name of a shared link, as used in the `vanity_url` field.", "type": "string", "example": "my_url", "nullable": true }, "access": { "description": "The access level for this shared link.\n\n- `open` - provides access to this item to anyone with this link\n- `company` - only provides access to this item to people the same company\n- `collaborators` - only provides access to this item to people who are collaborators on this item\n\nIf 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.", "type": "string", "example": "open", "enum": [ "open", "company", "collaborators" ], "nullable": false }, "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.", "type": "string", "example": "company", "enum": [ "open", "company", "collaborators" ], "nullable": false }, "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.", "type": "string", "example": "can_download", "enum": [ "can_edit", "can_download", "can_preview", "no_access" ], "nullable": false }, "unshared_at": { "description": "The date and time when this link will be unshared. This field can only be set by users with paid accounts.", "type": "string", "format": "date-time", "example": "2018-04-13T13:53:23-07:00", "nullable": true }, "is_password_enabled": { "description": "Defines if the shared link requires a password to access the item.", "type": "boolean", "example": true, "nullable": false }, "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.", "type": "object", "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.\n\nThis value can be set to `true` when the effective access level is set to `open` or `company`, not `collaborators`.", "type": "boolean", "example": true, "nullable": false }, "can_preview": { "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also applies to any items in the folder.", "type": "boolean", "example": true, "nullable": false }, "can_edit": { "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if the item has a type of `file`.", "type": "boolean", "example": false, "nullable": false } }, "required": [ "can_download", "can_preview", "can_edit" ] }, "download_count": { "description": "The number of times this item has been downloaded.", "type": "integer", "example": 3, "nullable": false }, "preview_count": { "description": "The number of times this item has been previewed.", "type": "integer", "example": 3, "nullable": false } } }, { "description": "The shared link object for this item. Will be `null` if no shared link has been created." }, { "nullable": true } ] }, "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.", "type": "string", "example": "active", "enum": [ "active", "trashed", "deleted" ] }, "collections": { "description": "The collections that this web link belongs to.\n\nFor more information, see the [collections guide](/guides/collections).", "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "allowed_shared_link_access_levels": { "description": "The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this web link.\n\nThe list depends on item policy and user authorization, so it may be narrower than the levels available to the owner. An empty array means no access level is available to this user.", "type": "array", "items": { "title": "Shared link access level", "type": "string", "description": "The access level for a shared link.", "example": "open", "enum": [ "open", "company", "collaborators" ] }, "example": [ "open" ], "nullable": false } } } ], "title": "Web link", "x-box-resource-id": "web_link", "x-box-tag": "web_links", "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.\n\nWeb link objects are treated similarly to file objects, they will also support most actions that apply to regular files.", "type": "object", "properties": { "id": { "description": "The unique identifier for this web link.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `web_link`.", "type": "string", "example": "web_link", "enum": [ "web_link" ] }, "etag": { "description": "The entity tag of this web link. Used with `If-Match` headers.", "type": "string", "example": "1" } }, "required": [ "id", "type" ], "title": "Web link (Base)", "x-box-resource-id": "web_link--base", "x-box-tag": "web_links", "x-box-variant": "base", "x-box-variants": [ "base", "mini", "standard" ] }, "WebLink--Mini": { "description": "Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects, they will also support most actions that apply to regular files.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WebLink--Base" }, { "properties": { "url": { "description": "The URL this web link points to.", "type": "string", "example": "https://www.example.com/example/1234" }, "sequence_id": { "allOf": [ { "type": "string", "example": "3", "nullable": true, "description": "A numeric identifier that represents the most recent user event that has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read.\n\nAn example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource." }, { "nullable": false } ] }, "name": { "description": "The name of the web link.", "type": "string", "example": "My Bookmark" } } } ], "title": "Web link (Mini)", "x-box-resource-id": "web_link--mini", "x-box-tag": "web_links", "x-box-variant": "mini" }, "Workflow": { "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYour application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Workflow--Mini" }, { "properties": { "flows": { "description": "A list of flows assigned to a workflow.", "type": "array", "items": { "type": "object", "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": { "id": { "description": "The identifier of the flow.", "type": "string", "example": "12345" }, "type": { "description": "The flow's resource type.", "type": "string", "example": "flow", "enum": [ "flow" ] }, "trigger": { "allOf": [ { "type": "object", "properties": { "type": { "description": "The trigger's resource type.", "type": "string", "example": "trigger", "enum": [ "trigger" ] }, "trigger_type": { "description": "The type of trigger selected for this flow.", "type": "string", "example": "WORKFLOW_MANUAL_START", "enum": [ "WORKFLOW_MANUAL_START" ] }, "scope": { "description": "List of trigger scopes.", "type": "array", "items": { "type": "object", "description": "Object that describes where and how a Trigger condition is met.", "properties": { "type": { "description": "The trigger scope's resource type.", "type": "string", "example": "trigger_scope", "enum": [ "trigger_scope" ] }, "ref": { "description": "Indicates the path of the condition value to check.", "type": "string", "example": "/event/source/parameters/folder" }, "object": { "description": "The object the `ref` points to.", "type": "object", "properties": { "type": { "description": "The type of the object.", "type": "string", "example": "folder", "enum": [ "folder" ] }, "id": { "description": "The id of the object.", "type": "string", "example": "12345" } } } } } } } }, { "description": "Trigger that initiates flow." } ] }, "outcomes": { "allOf": [ { "type": "array", "items": { "type": "object", "description": "List of outcomes to perform once the conditions of trigger are met.", "properties": { "id": { "description": "The identifier of the outcome.", "type": "string", "example": "12345" }, "type": { "description": "The outcomes resource type.", "type": "string", "example": "outcome", "enum": [ "outcome" ] }, "name": { "description": "The name of the outcome.", "type": "string", "example": "Task Approval Outcome" }, "action_type": { "allOf": [ { "title": "Action Type", "example": "assign_task", "type": "string", "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" ] }, { "description": "The type of outcome." } ] }, "if_rejected": { "description": "If `action_type` is `assign_task` and the task is rejected, returns a list of outcomes to complete.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The identifier of the outcome.", "type": "string", "example": "12345" }, "type": { "description": "The outcomes resource type.", "type": "string", "example": "outcome", "enum": [ "outcome" ] }, "name": { "description": "The name of the outcome.", "type": "string", "example": "Approval Rejection Outcome" }, "action_type": { "allOf": [ { "title": "Action Type", "example": "assign_task", "type": "string", "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" ] }, { "description": "The type of outcome." } ] } } } } } } }, { "description": "Actions that are completed once the flow is triggered." } ] }, "created_at": { "description": "When this flow was created.", "type": "string", "format": "date-time", "example": "2012-12-12T10:53:43-08:00" }, "created_by": { "allOf": [ { "$ref": "#/components/schemas/User--Base" }, { "description": "The user who created this flow." } ] } } } } } } ], "title": "Workflow", "x-box-resource-id": "workflow", "x-box-tag": "workflows", "x-box-variant": "standard" }, "Workflow--Mini": { "description": "Box Relay Workflows are objects that represent a named collection of flows.\n\nYou application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource.", "type": "object", "properties": { "id": { "description": "The unique identifier for the workflow.", "type": "string", "example": "11446498" }, "type": { "description": "The value will always be `workflow`.", "type": "string", "example": "workflow", "enum": [ "workflow" ] }, "name": { "description": "The name of the workflow.", "type": "string", "example": "New Hire Workflow" }, "description": { "description": "The description for a workflow.", "type": "string", "example": "This workflow sets off a new hire approval flow" }, "is_enabled": { "description": "Specifies if this workflow is enabled.", "type": "boolean", "example": true } }, "title": "Workflow (Mini)", "x-box-resource-id": "workflow--mini", "x-box-tag": "workflows", "x-box-variant": "mini", "x-box-variants": [ "mini", "standard" ] }, "Workflows": { "description": "A list of workflows.\n\nYou application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource.", "type": "object", "allOf": [ { "type": "object", "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.", "type": "integer", "format": "int64", "example": 1000 }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii", "nullable": true }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "string", "example": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih", "nullable": true } } }, { "properties": { "entries": { "description": "A list of workflows.", "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } } } ], "title": "Workflows", "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.", "type": "object", "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.\n\nIt 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.", "type": "string", "example": "https://dl.boxcloud.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/content" }, "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.\n\nIt 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.", "type": "string", "example": "https://api.box.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/status" }, "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.\n\nBy 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.", "type": "string", "format": "date-time", "example": "2019-08-29T23:59:00-07:00" }, "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.\n\nTo solve these conflicts, the API will automatically rename an item and return a mapping between the original item's name and its new name.\n\nFor every conflict, both files will be renamed and therefore this list will always be a multiple of 2.", "type": "array", "items": { "type": "array", "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": { "type": "object", "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": { "id": { "description": "The identifier of the item.", "type": "string", "example": "12345" }, "type": { "description": "The type of this item.", "type": "string", "example": "file", "enum": [ "file", "folder" ] }, "original_name": { "description": "Box Developer Documentation.", "type": "string", "example": "Report.pdf" }, "download_name": { "description": "The new name of this item as it will appear in the downloaded `zip` archive.", "type": "string", "example": "3aa6a7.pdf" } } } } } }, "example": { "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content", "status_url": "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status", "expires_at": "2020-07-22T11:26:08Z", "name_conflicts": [ [ { "id": "12345", "type": "file", "original_name": "Report.pdf", "download_name": "3aa6a7.pdf" }, { "id": "34325", "type": "file", "original_name": "Report.pdf", "download_name": "5d53f2.pdf" } ] ] }, "title": "Zip download", "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.", "type": "object", "properties": { "items": { "description": "A list of items to add to the `zip` archive. These can be folders or files.", "type": "array", "items": { "type": "object", "description": "An item to add to the `zip` archive. This can be a file or a folder.", "required": [ "type", "id" ], "properties": { "type": { "description": "The type of the item to add to the archive.", "type": "string", "example": "file", "enum": [ "file", "folder" ] }, "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`.", "type": "string", "example": "12345" } } } }, "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`.", "type": "string", "example": "January Financials" } }, "required": [ "items" ], "title": "Create a `zip` archive" }, "ZipDownloadStatus": { "description": "The status of a `zip` archive being downloaded.", "type": "object", "properties": { "total_file_count": { "description": "The total number of files in the archive.", "type": "integer", "example": 20, "maximum": 10000, "minimum": 0 }, "downloaded_file_count": { "description": "The number of files that have already been downloaded.", "type": "integer", "example": 10, "minimum": 0 }, "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.", "type": "integer", "example": 5, "minimum": 0 }, "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.", "type": "integer", "example": 5, "minimum": 0 }, "state": { "description": "The state of the archive being downloaded.", "type": "string", "example": "succeeded", "default": "in_progress", "enum": [ "in_progress", "failed", "succeeded" ] } }, "title": "Zip download status", "x-box-reference-category": "zip_downloads", "x-box-resource-id": "zip_download_status", "x-box-tag": "zip_downloads" } }, "securitySchemes": { "OAuth2Security": { "type": "oauth2", "description": "The access token received from the authorization server in the OAuth 2.0 flow.", "flows": { "authorizationCode": { "authorizationUrl": "https://account.box.com/api/oauth2/authorize", "tokenUrl": "https://api.box.com/oauth2/token", "scopes": { "root_readonly": "Read all files and folders stored in Box", "root_readwrite": "Read and write all files and folders stored in Box", "manage_app_users": "Provision and manage app users", "manage_managed_users": "Provision and manage managed users", "manage_groups": "Manage an enterprise's groups", "manage_webhook": "Create webhooks programmatically through the API", "manage_enterprise_properties": "Manage enterprise properties", "manage_data_retention": "Manage data retention polices", "manage_legal_hold": "Manage Legal Holds" } } } } } }, "security": [ { "OAuth2Security": [] } ], "tags": [ { "name": "AI", "description": "A set of endpoints used to interact with supported LLMs.", "x-box-tag": "ai" }, { "name": "AI Studio", "description": "A set of endpoints used to interact with AI Studio.", "x-box-tag": "ai_studio" }, { "name": "App item associations", "x-box-tag": "app_item_associations" }, { "name": "Authorization", "description": "A set of endpoints used to manage user authorization process.", "x-box-tag": "authorization", "x-box-priority": true }, { "name": "Box Sign requests", "description": "Box Sign requests are used to submit a file for signature.", "x-box-tag": "sign_requests" }, { "name": "Classifications", "description": "Classification labels are used for content that is sensitive or under security restrictions.", "x-box-tag": "classifications" }, { "name": "Classifications on files", "description": "Classification labels are used for files that are sensitive or under security restrictions.", "x-box-tag": "file_classifications" }, { "name": "Classifications on folders", "description": "Classification labels are used for folders that are sensitive or under security restrictions.", "x-box-tag": "folder_classifications" }, { "name": "Collaborations", "description": "Collaborations define access permissions for users and groups to files and folders, similar to access control lists.", "x-box-tag": "user_collaborations" }, { "name": "Collaborations (List)", "description": "A set of endpoints used to retrieve file, folder, pending, and group collaborations.", "x-box-tag": "list_collaborations" }, { "name": "Collections", "description": "Collections are a way to group files, folders, and web links without putting them all into a folder.", "x-box-tag": "collections" }, { "name": "Comments", "description": "Comments are messages generated users on files, allowing users to collaborate on a file, discussing any feedback they might have on the content.", "x-box-tag": "comments" }, { "name": "Device pinners", "description": "Device pinners allow enterprises to control what devices can use native Box applications.", "x-box-tag": "device_pinners" }, { "name": "Domain restrictions (User exemptions)", "description": "A set of endpoints that allow exempting users from restrictions imposed by the list of allowed collaboration domains for a specific enterprise.", "x-box-tag": "collaboration_allowlist_exempt_targets" }, { "name": "Domain restrictions for collaborations", "description": "A set of endpoints that manage domains for which users can collaborate with files and folders in an enterprise.", "x-box-tag": "collaboration_allowlist_entries" }, { "name": "Downloads", "description": "Downloads allow saving files to the application's server, or directly by the end user in a browser.", "x-box-tag": "downloads" }, { "name": "Email aliases", "description": "Email aliases provide a list of emails additional to the user's primary login email.", "x-box-tag": "email_aliases" }, { "name": "Events", "description": "Events provide a way for an application to subscribe to any actions performed by any user, users, or service in an enterprise.", "x-box-tag": "events" }, { "name": "File requests", "description": "File Requests provide a fast and secure way to request files and associated metadata from anyone. Users can create new file requests based on an existing file request, update file request settings, activate, deactivate, and delete file requests programmatically.", "x-box-tag": "file_requests" }, { "name": "File version legal holds", "description": "A legal hold is a process that an enterprise can use to preserve all forms of potentially relevant information when litigation is pending or reasonably anticipated. A File Version Legal Hold represents all the policies that are assigned to a specific file version.", "x-box-tag": "file_version_legal_holds" }, { "name": "File version retentions", "description": "A retention policy blocks permanent deletion of content for a specified amount of time. A file version retention is a record for a retained file.", "x-box-tag": "file_version_retentions" }, { "name": "File versions", "description": "A set of endpoints used to manage specific versions of a file.", "x-box-tag": "file_versions" }, { "name": "Files", "description": "Files, together with Folders, are at the core of the Box API. Files can be uploaded and downloaded, as well as hold important metadata information about the content.", "x-box-tag": "files" }, { "name": "Folder Locks", "description": "Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.", "x-box-tag": "folder_locks" }, { "name": "Folders", "description": "Folders, together with Files, are at the core of the Box API. Folders can be uploaded and downloaded, as well as hold important metadata information about the content.", "x-box-tag": "folders" }, { "name": "Integration mappings", "description": "Integration Mappings allow the users to manage where content from partner apps is stored in Box.", "x-box-tag": "integration_mappings" }, { "name": "Group memberships", "description": "Group memberships signify that a user is a part of the group.", "x-box-tag": "memberships" }, { "name": "Groups", "description": "Groups created in an enterprise.", "x-box-tag": "groups" }, { "name": "Invites", "description": "Invites are used to invite the user to an enterprise.", "x-box-tag": "invites" }, { "name": "Legal hold policies", "description": "A legal hold is a process that an enterprise can use to preserve all forms of potentially relevant information when litigation is pending or reasonably anticipated.", "x-box-tag": "legal_hold_policies" }, { "name": "Legal hold policy assignments", "description": "A Legal Hold Policy Assignment is a relation between a policy and custodian. In this case, as custodian can be a user, folder, file, or file version.", "x-box-tag": "legal_hold_policy_assignments" }, { "name": "Metadata cascade policies", "description": "A metadata cascade policy describes how metadata instances applied to a folder should be applied to any item within that folder.", "x-box-tag": "metadata_cascade_policies" }, { "name": "Metadata instances (Files)", "description": "A metadata instance describes the relation between a template and a file, including the values that are assigned for every field.", "x-box-tag": "file_metadata" }, { "name": "Metadata instances (Folders)", "description": "A metadata instance describes the relation between a template and a folder, including the values that are assigned for every field.", "x-box-tag": "folder_metadata" }, { "name": "Metadata taxonomies", "description": "A metadata taxonomy is a hierarchical classification system that helps organize and manage metadata within an enterprise.", "x-box-tag": "metadata_taxonomies" }, { "name": "Metadata templates", "description": "A metadata template describes a reusable set of key/value pairs that can be assigned to a file.", "x-box-tag": "metadata_templates" }, { "name": "Recent items", "description": "Recent items represent items such as files or folders that the user accessed recently.", "x-box-tag": "recent_items" }, { "name": "Retention policies", "description": "A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then assign them to specific folders or their entire enterprise.", "x-box-tag": "retention_policies" }, { "name": "Retention policy assignments", "description": "A Retention Policy Assignment is a relation between a policy and folder or enterprise. Creating an assignment puts a retention on all the file versions that belong to that folder or enterprise.", "x-box-tag": "retention_policy_assignments" }, { "name": "Search", "description": "The Box API provides a way to find content in Box using full-text search queries.", "x-box-tag": "search" }, { "name": "Session termination", "description": "Session termination API is used to validate the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions.", "x-box-tag": "session_termination" }, { "name": "Shared links (Files)", "description": "Files shared links are URLs that are generated for files stored in Box, which provide direct, read-only access to the resource.", "x-box-tag": "shared_links_files" }, { "name": "Shared links (Folders)", "description": "Folders shared links are URLs that are generated for folders stored in Box, which provide direct, read-only access to the resource.", "x-box-tag": "shared_links_folders" }, { "name": "Shared links (Web Links)", "description": "Web links for files are URLs that are generated for web links in Box, which provide direct, read-only access to the resource.", "x-box-tag": "shared_links_web_links" }, { "name": "Shared links (App Items)", "description": "URLs generated for app items stored in Box, which provide direct, read-only access to the resource.", "x-box-tag": "shared_links_app_items" }, { "name": "Shield information barriers", "description": "Shield information barrier in Box defines an ethical wall. An ethical wall is a mechanism that prevents exchanges or communication that could lead to conflicts of interest and therefore result in business activities ethically or legally questionable.", "x-box-tag": "shield_information_barriers" }, { "name": "Shield information barrier segments", "description": "Shield information barrier segment represents a defined group of users. A user can be a member of only one segment, which makes segments different from groups.", "x-box-tag": "shield_information_barrier_segments" }, { "name": "Shield information barrier segment members", "description": "Shield information barrier segment member represents a user that is assigned to a specific segment.", "x-box-tag": "shield_information_barrier_segment_members" }, { "name": "Shield information barrier reports", "description": "Shield information barrier reports contain information on what existing collaborations will be removed permanently when the information barrier is enabled.", "x-box-tag": "shield_information_barrier_reports" }, { "name": "Shield information barrier segment restrictions", "description": "Shield information barrier segment restriction is an access restriction based on the content (file or folder) owner.", "x-box-tag": "shield_information_barrier_segment_restrictions" }, { "name": "Box Sign templates", "description": "Sign templates allow you to use a predefined Box Sign template when creating a signature request. The template includes placeholders that are automatically populated with data when creating the request.", "x-box-tag": "sign_templates" }, { "name": "Skills", "description": "Box Skills are designed to allow custom processing of files uploaded to Box, with the intent of enhancing the underlying metadata of the file.", "x-box-tag": "skills" }, { "name": "Standard and Zones Storage Policies", "description": "Storage policy assignment represents the storage zone for items in a given enterprise.", "x-box-tag": "storage_policies" }, { "name": "Standard and Zones Storage Policy Assignments", "description": "Storage policy assignment represents the relation between storage zone and the assigned item (for example a file stored in a specific zone).", "x-box-tag": "storage_policy_assignments" }, { "name": "Task assignments", "description": "A task assignment defines which task is assigned to which user to complete.", "x-box-tag": "task_assignments" }, { "name": "Tasks", "description": "Tasks allow users to request collaborators on a file to review a file or complete a piece of work. Tasks can be used by developers to create file-centric workflows.", "x-box-tag": "tasks" }, { "name": "Terms of service", "description": "A set of endpoints used to manage terms of service agreements.", "x-box-tag": "terms_of_services" }, { "name": "Terms of service user statuses", "description": "A set of endpoints used to manage the status of terms of service for a particular user.", "x-box-tag": "terms_of_service_user_statuses" }, { "name": "Transfer folders", "description": "API designed to move all of the items (files, folders and workflows) owned by a user into another user's account.", "x-box-tag": "transfer" }, { "name": "Trashed files", "description": "Files that were deleted and are in trash.", "x-box-tag": "trashed_files" }, { "name": "Trashed folders", "description": "Folders that were deleted and are in trash.", "x-box-tag": "trashed_folders" }, { "name": "Trashed items", "description": "Items that were deleted and are in trash.", "x-box-tag": "trashed_items" }, { "name": "Trashed web links", "description": "Web links that were deleted and are in trash.", "x-box-tag": "trashed_web_links" }, { "name": "Uploads", "description": "The direct file upload API supports files up to 50MB in size and sends all the binary data to the Box API in 1 API request.", "x-box-tag": "uploads" }, { "name": "Uploads (Chunked)", "description": "The chunked upload endpoints support files from 20MB in size and allow an application to upload the file in parts, allowing for more control to catch any errors and retry parts individually.", "x-box-tag": "chunked_uploads" }, { "name": "User avatars", "description": "User avatars are JPG or PNG files uploaded to Box to represent the user image. They are then displayed in the user account.", "x-box-tag": "avatars" }, { "name": "Users", "description": "Box API supports a variety of users, ranging from real employees logging in with their Managed User account, to applications using App Users to drive powerful automation workflows.", "x-box-tag": "users" }, { "name": "Watermarks (Files)", "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 the file.", "x-box-tag": "file_watermarks" }, { "name": "Watermarks (Folders)", "description": "A watermark is a semi-transparent overlay on an embedded folder preview that displays a viewer's email address or user ID and the time of access over the folder content.", "x-box-tag": "folder_watermarks" }, { "name": "Web links", "description": "Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application.", "x-box-tag": "web_links" }, { "name": "Webhooks", "description": "Webhooks allow you to monitor Box content for events, and receive notifications to a URL of your choice when they occur. For example, a workflow may include waiting for a file to be downloaded to delete a shared link.", "x-box-tag": "webhooks" }, { "name": "Workflows", "description": "Box Relay Workflows are objects that represent a named collection of flows.", "x-box-tag": "workflows" }, { "name": "Zip Downloads", "description": "Zip downloads represent a successful request to create a ZIP archive with files and folders.", "x-box-tag": "zip_downloads" } ], "externalDocs": { "description": "Box Developer Documentation.", "url": "https://developer.box.com" }, "x-mint": { "mcp": { "enabled": true } } }