{ "swagger": "2.0", "info": { "title": "Box Platform API", "description": "[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.", "termsOfService": "https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9", "contact": { "name": "Box, Inc", "url": "https://box.dev", "email": "devrel@box.com" }, "license": { "name": "Apache-2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "2.0.0" }, "host": "api.box.com", "basePath": "/2.0", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/files/{file_id}": { "get": { "operationId": "get_files_id", "summary": "Get file information", "tags": [ "Files" ], "description": "Retrieves the details about a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.\n\nAdditionally this field can be used to query any metadata\napplied to the file by specifying the `metadata` field as well\nas the scope and key of the template to retrieve, for example\n`?field=metadata.enterprise_12345.contractTemplate`.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "type": "string" }, { "name": "boxapi", "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\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `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\nor folders nested within the item.", "in": "header", "required": false, "type": "string" }, { "name": "x-rep-hints", "description": "A header required to request specific `representations`\nof a file. Use this in combination with the `fields` query\nparameter to request a specific file representation.\n\nThe general format for these representations is\n`X-Rep-Hints: [...]` where `[...]` is one or many\nhints in the format `[fileType?query]`.\n\nFor example, to request a `png` representation in `32x32`\nas well as `94x94` pixel dimensions provide the following\nhints.\n\n`X-Rep-Hints: [jpg?dimensions=32x32][jpg?dimensions=94x94]`\n\nAdditionally, a `text` representation is available for all\ndocument file types in Box using the `[extracted_text]`\nrepresentation.\n\n`X-Rep-Hints: [extracted_text]`", "in": "header", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/File" } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "415": { "description": "Returns an error if an action is performed on a file with an\nincorrect media type.\n\n* `unsupported_media_type` when requesting an `expiring_embed_link`\n for a file that is not supported by Box Embed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_files_id", "summary": "Restore file", "tags": [ "Trashed files" ], "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\noriginal folder has been deleted.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the file.", "type": "string" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item" } } }, { "description": "Specifies an optional ID of a folder to restore the file to\nwhen the original folder no longer exists.\n\nPlease be aware that this ID will only be used if the original\nfolder no longer exists. Use this ID to provide a fallback\nlocation to restore the file to if the original location\nhas been deleted." } ] } } } } ], "responses": { "201": { "description": "Returns a file object when the file has been restored.", "schema": { "$ref": "#/definitions/File" } }, "403": { "description": "Returns an error if the user does not have access to the folder\nthe file is being restored to, or the user does not have permission\nto restore files from the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the file is not in the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if there is an file with the same name\nin the folder the file is being restored to.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_files_id", "summary": "Update file", "tags": [ "Files" ], "description": "Updates a file. This can be used to rename or move a file,\ncreate a shared link, or lock a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "An optional different name for the file. This can be used to\nrename the file." }, "description": { "type": "string", "description": "The description for a file. This can be seen in the right-hand sidebar panel\nwhen viewing a file in the Box web app. Additionally, this index is used in\nthe search index of the file, allowing users to find the file by the content\nin the description.", "maxLength": 256 }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item" } } }, { "description": "An optional new parent folder for the file. This can be used\nto move the file to a new folder." } ] }, "shared_link": { "allOf": [ { "description": "Defines a shared link for an item. Set this to `null` to remove\nthe shared link.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ] }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`." }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared links." }, "unshared_at": { "type": "string", "format": "date-time", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } }, { "description": "Defines a shared link for a file. Set this to `null` to remove\nthe shared link." } ] }, "lock": { "type": "object", "description": "Defines a lock on an item. This prevents the item from being\nmoved, renamed, or otherwise changed by anyone other than the user\nwho created the lock.\n\nSet this to `null` to remove the lock.", "required": [ "type" ], "properties": { "access": { "type": "string", "description": "The type of this object.", "enum": [ "lock" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Defines the time at which the lock expires." }, "is_download_prevented": { "type": "boolean", "description": "Defines if the file can be downloaded while it is locked." } } }, "permissions": { "description": "Defines who can download a file.", "type": "object", "properties": { "can_download": { "description": "Defines who is allowed to download this file. The possible\nvalues are either `open` for everyone or `company` for\nthe other members of the user's enterprise.\n\nThis setting overrides the download permissions that are\nnormally part of the `role` of a collaboration. When set to\n`company`, this essentially removes the download option for\nexternal users with `viewer` or `editor` a roles.", "type": "string", "enum": [ "open", "company" ] } } }, "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "The tags for this item. These tags are shown in\nthe Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags,\nmodify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000\nunique tags per enterprise." } } } } ], "responses": { "200": { "description": "Returns a file object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/File" } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` when the authenticated user\ndoes not have access the destination folder to move the file to.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_files_id", "summary": "Delete file", "tags": [ "Files" ], "description": "Deletes a file, either permanently or by moving it to\nthe trash.\n\nThe the enterprise settings determine whether the item will\nbe permanently deleted from Box or moved to the trash.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the file has been successfully\ndeleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found or has already been deleted, or the user\ndoes not have access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/content": { "get": { "operationId": "get_files_id_content", "summary": "Download file", "tags": [ "Downloads" ], "description": "Returns the contents of a file in binary format.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "range", "description": "The byte range of the content to download.\n\nThe format `{start_byte}-{end_byte}` can be used to specify\nwhat section of the file to download.", "in": "header", "required": false, "type": "string" }, { "name": "boxapi", "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\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `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\nor folders nested within the item.", "in": "header", "required": false, "type": "string" }, { "name": "version", "description": "The file version to download", "in": "query", "required": false, "type": "string" }, { "name": "access_token", "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.\nWhen 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.", "in": "query", "required": false, "type": "string" } ], "responses": { "202": { "description": "If the file is not ready to be downloaded yet `Retry-After` header will\nbe returned indicating the time in seconds after which the file will\nbe available for the client to download.\n\nThis response can occur when the file was uploaded immediately before the\ndownload request.", "headers": { "Retry-After": { "description": "The time in seconds after which to retry the download", "type": "integer" } } }, "302": { "description": "If the file is available to be downloaded the response will include a\n`Location` header for the file on `dl.boxcloud.com`.\n\nThe `dl.boxcloud.com` URL is not persistent and clients will need\nto follow the redirect in order to actually download the file.", "headers": { "Location": { "description": "A pointer to the download URL", "type": "string", "format": "url" } } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/content": { "options": { "operationId": "options_files_content", "summary": "Preflight check before upload", "tags": [ "Files" ], "description": "Performs a check to verify that a file will be accepted by Box\nbefore you upload the entire file.", "responses": { "200": { "description": "If the check passed, the response will include a session URL that\ncan be used to upload the file to.", "schema": { "$ref": "#/definitions/UploadUrl" } }, "409": { "description": "If the check did not pass, the response will include some details on\nwhy it did not pass.", "schema": { "$ref": "#/definitions/ConflictError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the file" }, "size": { "type": "integer", "format": "int32", "description": "The size of the file in bytes" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item" } } }, { "description": "The parent folder to upload the file to" } ] } } } } ] } }, "/files/{file_id}/copy": { "post": { "operationId": "post_files_id_copy", "summary": "Copy file", "description": "Creates a copy of a file.", "tags": [ "Files" ], "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "parent" ], "properties": { "name": { "type": "string", "description": "An optional new name for the copied file.\n\nThere are some restrictions to the file name. Names containing\nnon-printable ASCII characters, forward and backward slashes\n(`/`, `\\`), and protected names like `.` and `..` are\nautomatically sanitized by removing the non-allowed\ncharacters.", "maxLength": 255 }, "version": { "type": "string", "description": "An optional ID of the specific file version to copy." }, "parent": { "type": "object", "description": "The destination folder to copy the file to.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of folder to copy the file to." } } } } } } ], "responses": { "201": { "description": "Returns a new file object representing the copied file.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/File" } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the file. This indicates that the file\nhas not changed since it was last requested." }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `bad_request` when a parameter is missing.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if either the source file or the destination\nfolder could not be found, or the authenticated user does not\nhave access to either.\n\n* `not_found` when the authenticated user does not have access\n to the source file or the destination folder", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in process.\n\n The operation can be retried at a later point.\n\n* `item_name_in_use` when a folder with the same name already\n exists.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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\nthe `.png` format and sizes of `32x32`, `94x94`, `160x160`, and `320x320`\ncan be returned in the `.jpg` format.\n\nThumbnails can be generated for the image and video file formats listed\n[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", "tags": [ "Files" ], "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "extension", "description": "The file format for the thumbnail", "in": "path", "required": true, "type": "string", "enum": [ "png", "jpg" ] }, { "name": "min_height", "description": "The minimum height of the thumbnail", "in": "query", "type": "integer", "minimum": 32, "maximum": 320 }, { "name": "min_width", "description": "The minimum width of the thumbnail", "in": "query", "type": "integer", "minimum": 32, "maximum": 320 }, { "name": "max_height", "description": "The maximum height of the thumbnail", "in": "query", "required": false, "type": "integer", "minimum": 32, "maximum": 320 }, { "name": "max_width", "description": "The maximum width of the thumbnail", "in": "query", "required": false, "type": "integer", "minimum": 32, "maximum": 320 } ], "responses": { "200": { "description": "When a thumbnail can be created the thumbnail data will be\nreturned in the body of the response.", "schema": { "type": "string", "format": "binary", "description": "The thumbnail" } }, "202": { "description": "Sometimes generating a thumbnail can take a few seconds. In these\nsituations the API returns a `Location`-header pointing to a\nplaceholder graphic for this file type.\n\nThe placeholder graphic can be used in a user interface until the\nthumbnail generation has completed. The `Retry-After`-header indicates\nwhen to the thumbnail will be ready. At that time, retry this endpoint\nto 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\nthis time.", "type": "integer", "format": "int64" }, "Location": { "description": "A pointer to a placeholder graphic that can be used until the\nthumbnail has been generated.", "type": "string", "format": "url" } } }, "302": { "description": "Returns an error when Box is not able to create a thumbnail for this\nfile type.\n\nInstead, a `Location`-header pointing to a placeholder graphic for\nthis file type will be returned.", "headers": { "Location": { "description": "A pointer to a placeholder graphic that can be used for this\nfile type.", "type": "string", "format": "url" } } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `requested_preview_unavailable` - an incorrect dimension was\n requested. This will happen if the dimension requested is\n larger or smaller than the available file sizes for the thumbnail\n format, or when when any of the size constraints contradict\n each other.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file, or for additional reasons.\n\n* `preview_cannot_be_generated` - Box does not support thumbnails\n for this type of file", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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\nfile. This returns all the users that have access to the file\nor have been invited to the file.", "tags": [ "Collaborations (List)" ], "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no\ncollaborations on this file an empty collection will be returned.\n\nThis list includes pending collaborations, for which the `status`\nis set to `pending`, indicating invitations that have been sent but not\nyet accepted.", "schema": { "$ref": "#/definitions/Collaborations" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/comments": { "get": { "operationId": "get_files_id_comments", "summary": "List file comments", "description": "Retrieves a list of comments for a file.", "tags": [ "Comments" ], "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns a collection of comment objects. If there are no\ncomments on this file an empty collection will be returned.", "schema": { "$ref": "#/definitions/Comments" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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\nendpoint does not support pagination.", "tags": [ "Tasks" ], "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "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\ninstead.", "schema": { "$ref": "#/definitions/Tasks" } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returns an error when the `file_id` was not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error when an attempt was made to retrieve tasks for the file\nwith ID `0`.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/trash": { "get": { "operationId": "get_files_id_trash", "summary": "Get trashed file", "tags": [ "Trashed files" ], "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\ntrash can it be retrieved with this API call. If instead one of\nits parent folders was moved to the trash, only that folder\ncan be inspected using the\n[`GET /folders/:id/trash`](e://get_folders_id_trash) API.\n\nTo list all items that have been moved to the trash, please\nuse the [`GET /folders/trash/items`](e://get-folders-trash-items/)\nAPI.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns the file that was trashed,\nincluding information about when the it\nwas moved to the trash.", "schema": { "$ref": "#/definitions/File" } }, "404": { "description": "Returns an error if the file can not be found directly\nin the trash.\n\nPlease note that a `HTTP 404` is also returned if any of\nthe file's parent folders have been moved to the trash.\n\nIn that case, only that parent folder can be inspected using\nthe [`GET /folders/:id/trash`](e://get_folders_id_trash) API.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_files_id_trash", "summary": "Permanently remove file", "tags": [ "Trashed files" ], "description": "Permanently deletes a file that is in the trash.\nThis action cannot be undone.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the file was\npermanently deleted." }, "404": { "description": "Returns an error if the file is not in the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/versions": { "get": { "operationId": "get_files_id_versions", "summary": "List all file versions", "tags": [ "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\nof the current version of a file, use the `GET /file/:id` API.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns an array of past versions for this file.", "schema": { "$ref": "#/definitions/FileVersions" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/versions/{file_version_id}": { "get": { "operationId": "get_files_id_versions_id", "summary": "Get file version", "tags": [ "File versions" ], "description": "Retrieve a specific version of a file.\n\nVersions are only tracked for Box users with premium accounts.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "file_version_id", "description": "The ID of the file version", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a specific version of a file.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/FileVersion" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_files_id_versions_id", "summary": "Remove file version", "tags": [ "File versions" ], "description": "Move a file version to the trash.\n\nVersions are only tracked for Box users with premium accounts.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "file_version_id", "description": "The ID of the file version", "in": "path", "required": true, "type": "string" }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the file has been successfully\ndeleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/versions/current": { "post": { "operationId": "post_files_id_versions_current", "summary": "Revert file version", "tags": [ "File versions" ], "description": "Revert to a previous version of a file.\n\nIf previous versions exist, this method can be used to\npromote one of the older versions to the top of the version history.\n\nThis actually creates a new copy of the old version and puts it at the\ntop of the versions history. The file will have the exact same contents\nas the older version, with the the same hash digest, `etag`, and\nname as the original.\n\nOther properties such as comments do not get updated to their\nformer values.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "description": "The file version to revert to", "properties": { "id": { "type": "string", "description": "The file version ID" }, "type": { "type": "string", "description": "The type to revert to", "enum": [ "file_version" ] } } } } ], "responses": { "201": { "description": "Returns a newly created file version object.", "schema": { "$ref": "#/definitions/FileVersion" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/metadata": { "get": { "operationId": "get_files_id_metadata", "summary": "List metadata instances on file", "tags": [ "Metadata instances (Files)" ], "description": "Retrieves all metadata for a given file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the file.", "schema": { "$ref": "#/definitions/Metadatas" } }, "403": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when the user does not have access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { "get": { "operationId": "get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Get classification on file", "tags": [ "Classifications on files" ], "description": "Retrieves the classification metadata instance that\nhas been applied to a file.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "201": { "description": "Returns an instance of the `securityClassification` metadata\ntemplate, which contains a `Box__Security__Classification__Key`\nfield that lists all the classifications available to this\nenterprise.", "schema": { "$ref": "#/definitions/Classification" } }, "403": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this file or the user does not have access to the\nfile.\n\n* `instance_not_found` - The metadata template was not applied to the\nfile.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to file", "tags": [ "Classifications on files" ], "description": "Adds a classification to a file by specifying the label of the\nclassification to add.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "Box__Security__Classification__Key": { "type": "string", "description": "The name of the classification to apply to this file.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys." } } } } ], "responses": { "201": { "description": "Returns the classification template instance\nthat was applied to the file.", "schema": { "$ref": "#/definitions/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 for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file or metadata template could not be found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template could not be found.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on file", "tags": [ "Classifications on files" ], "description": "Updates a classification on a file.\n\nThe classification can only be updated if a classification has already been\napplied to the file before. When editing classifications, only values are\ndefined for the enterprise will be accepted.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the updated classification metadata template instance.", "schema": { "$ref": "#/definitions/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\nPatch operations.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from file", "tags": [ "Classifications on files" ], "description": "Removes any classifications from a file.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the classification is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file does not have any classification applied\nto it, or when the user does not have access to the\nfile.\n\n* `instance_not_found` - An instance of the classification metadata\ntemplate with the was not found on this file.\n* `not_found` - The file was not found, or the user does not have access\nto the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/metadata/{scope}/{template_key}": { "get": { "operationId": "get_files_id_metadata_id_id", "summary": "Get metadata instance on file", "tags": [ "Metadata instances (Files)" ], "description": "Retrieves the instance of a metadata template that has been applied to a\nfile.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "201": { "description": "An instance of the metadata template that includes\nadditional \"key:value\" pairs defined by the user or\nan application.", "schema": { "$ref": "#/definitions/Metadata" } }, "403": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this file or the user does not have access to the\nfile.\n\n* `instance_not_found` - The metadata template was not applied to the\nfile.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_files_id_metadata_id_id", "summary": "Create metadata instance on file", "tags": [ "Metadata instances (Files)" ], "description": "Applies an instance of a metadata template to a file.\n\nIn most cases only values that are present in the metadata template\nwill be accepted, except for the `global.properties` template which accepts\nany key-value pair.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "additionalProperties": { "type": "string", "description": "A value for each of the fields that are present on the metadata\ntemplate.\n\nFor the `global.properties` template this can be an a list of zero\nor more fields, as this template allows for any generic key-value\npairs to be stored on the template.", "x-box-example-key": "name" } } } ], "responses": { "201": { "description": "Returns the instance of the template that was applied to the file,\nincluding the data that was applied to the template.", "schema": { "$ref": "#/definitions/Metadata" } }, "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 for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file or metadata template could not be found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template could not be found.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_files_id_metadata_id_id", "summary": "Update metadata instance on file", "tags": [ "Metadata instances (Files)" ], "description": "Updates a piece of metadata on a file.\n\nThe metadata instance can only be updated if the template has already been\napplied to the file before. When editing metadata, only values that match\nthe metadata template schema will be accepted.\n\nThe update is applied atomically. If any errors occur during the\napplication of the operations, the metadata instance will not be changed.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the updated metadata template instance, with the\ncustom template data included.", "schema": { "$ref": "#/definitions/Metadata" } }, "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\nPatch objects.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_files_id_metadata_id_id", "summary": "Remove metadata instance from file", "tags": [ "Metadata instances (Files)" ], "description": "Deletes a piece of file metadata.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the metadata is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid. This may happen of the\n`scope` is not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file does not have an instance of the metadata\ntemplate applied to it, or when the user does not have access to the\nfile.\n\n* `instance_not_found` - An instance of the metadata template with the\ngiven `scope` and `templateKey` was not found on this file.\n* `not_found` - The file was not found, or the user does not have access\nto the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/metadata/global/boxSkillsCards": { "get": { "operationId": "get_files_id_metadata_global_boxSkillsCards", "summary": "List Box Skill cards on file", "tags": [ "Skills" ], "description": "List the Box Skills metadata cards that are attached to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns all the metadata associated with a file.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the file.", "schema": { "$ref": "#/definitions/SkillCardsMetadata" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_files_id_metadata_global_boxSkillsCards", "summary": "Create Box Skill cards on file", "tags": [ "Skills" ], "description": "Applies one or more Box Skills metadata cards to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "cards" ], "properties": { "cards": { "type": "array", "description": "A list of Box Skill cards to apply to this file.", "items": { "$ref": "#/definitions/SkillCard" } } } } } ], "responses": { "201": { "description": "Returns the instance of the template that was applied to the file,\nincluding the data that was applied to the template.", "schema": { "$ref": "#/definitions/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 for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file or metadata template could not be found.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.\n* `instance_tuple_not_found` - The metadata template could not be found.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the file.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_files_id_metadata_global_boxSkillsCards", "summary": "Update Box Skill cards on file", "tags": [ "Skills" ], "description": "Updates one or more Box Skills metadata cards to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the updated metadata template, with the\ncustom template data included.", "schema": { "$ref": "#/definitions/SkillCardsMetadata" } }, "404": { "description": "The requested file could not be found", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_files_id_metadata_global_boxSkillsCards", "summary": "Remove Box Skill cards from file", "tags": [ "Skills" ], "description": "Removes any Box Skills cards metadata from a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the cards are\nsuccessfully deleted." }, "404": { "description": "Returns an error when the file does not have an instance of the Box Skill\ncards 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\nSkill cards was not found on this file.\n* `not_found` - The file was not found, or the user does not have access\nto the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}/watermark": { "get": { "operationId": "get_files_id_watermark", "summary": "Get watermark on file", "tags": [ "Watermarks (Files)" ], "description": "Retrieve the watermark for a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns an object containing information about the\nwatermark associated for to this file.", "schema": { "$ref": "#/definitions/Watermark" } }, "404": { "description": "Returns an error if the file does not have a watermark applied.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_files_id_watermark", "summary": "Apply watermark to file", "tags": [ "Watermarks (Files)" ], "description": "Applies or update a watermark on a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "watermark" ], "properties": { "watermark": { "type": "object", "description": "The watermark to imprint on the file", "required": [ "imprint" ], "properties": { "imprint": { "type": "string", "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "enum": [ "default" ] } } } } } } ], "responses": { "200": { "description": "Returns an updated watermark if a watermark already\nexisted on this file.", "schema": { "$ref": "#/definitions/Watermark" } }, "201": { "description": "Returns a new watermark if no watermark existed on\nthis file yet.", "schema": { "$ref": "#/definitions/Watermark" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_files_id_watermark", "summary": "Remove watermark from file", "tags": [ "Watermarks (Files)" ], "description": "Removes the watermark from a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "An empty response will be returned when the watermark\nwas successfully deleted." }, "404": { "description": "Returns an error if the file did not have\na watermark applied to it", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/file_requests/{file_request_id}": { "get": { "operationId": "get_file_requests_id", "summary": "Get file request", "tags": [ "File requests" ], "description": "Retrieves the information about a file request.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a file request object.", "schema": { "$ref": "#/definitions/FileRequest" } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_file_requests_id", "summary": "Update file request", "tags": [ "File requests" ], "description": "Updates a file request. This can be used to activate or\ndeactivate a file request.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "type": "string" }, { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/FileRequestUpdateRequest" } } ], "responses": { "200": { "description": "Returns the updated file request object.", "schema": { "$ref": "#/definitions/FileRequest" } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` when the authenticated user\ndoes not have access to update the file request.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file request. This indicates that the\nfile request has changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_file_requests_id", "summary": "Delete file request", "tags": [ "File requests" ], "description": "Deletes a file request permanently.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the file request has been successfully\ndeleted." }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file request is not found or has already been deleted,\nor the user does not have access to the associated folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/file_requests/{file_request_id}/copy": { "post": { "operationId": "post_file_requests_id_copy", "summary": "Copy file request", "tags": [ "File requests" ], "description": "Copies an existing file request that is already present on one folder,\nand applies it to another folder.", "parameters": [ { "name": "file_request_id", "description": "The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/FileRequestCopyRequest" } } ], "responses": { "200": { "description": "Returns updated file request object.", "schema": { "$ref": "#/definitions/FileRequest" } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.\n\n* `access_denied_insufficient_permissions` when the authenticated user\ndoes not have access to update the file request.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file request is not found, or the user does not\nhave access to the associated folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_request_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}": { "get": { "operationId": "get_folders_id", "summary": "Get folder information", "tags": [ "Folders" ], "description": "Retrieves details for a folder, including the first 100 entries\nin the folder.\n\nTo fetch more items within the folder, please use the\n[Get items in a folder](#get-folders-id-items) endpoint.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.\n\nAdditionally this field can be used to query any metadata\napplied to the file by specifying the `metadata` field as well\nas the scope and key of the template to retrieve, for example\n`?field=metadata.enterprise_12345.contractTemplate`.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "type": "string" }, { "name": "boxapi", "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\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `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\nor folders nested within the item.", "in": "header", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns a folder, including the first 100 entries in the folder.\n\nTo fetch more items within the folder, please use the\n[Get items in a folder](#get-folders-id-items) endpoint.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/Folder" } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_folders_id", "summary": "Restore folder", "tags": [ "Trashed folders" ], "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\noriginal folder has been deleted.\n\n# Folder locking\n\nDuring this operation, part of the file tree will be locked, mainly\nthe source folder and all of its descendants, as well as the destination\nfolder.\n\nFor the duration of the operation, no other move, copy, delete, or restore\noperation can performed on any of the locked folders.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the folder.", "type": "string" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item" } } }, { "description": "Specifies an optional ID of a folder to restore the folder\nto when the original folder no longer exists.\n\nPlease be aware that this ID will only be used if the original\nfolder no longer exists. Use this ID to provide a fallback\nlocation to restore the folder to if the original location\nhas been deleted." } ] } } } } ], "responses": { "201": { "description": "Returns a folder object when the folder has been restored.", "schema": { "$ref": "#/definitions/Folder" } }, "403": { "description": "Returns an error if the user does not have access to the folder\nthe folder is being restored to, or the user does not have permission\nto restore folders from the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the folder is not in the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "* Returned an error if there is a folder with the same name\n in the destination folder.\n\n* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in process.\n\n The operation can be retried at a later point.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_folders_id", "summary": "Update folder", "description": "Updates a folder. This can be also be used to move the folder,\ncreate shared links, update collaborations, and more.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The optional new name for this folder." }, "description": { "type": "string", "description": "The optional description of this folder", "maxLength": 256 }, "sync_state": { "type": "string", "description": "Specifies whether a folder should be synced to a\nuser's device or not. This is used by Box Sync\n(discontinued) and is not used by Box Drive.", "enum": [ "synced", "not_synced", "partially_synced" ] }, "can_non_owners_invite": { "type": "boolean", "description": "Specifies if users who are not the owner\nof the folder can ****** new collaborators to the folder." }, "parent": { "type": "object", "description": "The parent folder for this folder. Use this to move\nthe folder or to restore it out of the trash.", "properties": { "id": { "type": "string", "description": "The ID of the new parent folder" } } }, "shared_link": { "allOf": [ { "description": "Defines a shared link for an item. Set this to `null` to remove\nthe shared link.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ] }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`." }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared links." }, "unshared_at": { "type": "string", "format": "date-time", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } }, { "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": { "type": "string", "enum": [ "open", "collaborators" ], "description": "When this parameter has been set, users can email files\nto the email address that has been automatically\ncreated for this folder.\n\nTo create an email address, set this property either when\ncreating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email\naddresses for collaborators will be accepted. This includes\nany email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email\naddress." } } }, { "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly\nupload files directly to the folder via email.\n\nSetting the value to `null` will disable the email address." } ] }, "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "The tags for this item. These tags are shown in\nthe Box web app and mobile apps next to an item.\n\nTo add or remove a tag, retrieve the item's current tags,\nmodify them, and then update this field.\n\nThere is a limit of 100 tags per item, and 10,000\nunique tags per enterprise." }, "is_collaboration_restricted_to_enterprise": { "type": "boolean", "description": "Specifies if new invites to this folder are restricted to users\nwithin the enterprise. This does not affect existing\ncollaborations." }, "collections": { "type": "array", "description": "An array of collections to make this folder\na member of. Currently\nwe only support the `favorites` collection.\n\nTo get the ID for a collection, use the\n[List all collections][1] endpoint.\n\nPassing an empty array `[]` or `null` will remove\nthe folder from all collections.\n\n[1]: ../advanced-files-and-folders/#get-collections", "items": { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this object" }, "type": { "type": "string", "description": "The type for this object" } } } }, "can_non_owners_view_collaborators": { "type": "boolean", "description": "Restricts collaborators who are not the owner of\nthis folder from viewing other collaborations on\nthis folder.\n\nIt also restricts non-owners from inviting new\ncollaborators.\n\nWhen setting this field to `false`, it is required\nto also set `can_non_owners_invite_collaborators` to\n`false` if it has not already been set." } } } } ], "responses": { "200": { "description": "Returns a folder object for the updated folder\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.\n\nThis call will return synchronously. This holds true even when\nmoving folders with a large a large number of items in all of its\ndescendants. For very large folders, this means the call could\ntake minutes or hours to return.", "schema": { "$ref": "#/definitions/Folder" } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot 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\n happens when a password is set for a shared link with an access type\n of `open`.\n* `item_name_too_long` when the folder name is too long.\n* `item_name_invalid` when the folder name contains\n non-valid characters.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error if the user does not have the required\naccess to perform the action.\n\n* `access_denied_insufficient_permissions`: Returned when the\n user does not have access to the folder or parent folder, or if the\n folder is being moved and a folder lock has been applied to prevent\n such operations.\n\n* `insufficient_scope`: Returned an error if the application\n does not have the right scope to update folders. Make sure\n your application has been configured to read and write all files\n and folders stored in Box.\n\n* `forbidden`: Returned when the user is not allowed to perform this\n action for other users. This can include trying to create a\n Shared Link with a `company` access level on a free account.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the folder or parent folder could not be found,\nor the authenticated user does not have access to either folder.\n\n* `not_found` when the authenticated user does not have access\n to the folder or parent folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in progress.\n\n The operation can be retried at a later point.\n\n* `item_name_in_use`: Returned if a folder with the name\n already exists in the parent folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the\nfolder has changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "503": { "description": "Returns an error when the operation takes longer\nthan 60 seconds. The operation will continue after\nthis response has been returned.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_folders_id", "summary": "Delete folder", "description": "Deletes a folder, either permanently or by moving it to\nthe trash.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "if-match", "description": "Ensures this item hasn't recently changed before\nmaking changes.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `412 Precondition Failed` if it\nhas changed since.", "in": "header", "required": false, "type": "string" }, { "name": "recursive", "description": "Delete a folder that is not empty by recursively deleting the\nfolder and all of its content.", "in": "query", "required": false, "type": "boolean" } ], "responses": { "204": { "description": "Returns an empty response when the folder is successfully deleted\nor moved to the trash." }, "403": { "description": "Returns an error if the user does not have the required\naccess to perform the action.\n\n* `access_denied_insufficient_permissions`: Returned when the\n user does not have access to the folder, or when a folder lock has been\n applied to the folder to prevent deletion.\n\n* `insufficient_scope`: Returned an error if the application\n does not have the right scope to delete folders. Make sure\n your application has been configured to read and write all files\n and folders stored in Box.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the folder could not be found,\nor the authenticated user does not have access to the folder.\n\n* `not_found` when the authenticated user does not have access\n to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "* `folder_not_empty`: Returned if the folder is not empty. Use the\n `recursive` query parameter to recursively delete the folder and\n its contents.\n* `operation_blocked_temporary`: Returned if the folder\n is locked due to another move, copy, delete or restore\n operation in progress.\n\n The operation can be retried at a later point.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the\nfolder has changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "503": { "description": "Returns an error when the operation takes longer\nthan 60 seconds. The operation will continue after\nthis response has been returned.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}/items": { "get": { "operationId": "get_folders_id_items", "summary": "List items in folder", "tags": [ "Folders" ], "description": "Retrieves a page of items in a folder. These items can be files,\nfolders, and web links.\n\nTo request more information about the folder itself, like its size,\nplease use the [Get a folder](#get-folders-id) endpoint instead.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.\n\nAdditionally this field can be used to query any metadata\napplied to the file by specifying the `metadata` field as well\nas the scope and key of the template to retrieve, for example\n`?field=metadata.enterprise_12345.contractTemplate`.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "usemarker", "description": "Specifies whether to use marker-based pagination instead of\noffset-based pagination. Only one pagination method can\nbe used at a time.\n\nBy setting this value to true, the API will return a `marker` field\nthat can be passed as a parameter to this endpoint to get the next\npage of the response.", "in": "query", "required": false, "type": "boolean" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "boxapi", "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\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `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\nor folders nested within the item.", "in": "header", "required": false, "type": "string" }, { "name": "sort", "description": "Defines the **second** attribute by which items\nare sorted.\n\nItems are always sorted by their `type` first, with\nfolders listed before files, and files listed\nbefore web links.\n\nThis parameter is not supported for marker-based pagination\non the root folder (the folder with an ID of `0`).", "in": "query", "required": false, "type": "string", "enum": [ "id", "name", "date", "size" ] }, { "name": "direction", "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", "required": false, "type": "string", "enum": [ "ASC", "DESC" ] } ], "responses": { "200": { "description": "Returns a collection of files, folders, and web links contained in a folder.", "schema": { "$ref": "#/definitions/Items" } }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders": { "post": { "operationId": "post_folders", "summary": "Create folder", "tags": [ "Folders" ], "description": "Creates a new empty folder within the specified parent folder.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "name", "parent" ], "properties": { "name": { "type": "string", "description": "The name for the new folder.\n\nThere are some restrictions to the file name. Names containing\nnon-printable ASCII characters, forward and backward slashes\n(`/`, `\\`), as well as names with trailing spaces are\nprohibited.\n\nAdditionally, the names `.` and `..` are\nnot allowed either.", "maxLength": 255, "minLength": 1 }, "parent": { "type": "object", "description": "The parent folder to create the new folder within.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of parent folder" } } }, "folder_upload_email": { "allOf": [ { "title": "Folder upload email", "type": "object", "description": "The Write Folder Upload Email object", "properties": { "access": { "type": "string", "enum": [ "open", "collaborators" ], "description": "When this parameter has been set, users can email files\nto the email address that has been automatically\ncreated for this folder.\n\nTo create an email address, set this property either when\ncreating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email\naddresses for collaborators will be accepted. This includes\nany email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email\naddress." } } }, { "description": "Setting this object enables the upload email address.\n\nThis email address can be used by users to directly\nupload files directly to the folder via email." } ] }, "sync_state": { "type": "string", "description": "Specifies whether a folder should be synced to a\nuser's device or not. This is used by Box Sync\n(discontinued) and is not used by Box Drive.", "enum": [ "synced", "not_synced", "partially_synced" ] } } } } ], "responses": { "201": { "description": "Returns a folder object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/Folder" } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot 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\n non-valid characters.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error if the user does not have the required\naccess to perform the action. This might be because they\ndon't have access to the folder or parent folder, or because\nthe application does not have permission to write files and\nfolders.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the parent folder could not be found,\nor the authenticated user does not have access to the parent\nfolder.\n\n* `not_found` when the authenticated user does not have access\n to the parent folder", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "* `operation_blocked_temporary`: Returned if either of the destination\n or source folders is locked due to another move, copy, delete or\n restore operation in process.\n\n The operation can be retried at a later point.\n\n* `item_name_in_use`: Returned if a folder with the name\n already exists in the parent folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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.", "tags": [ "Folders" ], "parameters": [ { "name": "folder_id", "description": "The unique identifier of the folder to copy.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder with the ID `0` can not be copied.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "parent" ], "properties": { "name": { "type": "string", "description": "An optional new name for the copied folder.\n\nThere are some restrictions to the file name. Names containing\nnon-printable ASCII characters, forward and backward slashes\n(`/`, `\\`), as well as names with trailing spaces are\nprohibited.\n\nAdditionally, the names `.` and `..` are\nnot allowed either.", "maxLength": 255, "minLength": 1 }, "parent": { "type": "object", "description": "The destination folder to copy the folder to.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of parent folder" } } } } } } ], "responses": { "201": { "description": "Returns a new folder object representing the copied folder.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/Folder" } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `bad_request` when a parameter is missing.\n* `item_name_too_long` when the new folder name is too long.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if either the source or destination folder\ncould not be found, or the authenticated user does not\nhave access to either folders.\n\n* `not_found` when the authenticated user does not have access\n to the parent folder", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if a folder by this name already exists\nin the destination folder, or if the destination folder\nis locked.\n\n* `item_name_in_use` when a folder with the same name already\n exists.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error when trying to copy the root folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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\nfolder. This returns all the users that have access to the folder\nor have been invited to the folder.", "tags": [ "Collaborations (List)" ], "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no\ncollaborations on this folder an empty collection will be returned.\n\nThis list includes pending collaborations, for which the `status`\nis set to `pending`, indicating invitations that have been sent but not\nyet accepted.", "schema": { "$ref": "#/definitions/Collaborations" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}/trash": { "get": { "operationId": "get_folders_id_trash", "summary": "Get trashed folder", "tags": [ "Trashed folders" ], "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\ntrash can it be retrieved with this API call. If instead one of\nits parent folders was moved to the trash, only that folder\ncan be inspected using the\n[`GET /folders/:id/trash`](e://get_folders_id_trash) API.\n\nTo list all items that have been moved to the trash, please\nuse the [`GET /folders/trash/items`](e://get-folders-trash-items/)\nAPI.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns the folder that was trashed,\nincluding information about when the it\nwas moved to the trash.", "schema": { "$ref": "#/definitions/Folder" } }, "404": { "description": "Returns an error if the folder can not be found directly\nin the trash.\n\nPlease note that a `HTTP 404` is also returned if any of\nthe folder's parent folders have been moved to the trash.\n\nIn that case, only that parent folder can be inspected using\nthe [`GET /folders/:id/trash`](e://get_folders_id_trash) API.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_folders_id_trash", "summary": "Permanently remove folder", "tags": [ "Trashed folders" ], "description": "Permanently deletes a folder that is in the trash.\nThis action cannot be undone.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the folder was\npermanently deleted." }, "404": { "description": "Returns an error if the folder is not in the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}/metadata": { "get": { "operationId": "get_folders_id_metadata", "summary": "List metadata instances on folder", "tags": [ "Metadata instances (Folders)" ], "description": "Retrieves all metadata for a given folder. This can not be used on the root\nfolder with ID `0`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns all the metadata associated with a folder.\n\nThis API does not support pagination and will therefore always return\nall of the metadata associated to the folder.", "schema": { "$ref": "#/definitions/Metadatas" } }, "403": { "description": "Returned when the request parameters are not valid.\n\n* `forbidden` - this operation is not allowed on the Root folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when the user does not have access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo": { "get": { "operationId": "get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Get classification on folder", "tags": [ "Classifications on folders" ], "description": "Retrieves the classification metadata instance that\nhas been applied to a folder.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" } ], "responses": { "201": { "description": "Returns an instance of the `securityClassification` metadata\ntemplate, which contains a `Box__Security__Classification__Key`\nfield that lists all the classifications available to this\nenterprise.", "schema": { "$ref": "#/definitions/Classification" } }, "403": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this folder or the user does not have access to the\nfolder.\n\n* `instance_not_found` - The metadata template was not applied to the\nfolder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Add classification to folder", "tags": [ "Classifications on folders" ], "description": "Adds a classification to a folder by specifying the label of the\nclassification to add.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "Box__Security__Classification__Key": { "type": "string", "description": "The name of the classification to apply to this folder.\n\nTo list the available classifications in an enterprise,\nuse the classification API to retrieve the\n[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)\nwhich lists all available classification keys." } } } } ], "responses": { "201": { "description": "Returns the classification template instance\nthat was applied to the folder.", "schema": { "$ref": "#/definitions/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 for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the folder or metadata template could not be found.\n\n* `not_found` - The folder could not be found, or the user does not have\naccess to the folder.\n* `instance_tuple_not_found` - The metadata template could not be found.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the folder.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Update classification on folder", "tags": [ "Classifications on folders" ], "description": "Updates a classification on a folder.\n\nThe classification can only be updated if a classification has already been\napplied to the folder before. When editing classifications, only values are\ndefined for the enterprise will be accepted.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the updated classification metadata template instance.", "schema": { "$ref": "#/definitions/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\nPatch operations.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo", "summary": "Remove classification from folder", "tags": [ "Classifications on folders" ], "description": "Removes any classifications from a folder.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the classification is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the folder does not have any classification applied\nto it, or when the user does not have access to the\nfolder.\n\n* `instance_not_found` - An instance of the classification metadata\ntemplate with the was not found on this folder.\n* `not_found` - The folder was not found, or the user does not have access\nto the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}/metadata/{scope}/{template_key}": { "get": { "operationId": "get_folders_id_metadata_id_id", "summary": "Get metadata instance on folder", "tags": [ "Metadata instances (Folders)" ], "description": "Retrieves the instance of a metadata template that has been applied to a\nfolder. This can not be used on the root folder with ID `0`.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "201": { "description": "An instance of the metadata template that includes\nadditional \"key:value\" pairs defined by the user or\nan application.", "schema": { "$ref": "#/definitions/Metadata" } }, "403": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the metadata template specified\nwas not applied to this folder or the user does not have access to the\nfolder.\n\n* `instance_not_found` - The metadata template was not applied to the\nfolder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed. This often happens when the\nfolder ID is not valid or the root folder with ID `0`.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_folders_id_metadata_id_id", "summary": "Create metadata instance on folder", "tags": [ "Metadata instances (Folders)" ], "description": "Applies an instance of a metadata template to a folder.\n\nIn most cases only values that are present in the metadata template\nwill be accepted, except for the `global.properties` template which accepts\nany key-value pair.\n\nTo display the metadata template in the Box web app the enterprise needs to be\nconfigured to enable **Cascading Folder Level Metadata** for the user in the\nadmin console.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "additionalProperties": { "type": "string", "description": "A value for each of the fields that are present on the metadata\ntemplate.\n\nFor the `global.properties` template this can be an a list of zero\nor more fields, as this template allows for any generic key-value\npairs to be stored on the template.", "x-box-example-key": "name" } } } ], "responses": { "201": { "description": "Returns the instance of the template that was applied to the folder,\nincluding the data that was applied to the template.", "schema": { "$ref": "#/definitions/Metadata" } }, "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 for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the folder or metadata template could not be found.\n\n* `not_found` - The folder could not be found, or the user does not have\naccess to the folder.\n* `instance_tuple_not_found` - The metadata template could not be found.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error when an instance of this metadata template is already\npresent on the folder.\n\n* `tuple_already_exists` - An instance of them metadata template already\nexists on the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_folders_id_metadata_id_id", "summary": "Update metadata instance on folder", "tags": [ "Metadata instances (Folders)" ], "description": "Updates a piece of metadata on a folder.\n\nThe metadata instance can only be updated if the template has already been\napplied to the folder before. When editing metadata, only values that match\nthe metadata template schema will be accepted.\n\nThe update is applied atomically. If any errors occur during the\napplication of the operations, the metadata instance will not be changed.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the updated metadata template instance, with the\ncustom template data included.", "schema": { "$ref": "#/definitions/Metadata" } }, "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\nPatch objects.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error in some edge cases when the request body is not a valid\narray of JSON Patch items.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_folders_id_metadata_id_id", "summary": "Remove metadata instance from folder", "tags": [ "Metadata instances (Folders)" ], "description": "Deletes a piece of folder metadata.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the metadata is\nsuccessfully deleted." }, "400": { "description": "Returned when the request parameters are not valid. This may happen of the\n`scope` is not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the folder does not have an instance of the metadata\ntemplate applied to it, or when the user does not have access to the\nfolder.\n\n* `instance_not_found` - An instance of the metadata template with the\ngiven `scope` and `templateKey` was not found on this folder.\n* `not_found` - The folder was not found, or the user does not have access\nto the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned when the method was not allowed. This often happens when the\nfolder ID is not valid or the root folder with ID `0`.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/trash/items": { "get": { "operationId": "get_folders_trash_items", "summary": "List trashed items", "tags": [ "Trashed items" ], "description": "Retrieves the files and folders that have been moved\nto the trash.\n\nAny attribute in the full files or folders objects can be passed\nin with the `fields` parameter to retrieve those specific\nattributes that are not returned by default.\n\nThis endpoint defaults to use offset-based pagination, yet also supports\nmarker-based pagination using the `marker` parameter.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 }, { "name": "usemarker", "description": "Specifies whether to use marker-based pagination instead of\noffset-based pagination. Only one pagination method can\nbe used at a time.\n\nBy setting this value to true, the API will return a `marker` field\nthat can be passed as a parameter to this endpoint to get the next\npage of the response.", "in": "query", "required": false, "type": "boolean" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "direction", "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", "required": false, "type": "string", "enum": [ "ASC", "DESC" ] }, { "name": "sort", "description": "Defines the **second** attribute by which items\nare sorted.\n\nItems are always sorted by their `type` first, with\nfolders listed before files, and files listed\nbefore web links.\n\nThis parameter is not supported when using marker-based pagination.", "in": "query", "required": false, "type": "string", "enum": [ "id", "name", "date", "size" ] } ], "responses": { "200": { "description": "Returns a list of items that have been deleted", "schema": { "$ref": "#/definitions/Items" } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `invalid_parameter` can appear when the `sort`, `direction` or `offset`\nparameter is provided when using marker based pagination, or when the\n`marker` parameter is provided but `usemarker` is set to `false` or\n`null`.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}/watermark": { "get": { "operationId": "get_folders_id_watermark", "summary": "Get watermark for folder", "tags": [ "Watermarks (Folders)" ], "description": "Retrieve the watermark for a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns an object containing information about the\nwatermark associated for to this folder.", "schema": { "$ref": "#/definitions/Watermark" } }, "404": { "description": "Returns an error if the folder does not have a watermark applied.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_folders_id_watermark", "summary": "Apply watermark to folder", "tags": [ "Watermarks (Folders)" ], "description": "Applies or update a watermark on a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "watermark" ], "properties": { "watermark": { "type": "object", "description": "The watermark to imprint on the folder", "required": [ "imprint" ], "properties": { "imprint": { "type": "string", "description": "The type of watermark to apply.\n\nCurrently only supports one option.", "enum": [ "default" ] } } } } } } ], "responses": { "200": { "description": "Returns an updated watermark if a watermark already\nexisted on this folder.", "schema": { "$ref": "#/definitions/Watermark" } }, "201": { "description": "Returns a new watermark if no watermark existed on\nthis folder yet.", "schema": { "$ref": "#/definitions/Watermark" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_folders_id_watermark", "summary": "Remove watermark from folder", "tags": [ "Watermarks (Folders)" ], "description": "Removes the watermark from a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "An empty response will be returned when the watermark\nwas successfully deleted." }, "404": { "description": "Returns an error if the folder did not have\na watermark applied to it", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folder_locks": { "get": { "operationId": "get_folder_locks", "summary": "List folder locks", "tags": [ "Folder Locks" ], "description": "Retrieves folder lock details for a given folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "query", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns details for all folder locks applied to the folder, including the\nlock type and user that applied the lock.", "schema": { "$ref": "#/definitions/FolderLocks" } }, "403": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_folder_locks", "summary": "Create folder lock", "tags": [ "Folder Locks" ], "description": "Creates a folder lock on a folder, preventing it from being moved and/or\ndeleted.", "responses": { "200": { "description": "Returns the instance of the folder lock that was applied to the folder,\nincluding the user that applied the lock and the operations set.", "schema": { "$ref": "#/definitions/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\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the folder could not be found.\n\n* `not_found` - The folder could not be found, the user does not have\naccess to the folder, or the user making call is not an owner or co-owner\nof folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "folder" ], "properties": { "locked_operations": { "type": "object", "description": "The operations to lock for the folder. If `locked_operations` is\nincluded in the request, both `move` and `delete` must also be\nincluded and both set to `true`.", "required": [ "move", "delete" ], "properties": { "move": { "type": "boolean", "description": "Whether moving the folder should be locked." }, "delete": { "type": "boolean", "description": "Whether deleting the folder should be locked." } } }, "folder": { "type": "object", "description": "The folder to apply the lock to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The content type the lock is being applied to. Only `folder`\nis supported." }, "id": { "type": "string", "description": "The ID of the folder." } } } } } } ] } }, "/folder_locks/{folder_lock_id}": { "delete": { "operationId": "delete_folder_locks_id", "summary": "Delete folder lock", "description": "Deletes a folder lock on a given folder.", "tags": [ "Folder Locks" ], "parameters": [ { "name": "folder_lock_id", "description": "The ID of the folder lock.", "in": "path", "required": true, "type": "string" } ], "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\naccess to perform the action.\n\n* `access_denied_insufficient_permissions`: Returned when the\n user does not have access to the folder.\n\n* `insufficient_scope`: Returned an error if the application\n does not have the right scope to delete folders. Make sure\n your application has been configured to read and write all files\n and folders stored in Box.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the folder could not be found,\nor the authenticated user does not have access to the folder.\n\n* `not_found` when the authenticated user does not have access\n to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_templates": { "get": { "operationId": "get_metadata_templates", "summary": "Find metadata template by instance ID", "tags": [ "Metadata templates" ], "description": "Finds a metadata template by searching for the ID of an instance of the\ntemplate.", "parameters": [ { "name": "metadata_instance_id", "description": "The ID of an instance of the metadata template to find.", "in": "query", "required": true, "type": "string", "format": "uuid" } ], "responses": { "200": { "description": "Returns a list containing the 1 metadata template that matches the\ninstance ID.", "schema": { "$ref": "#/definitions/MetadataTemplates" } }, "400": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema": { "get": { "operationId": "get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema", "summary": "List all classifications", "tags": [ "Classifications" ], "description": "Retrieves the classification metadata template and lists all the\nclassifications available to this enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "responses": { "200": { "description": "Returns the `securityClassification` metadata template, which contains\na `Box__Security__Classification__Key` field that lists all the\nclassifications available to this enterprise.", "schema": { "$ref": "#/definitions/ClassificationTemplate" } }, "400": { "description": "Returned if any of the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [] }, "delete": { "operationId": "delete_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema", "summary": "Delete all classifications", "tags": [ "Classifications" ], "description": "Delete all classifications by deleting the classification\nmetadata template.", "responses": { "204": { "description": "Returns an empty response when the metadata\ntemplate for classifications is successfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [] } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add", "summary": "Add classification", "tags": [ "Classifications" ], "description": "Adds one or more new classifications to the list of classifications\navailable to the enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "schema": { "$ref": "#/definitions/ClassificationTemplate" } }, "400": { "description": "Returned if any of the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [] } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update", "summary": "Update classification", "tags": [ "Classifications" ], "description": "Updates the labels and descriptions of one or more classifications\navailable to the enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "schema": { "$ref": "#/definitions/ClassificationTemplate" } }, "400": { "description": "Returned if any of the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [] } }, "/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#delete": { "put": { "operationId": "put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#delete", "summary": "Delete classification", "tags": [ "Classifications" ], "description": "Removes a classification from the list of classifications\navailable to the enterprise.\n\nThis API can also be called by including the enterprise ID in the\nURL explicitly, for example\n`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.", "responses": { "200": { "description": "Returns the updated `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "schema": { "$ref": "#/definitions/ClassificationTemplate" } }, "400": { "description": "Returned if any of the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [] } }, "/metadata_templates/{scope}/{template_key}/schema": { "get": { "operationId": "get_metadata_templates_id_id_schema", "summary": "Get metadata template by name", "tags": [ "Metadata templates" ], "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\nan enterprise or globally, or list all templates applied to a file or folder.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the metadata template matching the `scope`\nand `template` name.", "schema": { "$ref": "#/definitions/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\n recognised. Please make sure to use either `enterprise` or `global` as\n the `scope` value.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when a template with the given `scope` and `template_key` can not\nbe found.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_metadata_templates_id_id_schema", "tags": [ "Metadata templates" ], "summary": "Update metadata template", "description": "Updates a metadata template.\n\nThe metadata template can only be updated if the template\nalready exists.\n\nThe update is applied atomically. If any errors occur during the\napplication of the operations, the metadata template will not be changed.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the updated metadata template, with the\ncustom template data included.", "schema": { "$ref": "#/definitions/MetadataTemplate" } }, "400": { "description": "The request body does not contain a valid metadata schema.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "The request body contains a scope that the user is not\nallowed to create templates for.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "The requested template could not be found", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_metadata_templates_id_id_schema", "summary": "Remove metadata template", "tags": [ "Metadata templates" ], "description": "Delete a metadata template and its instances.\nThis deletion is permanent and can not be reversed.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "in": "path", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the metadata\ntemplate is successfully deleted." }, "400": { "description": "Request body does not contain a valid metadata schema.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Request body contains a scope that the user is not allowed to\ncreate a template for.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_templates/{template_id}": { "get": { "operationId": "get_metadata_templates_id", "summary": "Get metadata template by ID", "tags": [ "Metadata templates" ], "description": "Retrieves a metadata template by its ID.", "parameters": [ { "name": "template_id", "required": true, "in": "path", "description": "The ID of the template", "type": "string" } ], "responses": { "200": { "description": "Returns the metadata template that matches the ID.", "schema": { "$ref": "#/definitions/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\n is not recognised.", "schema": { "$ref": "#/definitions/MetadataTemplate" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_templates/global": { "get": { "operationId": "get_metadata_templates_global", "summary": "List all global metadata templates", "tags": [ "Metadata templates" ], "description": "Used to retrieve all generic, global metadata templates available to all\nenterprises using Box.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns all of the metadata templates available to all enterprises\nand their corresponding schema.", "schema": { "$ref": "#/definitions/MetadataTemplates" } }, "400": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_templates/enterprise": { "get": { "operationId": "get_metadata_templates_enterprise", "summary": "List all metadata templates for enterprise", "tags": [ "Metadata templates" ], "description": "Used to retrieve all metadata templates created to be used specifically within\nthe user's enterprise", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns all of the metadata templates within an enterprise\nand their corresponding schema.", "schema": { "$ref": "#/definitions/MetadataTemplates" } }, "400": { "description": "Returned when the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_templates/schema": { "post": { "operationId": "post_metadata_templates_schema", "summary": "Create metadata template", "tags": [ "Metadata templates" ], "description": "Creates a new metadata template that can be applied to\nfiles and folders.", "responses": { "201": { "description": "The schema representing the metadata template created.", "schema": { "$ref": "#/definitions/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\ncases this response will include extra details on what fields are missing.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned when the user does not have the permission to create the metadata\ntemplate. This can happen for a few reasons, most commonly when the user\ndoes not have (co-)admin permissions, or the application tries to create a\ntemplate with the `global` scope.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "scope", "displayName" ], "properties": { "scope": { "type": "string", "description": "The scope of the metadata template to create. Applications can\nonly create templates for use within the authenticated user's\nenterprise.\n\nThis value needs to be set to `enterprise`, as `global` scopes can\nnot be created by applications." }, "templateKey": { "type": "string", "description": "A unique identifier for the template. This identifier needs to be\nunique across the enterprise for which the metadata template is\nbeing created.\n\nWhen not provided, the API will create a unique `templateKey`\nbased on the value of the `displayName`.", "maxLength": 64, "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" }, "displayName": { "type": "string", "description": "The display name of the template.", "maxLength": 4096 }, "hidden": { "type": "boolean", "description": "Defines if this template is visible in the Box web app UI, or if\nit is purely intended for usage through the API.", "default": false }, "fields": { "type": "array", "description": "An ordered list of template fields which are part of the template.\nEach field can be a regular text field, date field, number field,\nas well as a single or multi-select list.", "items": { "title": "Metadata Field (Write)", "description": "A field within a metadata template. Fields can be a basic text, date, or\nnumber field, or a list of options.", "required": [ "type", "key", "displayName" ], "type": "object", "properties": { "type": { "type": "string", "description": "The type of field. The basic fields are a `string` field for text, a\n`float` field for numbers, and a `date` fields to present the user with a\ndate-time picker.\n\nAdditionally, metadata templates support an `enum` field for a basic list\nof items, and ` multiSelect` field for a similar list of items where the\nuser can select more than one value.", "enum": [ "string", "float", "date", "enum", "multiSelect" ] }, "key": { "type": "string", "description": "A unique identifier for the field. The identifier must\nbe unique within the template to which it belongs.", "maxLength": 256 }, "displayName": { "type": "string", "description": "The display name of the field as it is shown to the user in the web and\nmobile apps.", "maxLength": 4096 }, "description": { "type": "string", "description": "A description of the field. This is not shown to the user.", "maxLength": 4096 }, "hidden": { "type": "boolean", "description": "Whether this field is hidden in the UI for the user and can only be set\nthrough the API instead." }, "options": { "description": "A list of options for this field. This is used in combination with the\n`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`.\nOptions represent the value(s) a user can select for the field either through\nthe UI or through the API.", "required": [ "key" ], "properties": { "key": { "description": "The text value of the option. This represents both the display name of the\noption and the internal key used when updating templates.", "type": "string" } } } } } } }, "copyInstanceOnItemCopy": { "type": "boolean", "description": "Whether or not to copy any metadata attached to a file or folder\nwhen it is copied. By default, metadata is not copied along with a\nfile or folder when it is copied.", "default": false } } } } ] } }, "/metadata_templates/schema#classifications": { "post": { "operationId": "post_metadata_templates_schema#classifications", "summary": "Add initial classifications", "tags": [ "Classifications" ], "description": "When an enterprise does not yet have any classifications, this API call\ninitializes the classification template with an initial set of\nclassifications.\n\nIf an enterprise already has a classification, the template will already\nexist and instead an API call should be made to add additional\nclassifications.", "responses": { "200": { "description": "Returns a new `securityClassification` metadata template, which\ncontains a `Box__Security__Classification__Key` field that lists all\nthe classifications available to this enterprise.", "schema": { "$ref": "#/definitions/ClassificationTemplate" } }, "400": { "description": "Returned if any of the request parameters are not valid.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned when a template name is not correct. Please make sure\nthe URL for the request is correct.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "scope", "displayName" ], "properties": { "scope": { "type": "string", "description": "The scope in which to create the classifications. This should\nbe `enterprise` or `enterprise_{id}` where `id` is the unique\nID of the enterprise.", "enum": [ "enterprise" ] }, "templateKey": { "type": "string", "description": "`securityClassification-6VMVochwUWo`", "enum": [ "securityClassification-6VMVochwUWo" ] }, "displayName": { "type": "string", "description": "`Classification`", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "description": "`false`" }, "copyInstanceOnItemCopy": { "type": "boolean", "description": "`false`" }, "fields": { "type": "array", "description": "The classification template holds one field, which holds\nall the valid classification values.", "items": { "type": "object", "description": "The `enum` field which holds all the valid classification\nvalues.", "properties": { "type": { "type": "string", "description": "`enum`", "enum": [ "enum" ] }, "key": { "type": "string", "description": "`Box__Security__Classification__Key`", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { "type": "string", "description": "`Classification`", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "description": "`false`" }, "options": { "type": "array", "description": "The actual list of classifications that are present on\nthis template.", "items": { "type": "object", "description": "An individual classification.", "properties": { "key": { "type": "string", "description": "The display name and key this classification. This\nwill be show in the Box UI." }, "staticConfig": { "type": "object", "description": "Additional information about the classification.", "properties": { "classification": { "type": "object", "description": "Additional information about the classification.", "properties": { "classificationDefinition": { "type": "string", "description": "A longer description of the classification." }, "colorID": { "type": "number", "description": "An identifier used to assign a color to\na classification label.\n\nMapping between a `colorID` and a color may\nchange without notice. Currently, the color\nmappings 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" } } } } } } } } } } } } } } ] } }, "/metadata_cascade_policies": { "get": { "operationId": "get_metadata_cascade_policies", "summary": "List metadata cascade policies", "tags": [ "Metadata cascade policies" ], "description": "Retrieves a list of all the metadata cascade policies\nthat are applied to a given folder. This can not be used on the root\nfolder with ID `0`.", "parameters": [ { "name": "folder_id", "in": "query", "required": true, "description": "Specifies which folder to return policies for. This can not be used on the\nroot folder with ID `0`.", "type": "string" }, { "name": "owner_enterprise_id", "in": "query", "description": "The ID of the enterprise ID for which to find metadata\ncascade policies. If not specified, it defaults to the\ncurrent enterprise.", "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns a list of metadata cascade policies", "schema": { "$ref": "#/definitions/MetadataCascadePolicies" } }, "400": { "description": "Returns an error when any of the parameters are not in a valid format.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error when the folder can not be accessed. This error often\nhappens when accessing the root folder with ID `0`.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the folder can not be found or the user does not\nhave access to the folder.\n\n* `not_found` - The folder could not be found or the user does not have\n access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_metadata_cascade_policies", "summary": "Create metadata cascade policy", "tags": [ "Metadata cascade policies" ], "description": "Creates a new metadata cascade policy that applies a given\nmetadata template to a given folder and automatically\ncascades it down to any files within that folder.\n\nIn order for the policy to be applied a metadata instance must first\nbe applied to the folder the policy is to be applied to.", "responses": { "201": { "description": "Returns a new of metadata cascade policy", "schema": { "$ref": "#/definitions/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\nnot in a valid format.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error when trying to apply a policy to a restricted folder, for\nexample the root folder with ID `0`.\n\n* `forbidden` - Although the folder ID was valid and the user has access\nto the folder, the policy could not be applied to this folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the template or folder can not be found, or when the\nuser does not have access to the folder or template.\n\n* `instance_tuple_not_found` - The template could not be found or the user\ndoes not have access to the template.\n* `not_found` - The folder could not be found or the user\ndoes not have access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error when a policy for this folder and template is already in\nplace.\n\n* `tuple_already_exists` - A cascade policy for this combination of\n`folder_id`, `scope` and `templateKey` already exists.", "schema": { "$ref": "#/definitions/ConflictError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "folder_id", "scope", "templateKey" ], "properties": { "folder_id": { "type": "string", "description": "The ID of the folder to apply the policy to. This folder will\nneed to already have an instance of the targeted metadata\ntemplate applied to it." }, "scope": { "description": "The scope of the targeted metadata template. This template will\nneed to already have an instance applied to the targeted folder.", "type": "string", "enum": [ "global", "enterprise" ] }, "templateKey": { "type": "string", "description": "The key of the targeted metadata template. This template will\nneed to already have an instance applied to the targeted folder.\n\nIn many cases the template key is automatically derived\nof its display name, for example `Contract Template` would\nbecome `contractTemplate`. In some cases the creator of the\ntemplate will have provided its own template key.\n\nPlease [list the templates for an enterprise][list], or\nget all instances on a [file][file] or [folder][folder]\nto inspect a template's key.\n\n[list]: e://get-metadata-templates-enterprise\n[file]: e://get-files-id-metadata\n[folder]: e://get-folders-id-metadata" } } } } ] } }, "/metadata_cascade_policies/{metadata_cascade_policy_id}": { "get": { "operationId": "get_metadata_cascade_policies_id", "summary": "Get metadata cascade policy", "tags": [ "Metadata cascade policies" ], "description": "Retrieve a specific metadata cascade policy assigned to a folder.", "parameters": [ { "name": "metadata_cascade_policy_id", "description": "The ID of the metadata cascade policy.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a metadata cascade policy", "schema": { "$ref": "#/definitions/MetadataCascadePolicy" } }, "404": { "description": "Returns an error when the policy can not be found or the user does not\nhave 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\n access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_metadata_cascade_policies_id", "summary": "Remove metadata cascade policy", "tags": [ "Metadata cascade policies" ], "description": "Deletes a metadata cascade policy.", "parameters": [ { "name": "metadata_cascade_policy_id", "description": "The ID of the metadata cascade policy.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the policy\nis successfully deleted." }, "404": { "description": "Returns an error when the policy can not be found or the user does not\nhave 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\n access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_cascade_policies/{metadata_cascade_policy_id}/apply": { "post": { "operationId": "post_metadata_cascade_policies_id_apply", "summary": "Force-apply metadata cascade policy to folder", "tags": [ "Metadata cascade policies" ], "description": "Force the metadata on a folder with a metadata cascade policy to be applied to\nall of its children. This can be used after creating a new cascade policy to\nenforce the metadata to be cascaded down to all existing files within that\nfolder.", "parameters": [ { "name": "metadata_cascade_policy_id", "required": true, "in": "path", "description": "The ID of the cascade policy to force-apply.", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "conflict_resolution" ], "properties": { "conflict_resolution": { "type": "string", "enum": [ "none", "overwrite" ], "description": "Describes the desired behavior when dealing with the conflict\nwhere a metadata template already has an instance applied\nto a child.\n\n* `none` will preserve the existing value on the file\n* `overwrite` will force-apply the templates values over\n any existing values." } } } } ], "responses": { "202": { "description": "Returns an empty response when the API call was successful. The metadata\ncascade operation will be performed asynchronously.\n\nThe API call will return directly, before the cascade operation\nis complete. There is currently no API to check for the status of this\noperation." }, "404": { "description": "Returns an error when the policy can not be found or the user does not\nhave 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\n access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/metadata_queries/execute_read": { "post": { "operationId": "post_metadata_queries_execute_read", "summary": "Query files/folders by metadata", "tags": [ "Search" ], "description": "Create a search using SQL-like syntax to return items that match specific\nmetadata.\n\nBy default, this endpoint returns only the most basic info about the items for\nwhich the query matches. To get additional fields for each item, including any\nof the metadata, use the `fields` attribute in the query.", "responses": { "200": { "description": "Returns a list of files and folders that match this metadata query.", "schema": { "$ref": "#/definitions/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\nincorrect. This can mean the `query` is incorrect, as well as some cases\nwhere the `from` value does not represent a valid template.\n* `unexpected_json_type` - An argument from the `query` string is not\npresent in `query_param`. For example, `query` of `name = :name` requires\nthe `query_param` to include a value for the `name` argument, for example\n`{ \"name\": \"Box, Inc\" }`.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when a metadata template with the given `scope` and\n`templateKey` can not be found. The error response will include extra\ndetails.\n\n* `instance_not_found` - The template could not be found. Please make sure\nto use the full template scope including the enterprise ID, like\n`enterprise_12345`.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/MetadataQuery" } } ] } }, "/metadata_query_indices": { "get": { "operationId": "get_metadata_query_indices", "summary": "List metadata query indices", "tags": [ "Search" ], "description": "Retrieves the metadata query indices for a given scope and template key.", "parameters": [ { "name": "scope", "description": "The scope of the metadata template", "in": "query", "required": true, "type": "string", "enum": [ "global", "enterprise" ] }, { "name": "template_key", "description": "The name of the metadata template", "in": "query", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a collection of metadata query indices for scope and template key.", "schema": { "$ref": "#/definitions/MetadataQueryIndices" } }, "400": { "description": "Returns an error when any of the parameters are not in a valid format.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the scope and template combination cannot be found.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/comments/{comment_id}": { "get": { "operationId": "get_comments_id", "summary": "Get comment", "tags": [ "Comments" ], "description": "Retrieves the message and metadata for a specific comment, as well\nas information on the user who created the comment.", "parameters": [ { "name": "comment_id", "description": "The ID of the comment.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns a full comment object.", "schema": { "$ref": "#/definitions/Comment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_comments_id", "summary": "Update comment", "tags": [ "Comments" ], "description": "Update the message of a comment.", "parameters": [ { "name": "comment_id", "description": "The ID of the comment.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The text of the comment to update" } } } } ], "responses": { "200": { "description": "Returns the updated comment object.", "schema": { "$ref": "#/definitions/Comment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_comments_id", "summary": "Remove comment", "tags": [ "Comments" ], "description": "Permanently deletes a comment.", "parameters": [ { "name": "comment_id", "description": "The ID of the comment.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the comment has been deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/comments": { "post": { "operationId": "post_comments", "tags": [ "Comments" ], "summary": "Create comment", "description": "Adds a comment by the user to a specific file, or\nas a reply to an other comment.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "The text of the comment.\n\nTo mention a user, use the `tagged_message`\nparameter instead." }, "tagged_message": { "type": "string", "description": "The text of the comment, including `@[user_id:name]`\nsomewhere in the message to mention another user, which\nwill send them an email notification, letting them know\nthey have been mentioned.\n\nThe `user_id` is the target user's ID, where the `name`\ncan be any custom phrase. In the Box UI this name will\nlink to the user's profile.\n\nIf you are not mentioning another user, use `message`\ninstead." }, "item": { "type": "object", "description": "The item to attach the comment to.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the item" }, "type": { "type": "string", "description": "The type of the item that this comment will be placed on.", "enum": [ "file", "comment" ] } } } } } } ], "responses": { "201": { "description": "Returns the newly created comment object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields.", "schema": { "$ref": "#/definitions/Comment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/collaborations/{collaboration_id}": { "get": { "operationId": "get_collaborations_id", "summary": "Get collaboration", "tags": [ "Collaborations" ], "description": "Retrieves a single collaboration.", "parameters": [ { "name": "collaboration_id", "description": "The ID of the collaboration", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns a collaboration object.", "schema": { "$ref": "#/definitions/Collaboration" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_collaborations_id", "tags": [ "Collaborations" ], "summary": "Update collaboration", "description": "Updates a collaboration.\n\nCan be used to change the owner of an item, or to\naccept collaboration invites.", "parameters": [ { "name": "collaboration_id", "description": "The ID of the collaboration", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "The level of access granted.", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner", "owner" ] }, "status": { "type": "string", "description": "\nSet the status of a `pending` collaboration invitation,\neffectively accepting, or rejecting the ******.", "enum": [ "pending", "accepted", "rejected" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Update the expiration date for the collaboration. At this date,\nthe collaboration will be automatically removed from the item.\n\nThis feature will only work if the **Automatically remove invited\ncollaborators: Allow folder owners to extend the expiry date**\nsetting has been enabled in the **Enterprise Settings**\nof the **Admin Console**. When the setting is not enabled,\ncollaborations can not have an expiry date and a value for this\nfield will be result in an error.\n\nAdditionally, a collaboration can only be given an\nexpiration if it was created after the **Automatically remove\ninvited collaborator** setting was enabled." }, "can_view_path": { "type": "boolean", "description": "Determines if the invited users can see the entire parent path to\nthe associated folder. The user will not gain privileges in any\nparent folder and therefore can not see content the user is not\ncollaborated on.\n\nBe aware that this meaningfully increases the time required to load the\ninvitee's **All Files** page. We recommend you limit the number of\ncollaborations with `can_view_path` enabled to 1,000 per user." } } } } ], "responses": { "200": { "description": "Returns an updated collaboration object unless the owner has changed.", "schema": { "$ref": "#/definitions/Collaboration" } }, "204": { "description": "If the role is changed to `owner`, the collaboration is deleted\nand a new collaboration is created. The previous `owner` of\nthe old collaboration will be a `co-owner` on the new collaboration.", "schema": { "$ref": "#/definitions/Collaboration" } }, "403": { "description": "Returns an error if the authenticated user does not have the right\npermissions to update the collaboration.\n\nAdditionally, this error may occur when attempting to update the\n`expires_at` field for the collaboration without the **Automatically\nremove invited collaborators: Allow folder owners to extend the expiry\ndate** setting enabled in the admin dashboard of the enterprise.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_collaborations_id", "summary": "Remove collaboration", "tags": [ "Collaborations" ], "description": "Deletes a single collaboration.", "parameters": [ { "name": "collaboration_id", "description": "The ID of the collaboration", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "A blank response is returned if the collaboration was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/collaborations": { "get": { "operationId": "get_collaborations", "summary": "List pending collaborations", "tags": [ "Collaborations (List)" ], "description": "Retrieves all pending collaboration invites for this user.", "parameters": [ { "name": "status", "description": "The status of the collaborations to retrieve", "in": "query", "required": true, "type": "string", "enum": [ "pending" ] }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a collection of pending collaboration objects.\n\nIf the user has no pending collaborations, the collection\nwill be empty.", "schema": { "$ref": "#/definitions/Collaborations" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_collaborations", "tags": [ "Collaborations" ], "summary": "Create collaboration", "description": "Adds a collaboration for a single user or a single group to a file\nor folder.\n\nCollaborations can be created using email address, user IDs, or a\ngroup IDs.\n\nIf a collaboration is being created with a group, access to\nthis endpoint is dependent on the group's ability to be invited.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "notify", "description": "Determines if users should receive email notification\nfor the action performed.", "in": "query", "required": false, "type": "boolean" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "item", "accessible_by", "role" ], "properties": { "item": { "type": "object", "description": "The item to attach the comment to.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "The type of the item that this collaboration will be\ngranted access to", "enum": [ "file", "folder" ] }, "id": { "type": "string", "description": "The ID of the item that will be granted access to" } } }, "accessible_by": { "type": "object", "description": "The user or group to give access to the item.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of collaborator to ******.", "enum": [ "user", "group" ] }, "id": { "type": "string", "description": "The ID of the user or group.\n\nAlternatively, use `login` to specify a user by email\naddress." }, "login": { "type": "string", "description": "The email address of the user to grant access to the item.\n\nAlternatively, use `id` to specify a user by user ID." } } }, "role": { "type": "string", "description": "The level of access granted.", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "can_view_path": { "type": "boolean", "description": "Determines if the invited users can see the entire parent path to\nthe associated folder. The user will not gain privileges in any\nparent folder and therefore can not see content the user is not\ncollaborated on.\n\nBe aware that this meaningfully increases the time required to load the\ninvitee's **All Files** page. We recommend you limit the number of\ncollaborations with `can_view_path` enabled to 1,000 per user." }, "expires_at": { "type": "string", "format": "date-time", "description": "Set the expiration date for the collaboration. At this date, the\ncollaboration will be automatically removed from the item.\n\nThis feature will only work if the **Automatically remove invited\ncollaborators: Allow folder owners to extend the expiry date**\nsetting has been enabled in the **Enterprise Settings**\nof the **Admin Console**. When the setting is not enabled,\ncollaborations can not have an expiry date and a value for this\nfield will be result in an error." } } } } ], "responses": { "201": { "description": "Returns a new collaboration object.", "schema": { "$ref": "#/definitions/Collaboration" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/search": { "get": { "operationId": "get_search", "summary": "Search for content", "tags": [ "Search" ], "description": "Searches for files, folders, web links, and shared files across the\nusers content or across the entire enterprise.", "parameters": [ { "name": "query", "description": "The string to search for. This query is matched against item names,\ndescriptions, text content of files, and various other fields of\nthe different item types.\n\nThis parameter supports a variety of operators to further refine\nthe results returns.\n\n* `\"\"` - by wrapping a query in double quotes only exact matches are\n returned by the API. Exact searches do not return search matches\n based on specific character sequences. Instead, they return\n matches based on phrases, that is, word sequences. For example:\n A search for `\"Blue-Box\"` may return search results including\n the sequence `\"blue.box\"`, `\"Blue Box\"`, and `\"Blue-Box\"`;\n any item containing the words `Blue` and `Box` consecutively, in\n the order specified.\n* `AND` - returns items that contain both the search terms. For\n example, a search for `marketing AND BoxWorks` returns items\n that have both `marketing` and `BoxWorks` within its text in any order.\n It does not return a result that only has `BoxWorks` in its text.\n* `OR` - returns items that contain either of the search terms. For\n example, a search for `marketing OR BoxWorks` returns a result that\n has either `marketing` or `BoxWorks` within its text. Using this\n operator is not necessary as we implicitly interpret multi-word\n queries as `OR` unless another supported boolean term is used.\n* `NOT` - returns items that do not contain the search term provided.\n For example, a search for `marketing AND NOT BoxWorks` returns a result\n that has only `marketing` within its text. Results containing\n `BoxWorks` are omitted.\n\nPlease note that we do not support lower case (that is,\n`and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`)\noperators.\n\nThis field is required unless the `mdfilters` parameter is defined.", "in": "query", "required": false, "type": "string" }, { "name": "scope", "description": "Limits the search results to either the files that the user has\naccess to, or to files available to the entire enterprise.\n\nThe scope defaults to `user_content`, which limits the search\nresults to content that is available to the currently authenticated\nuser.\n\nThe `enterprise_content` can be requested by an admin through our\nsupport channels. Once this scope has been enabled for a user, it\nwill allow that use to query for content across the entire\nenterprise and not only the content that they have access to.", "in": "query", "required": false, "type": "string", "enum": [ "user_content", "enterprise_content" ], "default": "user_content" }, { "name": "file_extensions", "description": "Limits the search results to any files that match any of the provided\nfile extensions. This list is a comma-separated list of file extensions\nwithout the dots.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "created_at_range", "description": "Limits the search results to any items created within\na given date range.\n\nDate ranges are defined as comma separated RFC3339\ntimestamps.\n\nIf the the start date is omitted (`,2014-05-17T13:35:01-07:00`)\nanything created before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00,`) the\ncurrent date will be used as the end date instead.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "updated_at_range", "description": "Limits the search results to any items updated within\na given date range.\n\nDate ranges are defined as comma separated RFC3339\ntimestamps.\n\nIf the start date is omitted (`,2014-05-17T13:35:01-07:00`)\nanything updated before the end date will be returned.\n\nIf the end date is omitted (`2014-05-15T13:35:01-07:00,`) the\ncurrent date will be used as the end date instead.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "size_range", "description": "Limits the search results to any items with a size within\na given file size range. This applied to files and folders.\n\nSize ranges are defined as comma separated list of a lower\nand upper byte size limit (inclusive).\n\nThe upper and lower bound can be omitted to create open ranges.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "owner_user_ids", "description": "Limits the search results to any items that are owned\nby the given list of owners, defined as a list of comma separated\nuser IDs.\n\nPlease note that the items still need to be owned or shared with\nthe currently authenticated user for them to show up in the search\nresults. If the user does not have access to any files owned by any of\nthe users an empty result set will be returned.\n\nTo search across an entire enterprise, we recommend using the\n`enterprise_content` scope parameter which can be requested with our\nsupport team.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "ancestor_folder_ids", "description": "Limits the search results to items within the given\nlist of folders, defined as a comma separated lists\nof folder IDs.\n\nSearch results will also include items within any subfolders\nof those ancestor folders.\n\nPlease note that the folders still need to be owned or shared with\nthe currently authenticated user. If the folder is not accessible by this\nuser, or it does not exist, a `HTTP 404` error code will be returned\ninstead.\n\nTo search across an entire enterprise, we recommend using the\n`enterprise_content` scope parameter which can be requested with our\nsupport team.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "content_types", "description": "Limits the search results to any items that match the search query\nfor a specific part of the file, for example the file description.\n\nContent types are defined as a comma separated lists\nof Box recognized content types. The allowed content types are as follows.\n\n* `name` - The name of the item, as defined by its `name` field.\n* `description` - The description of the item, as defined by its\n `description` field.\n* `file_content` - The actual content of the file.\n* `comments` - The content of any of the comments on a file or\n folder.\n* `tag` - Any tags that are applied to an item, as defined by its\n `tag` field.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "type", "description": "Limits the search results to any items of this type. This\nparameter only takes one value. By default the API returns\nitems that match any of these types.\n\n* `file` - Limits the search results to files\n* `folder` - Limits the search results to folders\n* `web_link` - Limits the search results to web links, also known\n as bookmarks", "in": "query", "required": false, "type": "string", "enum": [ "file", "folder", "web_link" ] }, { "name": "trash_content", "description": "Determines if the search should look in the trash for items.\n\nBy default, this API only returns search results for items\nnot currently in the trash (`non_trashed_only`).\n\n* `trashed_only` - Only searches for items currently in the trash\n* `non_trashed_only` - Only searches for items currently not in\n the trash", "in": "query", "required": false, "type": "string", "default": "non_trashed_only", "enum": [ "non_trashed_only", "trashed_only" ] }, { "name": "mdfilters", "description": "A list of metadata templates to filter the search results by.\n\nRequired unless `query` parameter is defined.", "in": "query", "x-example": [ { "scope": "enterprise", "templateKey": "contract", "filters": { "category": "online", "contractValue": 1000000 } } ], "required": false, "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string" } }, { "name": "sort", "description": "Defines the order in which search results are returned. This API\ndefaults to returning items by relevance unless this parameter is\nexplicitly specified.\n\n* `relevance` (default) returns the results sorted by relevance to the\nquery search term. The relevance is based on the occurrence of the search\nterm in the items name, description, content, and additional properties.\n* `modified_at` returns the results ordered in descending order by date\nat which the item was last modified.", "in": "query", "required": false, "type": "string", "default": "relevance", "enum": [ "modified_at", "relevance" ] }, { "name": "direction", "description": "Defines the direction in which search results are ordered. This API\ndefaults to returning items in descending (`DESC`) order unless this\nparameter is explicitly specified.\n\nWhen results are sorted by `relevance` the ordering is locked to returning\nitems in descending order of relevance, and this parameter is ignored.", "in": "query", "required": false, "type": "string", "default": "DESC", "enum": [ "DESC", "ASC" ] }, { "name": "limit", "description": "Defines the maximum number of items to return as part of a page of\nresults.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 30, "maximum": 200 }, { "name": "include_recent_shared_links", "description": "Defines whether the search results should include any items\nthat the user recently accessed through a shared link.\n\nPlease note that when this parameter has been set to true,\nthe format of the response of this API changes to return\na list of [Search Results with\nShared Links](r://search_results_with_shared_links)", "in": "query", "required": false, "type": "boolean", "default": false }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns a collection of search results. If there are no matching\nsearch results, the `entries` array will be empty.", "schema": { "$ref": "#/definitions/SearchResults" } }, "400": { "description": "Returns an error when the request was not valid. This can have multiple\nreasons and the `context_info` object will provide you with more details.\n\n* `missing_parameter` - Please provide at least the `query` or `mdfilters`\n query parameter in a search.\n* `invalid_parameter` - Any of the fields might not be in the right\n format. This could for example mean that one of the RFC3339 dates is\n incorrect, or a string is provided where an integer is expected.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error when the user does not have the permission to make\nthis API call.\n\n* The developer provided a `scope` of `enterprise_content` but did\n not request this scope to be enabled for the user through our\n support channels.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the user does not have access to an item\nmentioned in the request.\n\n* The developer provided a folder ID in `ancestor_folder_ids`\n that either does not exist or the user does not have access to.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/tasks": { "post": { "operationId": "post_tasks", "tags": [ "Tasks" ], "summary": "Create task", "description": "Creates a single task on a file. This task is not assigned to any user and\nwill need to be assigned separately.", "responses": { "201": { "description": "Returns the newly created task.", "schema": { "$ref": "#/definitions/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\nbe because the `action` or `completion_rule` are not one of the allowed\nvalues.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error when the user does not have the permission to create a\ntask on the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "object", "description": "The file to attach the task to.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the file" }, "type": { "type": "string", "description": "`file`", "enum": [ "file" ] } } }, "action": { "type": "string", "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\nrejected\n* `complete` defines a general task which can be completed", "default": "review", "enum": [ "review", "complete" ] }, "message": { "type": "string", "default": "", "description": "An optional message to include with the task." }, "due_at": { "type": "string", "format": "date-time", "description": "Defines when the task is due. Defaults to `null` if not\nprovided." }, "completion_rule": { "type": "string", "description": "Defines which assignees need to complete this task before the task\nis considered completed.\n\n* `all_assignees` (default) requires all assignees to review or\napprove the the task in order for it to be considered completed.\n* `any_assignee` accepts any one assignee to review or\napprove the the task in order for it to be considered completed.", "default": "all_assignees", "enum": [ "all_assignees", "any_assignee" ] } } } } ] } }, "/tasks/{task_id}": { "get": { "operationId": "get_tasks_id", "summary": "Get task", "tags": [ "Tasks" ], "description": "Retrieves information about a specific task.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a task object.", "schema": { "$ref": "#/definitions/Task" } }, "404": { "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_tasks_id", "tags": [ "Tasks" ], "summary": "Update task", "description": "Updates a task. This can be used to update a task's configuration, or to\nupdate its completion state.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "action": { "type": "string", "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\nrejected\n* `complete` defines a general task which can be completed", "enum": [ "review", "complete" ] }, "message": { "type": "string", "description": "The message included with the task." }, "due_at": { "type": "string", "format": "date-time", "description": "When the task is due at." }, "completion_rule": { "type": "string", "description": "Defines which assignees need to complete this task before the task\nis considered completed.\n\n* `all_assignees` (default) requires all assignees to review or\napprove the the task in order for it to be considered completed.\n* `any_assignee` accepts any one assignee to review or\napprove the the task in order for it to be considered completed.", "enum": [ "all_assignees", "any_assignee" ] } } } } ], "responses": { "200": { "description": "Returns the updated task object", "schema": { "$ref": "#/definitions/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\nbe because the `action` or `completion_rule` are not one of the allowed\nvalues.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error when the user does not have the permission to update a\ntask on the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_tasks_id", "tags": [ "Tasks" ], "summary": "Remove task", "description": "Removes a task from a file.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "in": "path", "required": true, "type": "string" } ], "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\nhave access to the file the task is assigned to.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/tasks/{task_id}/assignments": { "get": { "operationId": "get_tasks_id_assignments", "summary": "List task assignments", "tags": [ "Task assignments" ], "description": "Lists all of the assignments for a given task.", "parameters": [ { "name": "task_id", "description": "The ID of the task.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a collection of task assignment defining what task on\na file has been assigned to which users and by who.", "schema": { "$ref": "#/definitions/TaskAssignments" } }, "404": { "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error if the task assignment ID was omitted in\nthe request.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/task_assignments": { "post": { "operationId": "post_task_assignments", "summary": "Assign task", "tags": [ "Task assignments" ], "description": "Assigns a task to a user.\n\nA task can be assigned to more than one user by creating multiple\nassignments.", "responses": { "201": { "description": "Returns a new task assignment object.", "schema": { "$ref": "#/definitions/TaskAssignment" } }, "403": { "description": "Returns an error if a change to a completed task is attempted", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the task could not be found or the user does not\nhave access to the file the task is assigned to.", "schema": { "$ref": "#/definitions/ClientError" } }, "500": { "description": "Returns an error if any of the IDs for this request were not valid, or if\nthe targeted user does not have access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "task", "assign_to" ], "properties": { "task": { "type": "object", "description": "The task to assign to a user.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the task" }, "type": { "type": "string", "description": "The type of the item to assign.", "enum": [ "task" ] } } }, "assign_to": { "type": "object", "description": "The user to assign the task to.", "properties": { "id": { "type": "string", "description": "The ID of the user to assign to the\ntask.\n\nTo specify a user by their email\naddress use the `login` parameter." }, "login": { "type": "string", "description": "The email address of the user to assign to the task.\nTo specify a user by their user ID please use the `id` parameter." } } } } } } ] } }, "/task_assignments/{task_assignment_id}": { "get": { "operationId": "get_task_assignments_id", "summary": "Get task assignment", "tags": [ "Task assignments" ], "description": "Retrieves information about a task assignment.", "parameters": [ { "name": "task_assignment_id", "description": "The ID of the task assignment.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a task assignment, specifying who the task has been assigned to\nand by whom.", "schema": { "$ref": "#/definitions/TaskAssignment" } }, "404": { "description": "Returns an error when the task assignment could not be found or the user\ndoes not have access to the file the task is assigned to.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_task_assignments_id", "summary": "Update task assignment", "tags": [ "Task assignments" ], "description": "Updates a task assignment. This endpoint can be\nused to update the state of a task assigned to a user.", "parameters": [ { "name": "task_assignment_id", "description": "The ID of the task assignment.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "An optional message by the assignee that can be added to the task." }, "resolution_state": { "type": "string", "description": "The state of the task assigned to the user.\n\n* For a task with an `action` value of `complete` this can be\n`incomplete` or `completed`.\n* For a task with an `action` of `review` this can be\n`incomplete`, `approved`, or `rejected`.", "enum": [ "completed", "incomplete", "approved", "rejected" ] } } } } ], "responses": { "200": { "description": "Returns the updated task assignment object.", "schema": { "$ref": "#/definitions/TaskAssignment" } }, "400": { "description": "Returns an error if a resolution state is incompatible with the action\ntype of the task.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the task assignment could not be found or the user\ndoes not have access to the file the task is assigned to.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_task_assignments_id", "summary": "Unassign task", "tags": [ "Task assignments" ], "description": "Deletes a specific task assignment.", "parameters": [ { "name": "task_assignment_id", "description": "The ID of the task assignment.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the task\nassignment was successfully deleted." }, "404": { "description": "Returns an error if the task assignment for the given ID does not exist\nor is inaccessible to your account.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/shared_items": { "get": { "operationId": "get_shared_items", "summary": "Find file for shared link", "tags": [ "Shared links (Files)" ], "description": "Return the file represented by a shared link.\n\nA shared file can be represented by a shared link,\nwhich can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a\nshared file when only given a shared link.", "parameters": [ { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "boxapi", "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", "in": "header", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a full file resource if the shared link is valid and\nthe user has access to it.", "schema": { "$ref": "#/definitions/File" } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}#get_shared_link": { "get": { "operationId": "get_files_id#get_shared_link", "summary": "Get shared link for file", "tags": [ "Shared links (Files)" ], "description": "Gets the information for a shared link on a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the base representation of a file with the\nadditional shared link information.", "schema": { "$ref": "#/definitions/File" }, "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 } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}#add_shared_link": { "put": { "operationId": "put_files_id#add_shared_link", "summary": "Add shared link to file", "tags": [ "Shared links (Files)" ], "description": "Adds a shared link to a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to create on the file.\n\nUse an empty object (`{}`) to use the default settings for shared\nlinks.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the file (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ] }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`." }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks." }, "unshared_at": { "type": "string", "format": "date-time", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } } } } } ], "responses": { "200": { "description": "Returns the base representation of a file with a new shared\nlink attached.", "schema": { "$ref": "#/definitions/File" }, "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 } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}#update_shared_link": { "put": { "operationId": "put_files_id#update_shared_link", "summary": "Update shared link on file", "tags": [ "Shared links (Files)" ], "description": "Updates a shared link on a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ] }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`." }, "vanity_name": { "type": "string", "description": "Defines a custom vanity name to use in the shared link URL,\nfor example `https://app.box.com/v/my-shared-link`.\n\nCustom URLs should not be used when sharing sensitive content\nas vanity URLs are a lot easier to guess than regular shared\nlinks." }, "unshared_at": { "type": "string", "format": "date-time", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "description": "If the shared link allows for downloading of files.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } } } } } ], "responses": { "200": { "description": "Returns a basic representation of the file, with the updated shared\nlink attached.", "schema": { "$ref": "#/definitions/File" }, "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 } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/files/{file_id}#remove_shared_link": { "put": { "operationId": "put_files_id#remove_shared_link", "summary": "Remove shared link from file", "tags": [ "Shared links (Files)" ], "description": "Removes a shared link from a file.", "parameters": [ { "name": "file_id", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link\nis removed from the file.", "type": "object" } } } } ], "responses": { "200": { "description": "Returns a basic representation of a file, with the shared link removed.", "schema": { "$ref": "#/definitions/File" }, "examples": { "default": { "value": { "id": "12345", "type": "file", "etag": "1", "shared_link": null } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the file is not found, or the user does not\nhave access to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `file_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the file. This indicates that the file\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/shared_items#folders": { "get": { "operationId": "get_shared_items#folders", "summary": "Find folder for shared link", "tags": [ "Shared links (Folders)" ], "description": "Return the folder represented by a shared link.\n\nA shared folder can be represented by a shared link,\nwhich can originate within the current enterprise or within another.\n\nThis endpoint allows an application to retrieve information about a\nshared folder when only given a shared link.", "parameters": [ { "name": "if-none-match", "description": "Ensures an item is only returned if it has changed.\n\nPass in the item's last observed `etag` value\ninto this header and the endpoint will fail\nwith a `304 Not Modified` if the item has not\nchanged since.", "in": "header", "required": false, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "boxapi", "description": "A header containing the shared link and optional password for the\nshared link.\n\nThe format for this header is as follows.\n\n`shared_link=[link]&shared_link_password=[password]`", "in": "header", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a full folder resource if the shared link is valid and\nthe user has access to it.", "schema": { "$ref": "#/definitions/Folder" } }, "304": { "description": "Returns an empty response when the `If-None-Match` header matches\nthe current `etag` value of the folder. This indicates that the folder\nhas not changed since it was last requested." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}#get_shared_link": { "get": { "operationId": "get_folders_id#get_shared_link", "summary": "Get shared link for folder", "tags": [ "Shared links (Folders)" ], "description": "Gets the information for a shared link on a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the base representation of a folder with the\nadditional shared link information.", "schema": { "$ref": "#/definitions/Folder" }, "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 } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}#add_shared_link": { "put": { "operationId": "put_folders_id#add_shared_link", "summary": "Add shared link to folder", "tags": [ "Shared links (Folders)" ], "description": "Adds a shared link to a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" }, { "name": "body", "in": "body", "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\nlinks.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ] }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`." }, "unshared_at": { "type": "string", "format": "date-time", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "description": "If the shared link allows for downloading of folders.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } } } } } ], "responses": { "200": { "description": "Returns the base representation of a folder with a new shared\nlink attached.", "schema": { "$ref": "#/definitions/Folder" }, "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 } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}#update_shared_link": { "put": { "operationId": "put_folders_id#update_shared_link", "summary": "Update shared link on folder", "tags": [ "Shared links (Folders)" ], "description": "Updates a shared link on a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "shared_link": { "description": "The settings for the shared link to update.", "type": "object", "properties": { "access": { "type": "string", "description": "The level of access for the shared link. This can be\nrestricted to anyone with the link (`open`), only people\nwithin the company (`company`) and only those who\nhave been invited to the folder (`collaborators`).\n\nIf not set, this field defaults to the access level specified\nby the enterprise admin. To create a shared link with this\ndefault setting pass the `shared_link` object with\nno `access` field, for example `{ \"shared_link\": {} }`.\n\nThe `company` access level is only available to paid\naccounts.", "enum": [ "open", "company", "collaborators" ] }, "password": { "type": "string", "description": "The password required to access the shared link. Set the\npassword to `null` to remove it.\n\nA password can only be set when `access` is set to `open`." }, "unshared_at": { "type": "string", "format": "date-time", "description": "The timestamp at which this shared link will\nexpire. This field can only be set by\nusers with paid accounts. The value must be greater than the\ncurrent date and time." }, "permissions": { "type": "object", "properties": { "can_download": { "type": "boolean", "description": "If the shared link allows for downloading of folders.\nThis can only be set when `access` is set to\n`open` or `company`." } } } } } } } } ], "responses": { "200": { "description": "Returns a basic representation of the folder, with the updated shared\nlink attached.", "schema": { "$ref": "#/definitions/Folder" }, "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 } } } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/folders/{folder_id}#remove_shared_link": { "put": { "operationId": "put_folders_id#remove_shared_link", "summary": "Remove shared link from folder", "tags": [ "Shared links (Folders)" ], "description": "Removes a shared link from a folder.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "Explicitly request the `shared_link` fields\nto be returned for this item.", "in": "query", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "shared_link": { "description": "By setting this value to `null`, the shared link\nis removed from the folder.", "type": "object" } } } } ], "responses": { "200": { "description": "Returns a basic representation of a folder, with the shared link removed.", "schema": { "$ref": "#/definitions/Folder" }, "examples": { "default": { "value": { "id": "12345", "type": "folder", "etag": "1", "shared_link": null } } } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned if the user does not have all the permissions to complete the\nupdate.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "405": { "description": "Returned if the `folder_id` is not in a recognized format.", "schema": { "$ref": "#/definitions/ClientError" } }, "412": { "description": "Returns an error when the `If-Match` header does not match\nthe current `etag` value of the folder. This indicates that the folder\nhas changed since it was last requested.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/web_links": { "post": { "operationId": "post_web_links", "summary": "Create web link", "tags": [ "Web links" ], "description": "Creates a web link object within a folder.", "responses": { "200": { "description": "Returns the newly created web link object.", "schema": { "$ref": "#/definitions/WebLink" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "parent", "url" ], "properties": { "url": { "type": "string", "description": "The URL that this web link links to. Must start with\n`\"http://\"` or `\"https://\"`." }, "parent": { "type": "object", "description": "The parent folder to create the web link within.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of parent folder" } } }, "name": { "type": "string", "description": "Name of the web link. Defaults to the URL if not set." }, "description": { "type": "string", "description": "Description of the web link." } } } } ] } }, "/web_links/{web_link_id}": { "get": { "operationId": "get_web_links_id", "summary": "Get web link", "tags": [ "Web links" ], "description": "Retrieve information about a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "in": "path", "required": true, "type": "string" }, { "name": "boxapi", "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\nexplicitly shared with a user.\n\nUse the format `shared_link=[link]` or if a password is required then\nuse `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\nor folders nested within the item.", "in": "header", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the web link object.", "schema": { "$ref": "#/definitions/WebLink" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_web_links_id", "summary": "Restore web link", "tags": [ "Trashed web links" ], "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\nthe original folder has been deleted.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "description": "An optional new name for the web link.", "type": "string" }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item" } } }, { "description": "Specifies an optional ID of a folder to restore the web link\nto when the original folder no longer exists.\n\nPlease be aware that this ID will only be used if the original\nfolder no longer exists. Use this ID to provide a fallback\nlocation to restore the web link to if the original location\nhas been deleted." } ] } } } } ], "responses": { "201": { "description": "Returns a web link object when it has been restored.", "schema": { "$ref": "#/definitions/WebLink" } }, "403": { "description": "Returns an error if the user does not have access to the folder\nthe web link is being restored to, or the user does not have permission\nto restore web link from the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the web link is not in the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if there is an web link with the same name\nin the folder the web link is being restored to.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_web_links_id", "summary": "Update web link", "tags": [ "Web links" ], "description": "Updates a web link object.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "The new URL that the web link links to. Must start with\n`\"http://\"` or `\"https://\"`." }, "parent": { "allOf": [ { "type": "object", "description": "The parent for this item", "properties": { "id": { "type": "string", "description": "The ID of parent item" } } }, { "description": "The new parent folder to put the web link in.\nUse this to move the web link to a different folder." } ] }, "name": { "type": "string", "description": "A new name for the web link. Defaults to the URL if not set." }, "description": { "type": "string", "description": "A new description of the web link." } } } } ], "responses": { "200": { "description": "Returns the updated web link object.", "schema": { "$ref": "#/definitions/WebLink" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_web_links_id", "summary": "Remove web link", "tags": [ "Web links" ], "description": "Deletes a web link.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "An empty response will be returned when the web link\nwas successfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/web_links/{web_link_id}/trash": { "get": { "operationId": "get_web_links_id_trash", "summary": "Get trashed web link", "tags": [ "Trashed web links" ], "description": "Retrieves a web link that has been moved to the trash.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns the web link that was trashed,\nincluding information about when the it\nwas moved to the trash.", "schema": { "$ref": "#/definitions/Folder" } }, "404": { "description": "Returns an error if the web link is not in the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_web_links_id_trash", "summary": "Permanently remove web link", "tags": [ "Trashed web links" ], "description": "Permanently deletes a web link that is in the trash.\nThis action cannot be undone.", "parameters": [ { "name": "web_link_id", "description": "The ID of the web link.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the web link was\npermanently deleted." }, "404": { "description": "Returns an error if the web link is not in the trash.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users": { "get": { "operationId": "get_users", "summary": "List enterprise users", "tags": [ "Users" ], "description": "Returns a list of all users for the Enterprise along with their `user_id`,\n`public_name`, and `login`.\n\nThe application and the authenticated user need to\nhave the permission to look up users in the entire\nenterprise.", "parameters": [ { "name": "filter_term", "description": "Limits the results to only users who's `name` or\n`login` start with the search term.\n\nFor externally managed users, the search term needs\nto completely match the in order to find the user, and\nit will only return one user at a time.", "in": "query", "required": false, "type": "string" }, { "name": "user_type", "description": "Limits the results to the kind of user specified.\n\n* `all` returns every kind of user for whom the\n `login` or `name` partially matches the\n `filter_term`. It will only return an external user\n if the login matches the `filter_term` completely,\n and in that case it will only return that user.\n* `managed` returns all managed and app users for whom\n the `login` or `name` partially matches the\n `filter_term`.\n* `external` returns all external users for whom the\n `login` matches the `filter_term` exactly.", "in": "query", "required": false, "type": "string", "enum": [ "all", "managed", "external" ] }, { "name": "external_app_user_id", "in": "query", "required": false, "description": "Limits the results to app users with the given\n`external_app_user_id` value.\n\nWhen creating an app user, an\n`external_app_user_id` value can be set. This value can\nthen be used in this endpoint to find any users that\nmatch that `external_app_user_id` value.", "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "usemarker", "description": "Specifies whether to use marker-based pagination instead of\noffset-based pagination. Only one pagination method can\nbe used at a time.\n\nBy setting this value to true, the API will return a `marker` field\nthat can be passed as a parameter to this endpoint to get the next\npage of the response.", "in": "query", "required": false, "type": "boolean" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns all of the users in the enterprise.", "schema": { "$ref": "#/definitions/Users" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_users", "summary": "Create user", "tags": [ "Users" ], "description": "Creates a new managed user in an enterprise. This endpoint\nis only available to users and applications with the right\nadmin permissions.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the user", "maxLength": 50 }, "login": { "type": "string", "description": "The email address the user uses to log in\n\nRequired, unless `is_platform_access_only`\nis set to `true`." }, "is_platform_access_only": { "type": "boolean", "description": "Specifies that the user is an app user." }, "role": { "type": "string", "enum": [ "coadmin", "user" ], "description": "The user’s enterprise role" }, "language": { "type": "string", "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format." }, "is_sync_enabled": { "type": "boolean", "description": "Whether the user can use Box Sync" }, "job_title": { "type": "string", "description": "The user’s job title", "maxLength": 100 }, "phone": { "type": "string", "description": "The user’s phone number", "maxLength": 100 }, "address": { "type": "string", "description": "The user’s address", "maxLength": 255 }, "space_amount": { "type": "integer", "format": "int64", "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage." }, "tracking_codes": { "type": "array", "description": "Tracking codes allow an admin to generate reports from the\nadmin console and assign an attribute to a specific group\nof users. This setting must be enabled for an enterprise before it\ncan be used.", "items": { "type": "string" } }, "can_see_managed_users": { "type": "boolean", "description": "Whether the user can see other enterprise users in their\ncontact list" }, "timezone": { "type": "string", "format": "timezone", "description": "The user's timezone" }, "is_external_collab_restricted": { "type": "boolean", "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise" }, "is_exempt_from_device_limits": { "type": "boolean", "description": "Whether to exempt the user from enterprise device limits" }, "is_exempt_from_login_verification": { "type": "boolean", "description": "Whether the user must use two-factor authentication" }, "status": { "type": "string", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ], "description": "The user's account status" }, "external_app_user_id": { "type": "string", "description": "An external identifier for an app user, which can be used to look\nup the user. This can be used to tie user IDs from external\nidentity providers to Box users." } } } } ], "responses": { "201": { "description": "Returns a user object for the newly created user.", "schema": { "$ref": "#/definitions/User" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users/me": { "get": { "operationId": "get_users_me", "summary": "Get current user", "tags": [ "Users" ], "description": "Retrieves information about the user who is currently authenticated.\n\nIn the case of a client-side authenticated OAuth 2.0 application\nthis will be the user who authorized the app.\n\nIn the case of a JWT, server-side authenticated application\nthis will be the service account that belongs to the application\nby default.\n\nUse the `As-User` header to change who this API call is made on behalf of.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns a single user object.", "schema": { "$ref": "#/definitions/User" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users/{user_id}": { "get": { "operationId": "get_users_id", "summary": "Get user", "tags": [ "Users" ], "description": "Retrieves information about a user in the enterprise.\n\nThe application and the authenticated user need to\nhave the permission to look up users in the entire\nenterprise.\n\nThis endpoint also returns a limited set of information\nfor external users who are collaborated on content\nowned by the enterprise for authenticated users with the\nright scopes. In this case, disallowed fields will return\nnull instead.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns a single user object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields using the [fields](#get-users-id--request--fields)\nparameter.", "schema": { "$ref": "#/definitions/User" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_users_id", "summary": "Update user", "tags": [ "Users" ], "description": "Updates a managed user in an enterprise. This endpoint\nis only available to users and applications with the right\nadmin permissions.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "enterprise": { "type": "string", "description": "Set this to `null` to roll the user out of the enterprise\nand make them a free user" }, "notify": { "type": "boolean", "description": "Whether the user should receive an email when they\nare rolled out of an enterprise" }, "name": { "type": "string", "description": "The name of the user", "maxLength": 50 }, "login": { "type": "string", "description": "The email address the user uses to log in" }, "role": { "type": "string", "enum": [ "coadmin", "user" ], "description": "The user’s enterprise role" }, "language": { "type": "string", "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format." }, "is_sync_enabled": { "type": "boolean", "description": "Whether the user can use Box Sync" }, "job_title": { "type": "string", "description": "The user’s job title", "maxLength": 100 }, "phone": { "type": "string", "description": "The user’s phone number", "maxLength": 100 }, "address": { "type": "string", "description": "The user’s address", "maxLength": 255 }, "tracking_codes": { "type": "array", "description": "Tracking codes allow an admin to generate reports from the\nadmin console and assign an attribute to a specific group\nof users. This setting must be enabled for an enterprise before it\ncan be used.", "items": { "type": "string" } }, "can_see_managed_users": { "type": "boolean", "description": "Whether the user can see other enterprise users in their\ncontact list" }, "timezone": { "type": "string", "format": "timezone", "description": "The user's timezone" }, "is_external_collab_restricted": { "type": "boolean", "description": "Whether the user is allowed to collaborate with users outside\ntheir enterprise" }, "is_exempt_from_device_limits": { "type": "boolean", "description": "Whether to exempt the user from enterprise device limits" }, "is_exempt_from_login_verification": { "type": "boolean", "description": "Whether the user must use two-factor authentication" }, "is_password_reset_required": { "type": "boolean", "description": "Whether the user is required to reset their password" }, "status": { "type": "string", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ], "description": "The user's account status" }, "space_amount": { "type": "integer", "format": "int64", "description": "The user’s total available space in bytes. Set this to `-1` to\nindicate unlimited storage." }, "notification_email": { "type": "object", "description": "An alternate notification email address to which email\nnotifications are sent. When it's confirmed, this will be\nthe email address to which notifications are sent instead of\nto the primary email address.\n\nSet this value to `null` to remove the notification email.", "properties": { "email": { "type": "string", "description": "The email address to send the notifications to." } } } } } } ], "responses": { "200": { "description": "Returns the updated user object.", "schema": { "$ref": "#/definitions/User" } }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `invalid_parameter` when a parameter is formatted incorrectly,\n for example when the `notification_email` has an incorrectly formatted\n email address.", "schema": { "$ref": "#/definitions/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\n the right permissions, for example when updating the notification email\n is turned off for the enterprise.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_users_id", "summary": "Delete user", "tags": [ "Users" ], "description": "Deletes a user. By default this will fail if the user\nstill owns any content. Move their owned content first\nbefore proceeding, or use the `force` field to delete\nthe user and their files.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" }, { "name": "notify", "in": "query", "description": "Whether the user will receive email notification of\nthe deletion", "type": "boolean" }, { "name": "force", "in": "query", "description": "Whether the user should be deleted even if this user\nstill own files", "type": "boolean" } ], "responses": { "204": { "description": "Removes the user and returns an empty response." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users/{user_id}/avatar": { "get": { "operationId": "get_users_id_avatar", "summary": "Get user avatar", "tags": [ "User avatars" ], "description": "Retrieves an image of a the user's avatar.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "When an avatar can be found for the user the\nimage data will be returned in the body of the\nresponse.", "schema": { "type": "string", "format": "binary", "description": "The avatar" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users/{user_id}/folders/0": { "put": { "operationId": "put_users_id_folders_0", "summary": "Transfer owned folders", "tags": [ "Transfer folders" ], "description": "Move all of the items (files, folders and workflows) owned by a user into\nanother user's account\n\nOnly the root folder (`0`) can be transferred.\n\nFolders can only be moved across users by users with administrative\npermissions.\n\nAll existing shared links and folder-level collaborations are transferred\nduring the operation. Please note that while collaborations at the individual\nfile-level are transferred during the operation, the collaborations are\ndeleted when the original user is deleted.\n\nThis call will be performed synchronously which might lead to a slow response\nwhen the source user has a large number of items in all of its folders.\n\nIf the destination path has a metadata cascade policy attached to any of\nthe parent folders, a metadata cascade operation will be kicked off\nasynchronously.\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\nFolders`, 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\nall files and folders stored in Box\" scope enabled.\n\nPlease make sure the destination user has access to `Relay` or `Relay Lite`,\nand has access to the files and folders involved in the workflows being\ntransferred.\n\nAdmins will receive an email when the operation is completed.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "notify", "description": "Determines if users should receive email notification\nfor the action performed.", "in": "query", "required": false, "type": "boolean" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "owned_by" ], "properties": { "owned_by": { "type": "object", "description": "The user who the folder will be transferred to", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the user who the folder will be\ntransferred to" } } } } } } ], "responses": { "200": { "description": "Returns the information for the newly created\ndestination folder.", "schema": { "$ref": "#/definitions/Folder" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users/{user_id}/email_aliases": { "get": { "operationId": "get_users_id_email_aliases", "summary": "List user's email aliases", "tags": [ "Email aliases" ], "description": "Retrieves all email aliases for a user. The collection\ndoes not include the primary login for the user.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a collection of email aliases.", "schema": { "$ref": "#/definitions/EmailAliases" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_users_id_email_aliases", "summary": "Create email alias", "tags": [ "Email aliases" ], "description": "Adds a new email alias to a user account..", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "The email address to add to the account as an alias." } } } } ], "responses": { "201": { "description": "Returns the newly created email alias object.", "schema": { "$ref": "#/definitions/EmailAlias" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users/{user_id}/email_aliases/{email_alias_id}": { "delete": { "operationId": "delete_users_id_email_aliases_id", "summary": "Remove email alias", "tags": [ "Email aliases" ], "description": "Removes an email alias from a user.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" }, { "name": "email_alias_id", "description": "The ID of the email alias.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Removes the alias and returns an empty response." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/users/{user_id}/memberships": { "get": { "operationId": "get_users_id_memberships", "summary": "List user's groups", "tags": [ "Group memberships" ], "description": "Retrieves all the groups for a user. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "user_id", "description": "The ID of the user.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns a collection of membership objects. If there are no\nmemberships, an empty collection will be returned.", "schema": { "$ref": "#/definitions/GroupMemberships" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/invites": { "post": { "operationId": "post_invites", "summary": "Create user ******", "tags": [ "Invites" ], "description": "Invites an existing external user to join an enterprise.\n\nThe existing user can not be part of another enterprise and\nmust already have a Box account. Once invited, the user will receive an\nemail and are prompted to accept the invitation within the\nBox web application.\n\nThis method requires the \"Manage An Enterprise\" scope enabled for\nthe application, which can be enabled within the developer console.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "enterprise", "actionable_by" ], "properties": { "enterprise": { "type": "object", "description": "The enterprise to ****** the user to", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the enterprise" } } }, "actionable_by": { "type": "object", "description": "The user to ******", "required": [ "id" ], "properties": { "login": { "type": "string", "description": "The login of the invited user" } } } } } } ], "responses": { "200": { "description": "Returns a new ****** object.", "schema": { "$ref": "#/definitions/******" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/invites/{invite_id}": { "get": { "operationId": "get_invites_id", "summary": "Get user ****** status", "tags": [ "Invites" ], "description": "Returns the status of a user ******.", "parameters": [ { "name": "invite_id", "description": "The ID of an ******.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns an ****** object", "schema": { "$ref": "#/definitions/******" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/groups": { "get": { "operationId": "get_groups", "summary": "List groups for enterprise", "tags": [ "Groups" ], "description": "Retrieves all of the groups for a given enterprise. The user\nmust have admin permissions to inspect enterprise's groups.", "parameters": [ { "name": "filter_term", "description": "Limits the results to only groups whose `name` starts\nwith the search term.", "in": "query", "required": false, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns a collection of group objects. If there are no groups, an\nempty collection will be returned.", "schema": { "$ref": "#/definitions/Groups" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_groups", "summary": "Create group", "tags": [ "Groups" ], "description": "Creates a new group of users in an enterprise. Only users with admin\npermissions can create new groups.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the new group to be created. This name must be unique\nwithin the enterprise." }, "provenance": { "type": "string", "description": "Keeps track of which external source this group is\ncoming, for example `Active Directory`, or `Okta`.\n\nSetting this will also prevent Box admins from editing\nthe group name and its members directly via the Box\nweb application.\n\nThis is desirable for one-way syncing of groups.", "maxLength": 255 }, "external_sync_identifier": { "type": "string", "description": "An arbitrary identifier that can be used by\nexternal group sync tools to link this Box Group to\nan external group.\n\nExample values of this field\ncould be an **Active Directory Object ID** or a **Google\nGroup ID**.\n\nWe recommend you use of this field in\norder to avoid issues when group names are updated in\neither Box or external systems." }, "description": { "type": "string", "description": "A human readable description of the group.", "maxLength": 255 }, "invitability_level": { "type": "string", "description": "Specifies who can ****** the group to collaborate\non folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins,\nand the group's admin can ****** the group.\n\nWhen set to `admins_and_members` all the admins listed\nabove and group members can ****** the group.\n\nWhen set to `all_managed_users` all managed users in the\nenterprise can ****** the group.", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "member_viewability_level": { "type": "string", "description": "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n enterprise", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] } } } } ], "responses": { "201": { "description": "Returns the new group object.", "schema": { "$ref": "#/definitions/Group" } }, "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\nthe enterprise.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/groups/{group_id}": { "get": { "operationId": "get_groups_id", "summary": "Get group", "tags": [ "Groups" ], "description": "Retrieves information about a group. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns the group object", "schema": { "$ref": "#/definitions/Group" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_groups_id", "summary": "Update group", "tags": [ "Groups" ], "description": "Updates a specific group. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the new group to be created. Must be unique within the\nenterprise." }, "provenance": { "type": "string", "description": "Keeps track of which external source this group is\ncoming, for example `Active Directory`, or `Okta`.\n\nSetting this will also prevent Box admins from editing\nthe group name and its members directly via the Box\nweb application.\n\nThis is desirable for one-way syncing of groups.", "maxLength": 255 }, "external_sync_identifier": { "type": "string", "description": "An arbitrary identifier that can be used by\nexternal group sync tools to link this Box Group to\nan external group.\n\nExample values of this field\ncould be an **Active Directory Object ID** or a **Google\nGroup ID**.\n\nWe recommend you use of this field in\norder to avoid issues when group names are updated in\neither Box or external systems." }, "description": { "type": "string", "description": "A human readable description of the group.", "maxLength": 255 }, "invitability_level": { "type": "string", "description": "Specifies who can ****** the group to collaborate\non folders.\n\nWhen set to `admins_only` the enterprise admin, co-admins,\nand the group's admin can ****** the group.\n\nWhen set to `admins_and_members` all the admins listed\nabove and group members can ****** the group.\n\nWhen set to `all_managed_users` all managed users in the\nenterprise can ****** the group.", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] }, "member_viewability_level": { "type": "string", "description": "Specifies who can see the members of the group.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n enterprise", "enum": [ "admins_only", "admins_and_members", "all_managed_users" ] } } } } ], "responses": { "200": { "description": "Returns the updated group object.", "schema": { "$ref": "#/definitions/Group" } }, "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\nthe enterprise.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_groups_id", "summary": "Remove group", "tags": [ "Groups" ], "description": "Permanently deletes a group. Only users with\nadmin-level permissions will be able to use this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "A blank response is returned if the group was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/groups/{group_id}/memberships": { "get": { "operationId": "get_groups_id_memberships", "summary": "List members of group", "tags": [ "Group memberships" ], "description": "Retrieves all the members for a group. Only members of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns a collection of membership objects. If there are no\nmemberships, an empty collection will be returned.", "schema": { "$ref": "#/definitions/GroupMemberships" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/groups/{group_id}/collaborations": { "get": { "operationId": "get_groups_id_collaborations", "summary": "List group collaborations", "tags": [ "Collaborations (List)" ], "description": "Retrieves all the collaborations for a group. The user\nmust have admin permissions to inspect enterprise's groups.\n\nEach collaboration object has details on which files or\nfolders the group has access to and with what role.", "parameters": [ { "name": "group_id", "description": "The ID of the group.", "in": "path", "required": true, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 } ], "responses": { "200": { "description": "Returns a collection of collaboration objects. If there are no\ncollaborations, an empty collection will be returned.", "schema": { "$ref": "#/definitions/Collaborations" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/group_memberships": { "post": { "operationId": "post_group_memberships", "summary": "Add user to group", "tags": [ "Group memberships" ], "description": "Creates a group membership. Only users with\nadmin-level permissions will be able to use this API.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "user", "group" ], "properties": { "user": { "type": "object", "description": "The user to add to the group.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the user to add to the group" } } }, "group": { "type": "object", "description": "The group to add the user to.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the group to add the user to" } } }, "role": { "type": "string", "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "configurable_permissions": { "type": "object", "description": "Custom configuration for the permissions an admin\nif a group will receive. This option has no effect\non members with a role of `member`.\n\nSetting these permissions overwrites the default\naccess levels of an admin.\n\nSpecifying a value of \"null\" for this object will disable\nall configurable permissions. Specifying permissions will set\nthem accordingly, omitted permissions will be enabled by default.", "additionalProperties": { "type": "boolean", "description": "A key value pair of custom permissions.", "x-box-example-key": "can_run_reports" } } } } } ], "responses": { "201": { "description": "Returns a new group membership object.", "schema": { "$ref": "#/definitions/GroupMembership" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/group_memberships/{group_membership_id}": { "get": { "operationId": "get_group_memberships_id", "summary": "Get group membership", "tags": [ "Group memberships" ], "description": "Retrieves a specific group membership. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_membership_id", "description": "The ID of the group membership.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns the group membership object.", "schema": { "$ref": "#/definitions/GroupMembership" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_group_memberships_id", "summary": "Update group membership", "tags": [ "Group memberships" ], "description": "Updates a user's group membership. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_membership_id", "description": "The ID of the group membership.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "configurable_permissions": { "type": "object", "description": "Custom configuration for the permissions an admin\nif a group will receive. This option has no effect\non members with a role of `member`.\n\nSetting these permissions overwrites the default\naccess levels of an admin.\n\nSpecifying a value of \"null\" for this object will disable\nall configurable permissions. Specifying permissions will set\nthem accordingly, omitted permissions will be enabled by default.", "additionalProperties": { "type": "boolean", "description": "A key value pair of custom permissions.", "x-box-example-key": "can_run_reports" } } } } } ], "responses": { "200": { "description": "Returns a new group membership object.", "schema": { "$ref": "#/definitions/GroupMembership" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_group_memberships_id", "summary": "Remove user from group", "tags": [ "Group memberships" ], "description": "Deletes a specific group membership. Only admins of this\ngroup or users with admin-level permissions will be able to\nuse this API.", "parameters": [ { "name": "group_membership_id", "description": "The ID of the group membership.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "A blank response is returned if the membership was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/webhooks": { "get": { "operationId": "get_webhooks", "summary": "List all webhooks", "tags": [ "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\nowned by the authenticated user. This means that an admin can not see webhooks\ncreated by a service account unless the admin has access to those folders, and\nvice versa.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a list of webhooks.", "schema": { "$ref": "#/definitions/Webhooks" } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_webhooks", "summary": "Create webhook", "tags": [ "Webhooks" ], "description": "Creates a webhook.", "responses": { "201": { "description": "Returns the new webhook object.", "schema": { "$ref": "#/definitions/Webhook" } }, "400": { "description": "Returns an error if the parameters were\nincorrect.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the target item could\nnot be found", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if the a webhook for this\ncombination of target, application, and user\nalready exists.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "target", "triggers", "address" ], "properties": { "target": { "type": "object", "description": "The item that will trigger the webhook", "properties": { "id": { "description": "The ID of the item to trigger a webhook", "type": "string" }, "type": { "description": "The type of item to trigger a webhook", "type": "string", "enum": [ "file", "folder" ] } } }, "address": { "type": "string", "description": "The URL that is notified by this webhook" }, "triggers": { "type": "array", "description": "An array of event names that this webhook is\nto be triggered for", "items": { "title": "Webhook Trigger", "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" ] } } } } } ] } }, "/webhooks/{webhook_id}": { "get": { "operationId": "get_webhooks_id", "tags": [ "Webhooks" ], "summary": "Get webhook", "description": "Retrieves a specific webhook", "parameters": [ { "name": "webhook_id", "description": "The ID of the webhook.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a webhook object", "schema": { "$ref": "#/definitions/Webhook" } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the webhook could not be found", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_webhooks_id", "summary": "Update webhook", "tags": [ "Webhooks" ], "description": "Updates a webhook.", "parameters": [ { "name": "webhook_id", "description": "The ID of the webhook.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "target": { "type": "object", "description": "The item that will trigger the webhook", "properties": { "id": { "description": "The ID of the item to trigger a webhook", "type": "string" }, "type": { "description": "The type of item to trigger a webhook", "type": "string", "enum": [ "file", "folder" ] } } }, "address": { "type": "string", "description": "The URL that is notified by this webhook" }, "triggers": { "type": "array", "description": "An array of event names that this webhook is\nto be triggered for", "items": { "title": "Webhook Trigger", "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" ] } } } } } ], "responses": { "200": { "description": "Returns the new webhook object.", "schema": { "$ref": "#/definitions/Webhook" } }, "400": { "description": "Returns an error if the parameters were\nincorrect.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the target item or webhook\ncould not be found", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if the a webhook for this\ncombination of target, application, and user\nalready exists.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_webhooks_id", "summary": "Remove webhook", "tags": [ "Webhooks" ], "description": "Deletes a webhook.", "parameters": [ { "name": "webhook_id", "description": "The ID of the webhook.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "An empty response will be returned when the webhook\nwas successfully deleted." }, "403": { "description": "Returns an error if the application does not\nhave the permission to manage webhooks.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the webhook could not be found", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/skill_invocations/{skill_id}": { "put": { "operationId": "put_skill_invocations_id", "summary": "Update all Box Skill cards on file", "tags": [ "Skills" ], "description": "An alternative method that can be used to overwrite and update all Box Skill\nmetadata cards on a file.", "parameters": [ { "name": "skill_id", "description": "The ID of the skill to apply this metadata for.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "status", "metadata", "file" ], "properties": { "status": { "type": "string", "description": "Defines the status of this invocation. Set this to `success` when setting Skill cards.", "enum": [ "invoked", "processing", "success", "transient_failure", "permanent_failure" ] }, "metadata": { "type": "object", "description": "The metadata to set for this skill. This is a list of\nBox Skills cards. These cards will overwrite any existing Box\nskill cards on the file.", "properties": { "cards": { "type": "array", "description": "A list of Box Skill cards to apply to this file.", "items": { "$ref": "#/definitions/SkillCard" } } } }, "file": { "type": "object", "description": "The file to assign the cards to.", "properties": { "type": { "type": "string", "description": "`file`", "enum": [ "file" ] }, "id": { "type": "string", "description": "The ID of the file" } } }, "file_version": { "type": "object", "description": "The optional file version to assign the cards to.", "properties": { "type": { "type": "string", "description": "`file_version`", "enum": [ "file_version" ] }, "id": { "type": "string", "description": "The ID of the file version" } } }, "usage": { "type": "object", "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`\nstate, and leave it out in most other situations.", "properties": { "unit": { "type": "string", "description": "`file`" }, "value": { "type": "number", "description": "`1`" } } } } } } ], "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 for\na field that either does not exist, or for which the value or type does\nnot match the expected field type. An example might be an unknown option\nfor an `enum` or `multiSelect` field.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error when the file could not be found or the user does not\nhave access.\n\n* `not_found` - The file could not be found, or the user does not have\naccess to the file.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/events": { "options": { "operationId": "options_events", "summary": "Get events long poll endpoint", "tags": [ "Events" ], "description": "Returns a list of real-time servers that can be used for long-polling updates\nto the [event stream](#get-events).\n\nLong polling is the concept where a HTTP request is kept open until the\nserver sends a response, then repeating the process over and over to receive\nupdated responses.\n\nLong polling the event stream can only be used for user events, not for\nenterprise events.\n\nTo use long polling, first use this endpoint to retrieve a list of long poll\nURLs. 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\n`new_change` will be sent. The response contains no other details as\nit only serves as a prompt to take further action such as sending a\nrequest to the [events endpoint](#get-events) with the last known\n`stream_position`.\n\nAfter the server sends this response it closes the connection. You must now\nrepeat 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\nreceive a response with the value `reconnect`. When you receive this response\nyou’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\nmake another request to the real-time server (one of the URLs in the response\nfor 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\nreal-time server, you should start over by making a call to this endpoint\nfirst.", "responses": { "200": { "description": "Returns a paginated array of servers that can be used\ninstead of the regular endpoints for long-polling events.", "schema": { "$ref": "#/definitions/RealtimeServers" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [] }, "get": { "operationId": "get_events", "summary": "List user and enterprise events", "tags": [ "Events" ], "description": "Returns up to a year of past events for a given user\nor for the entire enterprise.\n\nBy default this returns events for the authenticated user. To retrieve\nevents for the entire enterprise, set the `stream_type` to `admin_logs`.\nThe user making the API call will need to have admin privileges, and\nthe application will need to have the permission to access the event feed\nto get the enterprise event feed.", "parameters": [ { "name": "stream_type", "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\n 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\n requires the user making the API call to have admin permissions.", "in": "query", "type": "string", "default": "all", "enum": [ "all", "changes", "sync", "admin_logs" ] }, { "name": "stream_position", "description": "The location in the event stream to start receiving events from.\n\n* `now` will return an empty list events and\nthe latest stream position for initialization.\n* `0` or `null` will return all events.", "in": "query", "type": "string" }, { "name": "limit", "description": "Limits the number of events returned", "in": "query", "type": "integer", "format": "int64", "default": 100, "maximum": 500 }, { "name": "event_type", "description": "A comma-separated list of events to filter by. This can only be used when\nrequesting the events with a `stream_type` of `admin_logs`. For any other\n`stream_type` this value will be ignored.", "in": "query", "type": "array", "items": { "type": "string" } }, { "name": "created_after", "description": "The lower bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.", "in": "query", "type": "string", "format": "date-time" }, { "name": "created_before", "description": "The upper bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.", "in": "query", "required": false, "type": "string", "format": "date-time" } ], "responses": { "200": { "description": "Returns a list of event objects.\n\nEvents objects are returned in pages, with each page (chunk)\nincluding a list of event objects. The response includes a\n`chunk_size` parameter indicating how many events were returned in this\nchunk, as well as the next `stream_position` that can be\nqueried.", "schema": { "$ref": "#/definitions/Events" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/collections": { "get": { "operationId": "get_collections", "summary": "List all collections", "tags": [ "Collections" ], "description": "Retrieves all collections for a given user.\n\nCurrently, only the `favorites` collection\nis supported.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns all collections for the given user", "schema": { "$ref": "#/definitions/Collections" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/collections/{collection_id}/items": { "get": { "operationId": "get_collections_id_items", "summary": "List collection items", "tags": [ "Collections" ], "description": "Retrieves the files and/or folders contained within\nthis collection.", "parameters": [ { "name": "collection_id", "description": "The ID of the collection.", "in": "path", "required": true, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "offset", "description": "The offset of the item at which to begin the response.", "in": "query", "required": false, "type": "integer", "format": "int64", "default": 0 }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns an array of items in the collection.", "schema": { "$ref": "#/definitions/Items" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/recent_items": { "get": { "operationId": "get_recent_items", "summary": "List recently accessed items", "tags": [ "Recent items" ], "description": "Returns information about the recent items accessed\nby a user, either in the last 90 days or up to the last\n1000 items accessed.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns a list recent items access by a user.", "schema": { "$ref": "#/definitions/RecentItems" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/retention_policies": { "get": { "operationId": "get_retention_policies", "summary": "List retention policies", "tags": [ "Retention policies" ], "description": "Retrieves all of the retention policies for an enterprise.", "parameters": [ { "name": "policy_name", "description": "Filters results by a case sensitive prefix of the name of\nretention policies.", "in": "query", "required": false, "type": "string" }, { "name": "policy_type", "description": "Filters results by the type of retention policy.", "in": "query", "required": false, "type": "string", "enum": [ "finite", "indefinite" ] }, { "name": "created_by_user_id", "description": "Filters results by the ID of the user who created policy.", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns a list retention policies in the enterprise.", "schema": { "$ref": "#/definitions/RetentionPolicies" } }, "400": { "description": "Returns a `bad_request` if a non existent `policy_type` was specified.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns a `not_found` error if the user specified in `created_by_user_id`\ndoes not exist.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_retention_policies", "summary": "Create retention policy", "tags": [ "Retention policies" ], "description": "Creates a retention policy.", "responses": { "200": { "description": "Returns a new retention policy object.", "schema": { "$ref": "#/definitions/RetentionPolicy" } }, "400": { "description": "Returns a `bad_request` error with the `retention_length` was\nspecified for a `infinite` retention policy, or an incorrect\n`disposition_action` was set.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if a retention policy with the given name already exists", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "policy_name", "policy_type", "disposition_action" ], "properties": { "policy_name": { "type": "string", "description": "The name for the retention policy" }, "policy_type": { "type": "string", "description": "The type of the retention policy. A retention\npolicy type can either be `finite`, where a\nspecific amount of time to retain the content is known\nupfront, or `indefinite`, where the amount of time\nto retain the content is still unknown.", "enum": [ "finite", "indefinite" ] }, "disposition_action": { "type": "string", "description": "The disposition action of the retention policy.\nThis action can be `permanently_delete`, which\nwill cause the content retained by the policy\nto be permanently deleted, or `remove_retention`,\nwhich will lift the retention policy from the content,\nallowing it to be deleted by users,\nonce the retention policy has expired.", "enum": [ "permanently_delete", "remove_retention" ] }, "retention_length": { "type": "string", "format": "int32", "minimum": 1, "description": "The length of the retention policy. This length\nspecifies the duration in days that the retention\npolicy will be active for after being assigned to\ncontent. If the policy has A `policy_type` of\n`indefinite`, the `retention_length` will also be\n`indefinite`." }, "can_owner_extend_retention": { "type": "boolean", "description": "Whether the owner of a file will be allowed to\nextend the retention." }, "are_owners_notified": { "type": "boolean", "description": "Whether owner and co-owners of a file are notified\nwhen the policy nears expiration." }, "custom_notification_recipients": { "type": "array", "items": { "type": "object", "description": "A user that is notified of an event.", "properties": { "type": { "description": "The type of item to notify", "type": "string", "enum": [ "user" ] }, "id": { "description": "The id of the user to notify", "type": "string" }, "name": { "type": "string", "description": "The name of the user to notify" }, "login": { "type": "string", "description": "The email address the user uses to notify" } } } } } } } ] } }, "/retention_policies/{retention_policy_id}": { "get": { "operationId": "get_retention_policies_id", "summary": "Get retention policy", "tags": [ "Retention policies" ], "description": "Retrieves a retention policy.", "parameters": [ { "name": "retention_policy_id", "description": "The ID of the retention policy.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the retention policy object.", "schema": { "$ref": "#/definitions/RetentionPolicy" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_retention_policies_id", "summary": "Update retention policy", "tags": [ "Retention policies" ], "description": "Updates a retention policy.", "parameters": [ { "name": "retention_policy_id", "description": "The ID of the retention policy.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "policy_name": { "type": "string", "description": "The name for the retention policy" }, "disposition_action": { "type": "string", "description": "The disposition action of the retention policy.\nThis action can be `permanently_delete`, which\nwill cause the content retained by the policy\nto be permanently deleted, or `remove_retention`,\nwhich will lift the retention policy from the content,\nallowing it to be deleted by users,\nonce the retention policy has expired.", "enum": [ "permanently_delete", "remove_retention" ] }, "status": { "type": "string", "description": "Used to retire a retention policy.\n\nIf not retiring a policy, do not include this parameter\nor set it to `null`.", "enum": [ "retired" ] } } } } ], "responses": { "200": { "description": "Returns the updated retention policy object.", "schema": { "$ref": "#/definitions/RetentionPolicy" } }, "400": { "description": "Returns a `bad_request` if an incorrect\n`disposition_action` was set.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if a retention policy with the given name already exists", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/retention_policies/{retention_policy_id}/assignments": { "get": { "operationId": "get_retention_policies_id_assignments", "summary": "List retention policy assignments", "tags": [ "Retention policy assignments" ], "description": "Returns a list of all retention policy assignments associated with a specified\nretention policy.", "parameters": [ { "name": "retention_policy_id", "description": "The ID of the retention policy.", "in": "path", "required": true, "type": "string" }, { "name": "type", "description": "The type of the retention policy assignment to retrieve.", "in": "query", "required": false, "type": "string", "enum": [ "folder", "enterprise" ] }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a list of the retention policy assignments associated with the\nspecified retention policy.", "schema": { "$ref": "#/definitions/RetentionPolicyAssignments" } }, "400": { "description": "Returns an error if an unknown `type` is specified.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/retention_policy_assignments": { "post": { "operationId": "post_retention_policy_assignments", "summary": "Assign retention policy", "tags": [ "Retention policy assignments" ], "description": "Assigns a retention policy to an item.", "responses": { "201": { "description": "Returns a new retention policy assignment object.", "schema": { "$ref": "#/definitions/RetentionPolicyAssignment" } }, "400": { "description": "Returns an error if an `id` is specified while assigning a the\nretention policy to an enterprise.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if no retention policy with the given `policy_id` exists.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if a retention policy of equal or greater length has\nalready been assigned to this item.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "policy_id", "assign_to" ], "properties": { "policy_id": { "type": "string", "description": "The ID of the retention policy to assign" }, "assign_to": { "type": "object", "description": "The item to assign the policy to", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type of item to assign the policy to.", "enum": [ "enterprise", "folder", "metadata_template" ] }, "id": { "type": "string", "description": "The ID of item to assign the policy to.\n\nSet to `null` or omit when `type` is set to\n`enterprise`." } } } } } } ] } }, "/retention_policy_assignments/{retention_policy_assignment_id}": { "get": { "operationId": "get_retention_policy_assignments_id", "summary": "Get retention policy assignment", "tags": [ "Retention policy assignments" ], "description": "Retrieves a retention policy assignment", "parameters": [ { "name": "retention_policy_assignment_id", "description": "The ID of the retention policy assignment.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the retention policy assignment object.", "schema": { "$ref": "#/definitions/RetentionPolicyAssignment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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", "tags": [ "Retention policy assignments" ], "description": "Returns a list of files under retention for a retention policy assignment.", "parameters": [ { "name": "retention_policy_assignment_id", "description": "The ID of the retention policy assignment.", "in": "path", "required": true, "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a list of files under retention that are associated with the\nspecified retention policy assignment.", "schema": { "$ref": "#/definitions/FileVersionRetentions" } }, "400": { "description": "Returns an error if `retention_policy_assignment_id` is not specified.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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", "tags": [ "Retention policy assignments" ], "description": "Returns a list of file versions under retention for a retention policy\nassignment.", "parameters": [ { "name": "retention_policy_assignment_id", "description": "The ID of the retention policy assignment.", "in": "path", "required": true, "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a list of file versions under retention that are associated with\nthe specified retention policy assignment.", "schema": { "$ref": "#/definitions/FileVersionRetentions" } }, "400": { "description": "Returns an error if `retention_policy_assignment_id` is not specified.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/legal_hold_policies": { "get": { "operationId": "get_legal_hold_policies", "summary": "List all legal hold policies", "tags": [ "Legal hold policies" ], "description": "Retrieves a list of legal hold policies that belong to\nan enterprise.", "parameters": [ { "name": "policy_name", "description": "Limits results to policies for which the names start with\nthis search term. This is a case-insensitive prefix.", "in": "query", "required": false, "type": "string" }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a list of legal hold policies.", "schema": { "$ref": "#/definitions/LegalHoldPolicies" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_legal_hold_policies", "summary": "Create legal hold policy", "tags": [ "Legal hold policies" ], "description": "Create a new legal hold policy.", "responses": { "201": { "description": "Returns a new legal hold policy object.", "schema": { "$ref": "#/definitions/LegalHoldPolicy" } }, "400": { "description": "Returns an error if required parameters are missing,\nor neither `is_ongoing` or filter dates are specified.", "schema": { "$ref": "#/definitions/ClientError" } }, "409": { "description": "Returns an error if a policy with this name already exists.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "policy_name" ], "properties": { "policy_name": { "description": "The name of the policy.", "type": "string", "maxLength": 254 }, "description": { "description": "A description for the policy.", "type": "string", "maxLength": 500 }, "filter_started_at": { "description": "The filter start date.\n\nWhen this policy is applied using a `custodian` legal\nhold assignments, it will only apply to file versions\ncreated or uploaded inside of the\ndate range. Other assignment types, such as folders and\nfiles, will ignore the date filter.\n\nRequired if `is_ongoing` is set to `false`.", "type": "string", "maxLength": 500, "format": "date-time" }, "filter_ended_at": { "description": "The filter end date.\n\nWhen this policy is applied using a `custodian` legal\nhold assignments, it will only apply to file versions\ncreated or uploaded inside of the\ndate range. Other assignment types, such as folders and\nfiles, will ignore the date filter.\n\nRequired if `is_ongoing` is set to `false`.", "type": "string", "maxLength": 500, "format": "date-time" }, "is_ongoing": { "description": "Whether new assignments under this policy should\ncontinue applying to files even after initialization.\n\nWhen this policy is applied using a legal hold assignment,\nit will continue applying the policy to any new file versions\neven after it has been applied.\n\nFor example, if a legal hold assignment is placed on a user\ntoday, and that user uploads a file tomorrow, that file will\nget held. This will continue until the policy is retired.\n\nRequired if no filter dates are set.", "type": "boolean" } } } } ] } }, "/legal_hold_policies/{legal_hold_policy_id}": { "get": { "operationId": "get_legal_hold_policies_id", "summary": "Get legal hold policy", "tags": [ "Legal hold policies" ], "description": "Retrieve a legal hold policy.", "parameters": [ { "name": "legal_hold_policy_id", "description": "The ID of the legal hold policy", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a legal hold policy object.", "schema": { "$ref": "#/definitions/LegalHoldPolicy" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_legal_hold_policies_id", "summary": "Update legal hold policy", "tags": [ "Legal hold policies" ], "description": "Update legal hold policy.", "parameters": [ { "name": "legal_hold_policy_id", "description": "The ID of the legal hold policy", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "policy_name": { "description": "The name of the policy.", "type": "string", "maxLength": 254 }, "description": { "description": "A description for the policy.", "type": "string", "maxLength": 500 }, "release_notes": { "description": "Notes around why the policy was released.", "type": "string", "maxLength": 500 } } } } ], "responses": { "200": { "description": "Returns a new legal hold policy object.", "schema": { "$ref": "#/definitions/LegalHoldPolicy" } }, "409": { "description": "Returns an error if a policy with this name already exists.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_legal_hold_policies_id", "tags": [ "Legal hold policies" ], "summary": "Remove legal hold policy", "description": "Delete an existing legal hold policy.\n\nThis is an asynchronous process. The policy will not be\nfully deleted yet when the response returns.", "parameters": [ { "name": "legal_hold_policy_id", "description": "The ID of the legal hold policy", "in": "path", "required": true, "type": "string" } ], "responses": { "202": { "description": "A blank response is returned if the policy was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/legal_hold_policy_assignments": { "get": { "operationId": "get_legal_hold_policy_assignments", "summary": "List legal hold policy assignments", "tags": [ "Legal hold policy assignments" ], "description": "Retrieves a list of items a legal hold policy has been assigned to.", "parameters": [ { "name": "policy_id", "description": "The ID of the legal hold policy", "in": "query", "required": true, "type": "string" }, { "name": "assign_to_type", "description": "Filters the results by the type of item the\npolicy was applied to.", "in": "query", "type": "string", "enum": [ "file", "file_version", "folder", "user" ] }, { "name": "assign_to_id", "description": "Filters the results by the ID of item the\npolicy was applied to.", "in": "query", "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns a list of legal hold policy assignments.", "schema": { "$ref": "#/definitions/LegalHoldPolicyAssignments" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_legal_hold_policy_assignments", "summary": "Assign legal hold policy", "tags": [ "Legal hold policy assignments" ], "description": "Assign a legal hold to a file, file version, folder, or user.", "responses": { "201": { "description": "Returns a new legal hold policy assignment.", "schema": { "$ref": "#/definitions/LegalHoldPolicyAssignment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "policy_id", "assign_to" ], "properties": { "policy_id": { "description": "The ID of the policy to assign.", "type": "string" }, "assign_to": { "type": "object", "description": "The item to assign the policy to", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type of item to assign the policy to", "enum": [ "file", "file_version", "folder", "user" ] }, "id": { "type": "string", "description": "The ID of item to assign the policy to" } } } } } } ] } }, "/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}": { "get": { "operationId": "get_legal_hold_policy_assignments_id", "summary": "Get legal hold policy assignment", "tags": [ "Legal hold policy assignments" ], "description": "Retrieve a legal hold policy assignment.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a legal hold policy object.", "schema": { "$ref": "#/definitions/LegalHoldPolicyAssignment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_legal_hold_policy_assignments_id", "tags": [ "Legal hold policy assignments" ], "summary": "Unassign legal hold policy", "description": "Remove a legal hold from an item.\n\nThis is an asynchronous process. The policy will not be\nfully removed yet when the response returns.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "in": "path", "required": true, "type": "string" } ], "responses": { "202": { "description": "A blank response is returned if the assignment was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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 current file versions for legal hold policy assignment", "tags": [ "Legal hold policy assignments" ], "description": "Get a list of current file versions for a legal hold\nassignment.\n\nIn some cases you may want to get previous file versions instead. In these\ncases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold`\nAPI instead to return any previous versions of a file for this legal hold\npolicy assignment.\n\nDue to ongoing re-architecture efforts this API might not return all file\nversions held for this policy ID. Instead, this API will only return the\nlatest file version held in the newly developed architecture. The `GET\n/file_version_legal_holds` API can be used to fetch current and past versions\nof files held within the legacy architecture.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to\nfind a list of policy assignments for a given policy ID.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "in": "path", "required": true, "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns the list of current file versions held under legal hold for a\nspecific legal hold policy assignment.", "schema": { "$ref": "#/definitions/FileVersionLegalHolds" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/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", "tags": [ "Legal hold policy assignments" ], "description": "Get a list of previous file versions for a legal hold\nassignment.\n\nIn some cases you may only need the latest file versions instead. In these\ncases, use the `GET /legal_hold_policy_assignments/:id/files_on_hold` API\ninstead to return any current (latest) versions of a file for this legal hold\npolicy assignment.\n\nDue to ongoing re-architecture efforts this API might not return all files\nheld for this policy ID. Instead, this API will only return past file versions\nheld in the newly developed architecture. The `GET /file_version_legal_holds`\nAPI can be used to fetch current and past versions of files held within the\nlegacy architecture.\n\nThe `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to\nfind a list of policy assignments for a given policy ID.", "parameters": [ { "name": "legal_hold_policy_assignment_id", "description": "The ID of the legal hold policy assignment", "in": "path", "required": true, "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } } ], "responses": { "200": { "description": "Returns the list of previous file versions held under legal hold for a\nspecific legal hold policy assignment.", "schema": { "$ref": "#/definitions/FileVersionLegalHolds" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/file_version_retentions/{file_version_retention_id}": { "get": { "operationId": "get_file_version_retentions_id", "tags": [ "File version retentions" ], "summary": "Get retention on file", "description": "Returns information about a file version retention.", "parameters": [ { "name": "file_version_retention_id", "description": "The ID of the file version retention", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a file version retention object.", "schema": { "$ref": "#/definitions/FileVersionRetention" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/file_version_legal_holds/{file_version_legal_hold_id}": { "get": { "operationId": "get_file_version_legal_holds_id", "summary": "Get file version legal hold", "tags": [ "File version legal holds" ], "description": "Retrieves information about the legal hold policies\nassigned to a file version.", "parameters": [ { "name": "file_version_legal_hold_id", "description": "The ID of the file version legal hold", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the legal hold policy assignments for the file version.", "schema": { "$ref": "#/definitions/FileVersionLegalHold" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/file_version_legal_holds": { "get": { "operationId": "get_file_version_legal_holds", "summary": "List file version legal holds", "tags": [ "File version legal holds" ], "description": "Get a list of file versions on legal hold for a legal hold\nassignment.\n\nDue to ongoing re-architecture efforts this API might not return all file\nversions for this policy ID.\n\nInstead, this API will only return file versions held in the legacy\narchitecture. Two new endpoints will available to request any file versions\nheld in the new architecture.\n\nFor file versions held in the new architecture, the `GET\n/legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to\nreturn all past file versions available for this policy assignment, and the\n`GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to\nreturn 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\nfind 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", "description": "The ID of the legal hold policy to get the file version legal\nholds for.", "in": "query", "required": true, "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns the list of file version legal holds for a specific legal\nhold policy.", "schema": { "$ref": "#/definitions/FileVersionLegalHolds" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/device_pinners/{device_pinner_id}": { "get": { "operationId": "get_device_pinners_id", "summary": "Get device pin", "tags": [ "Device pinners" ], "description": "Retrieves information about an individual device pin.", "parameters": [ { "name": "device_pinner_id", "description": "The ID of the device pin", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns information about a single device pin.", "schema": { "$ref": "#/definitions/DevicePinner" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_device_pinners_id", "summary": "Remove device pin", "tags": [ "Device pinners" ], "description": "Deletes an individual device pin.", "parameters": [ { "name": "device_pinner_id", "description": "The ID of the device pin", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the pin has been deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/enterprises/{enterprise_id}/device_pinners": { "get": { "operationId": "get_enterprises_id_device_pinners", "summary": "List enterprise device pins", "tags": [ "Device pinners" ], "description": "Retrieves all the device pins within an enterprise.\n\nThe user must have admin privileges, and the application\nneeds the \"manage enterprise\" scope to make this call.", "parameters": [ { "name": "enterprise_id", "description": "The ID of the enterprise", "in": "path", "required": true, "type": "string" }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "direction", "description": "The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.", "in": "query", "required": false, "type": "string", "enum": [ "ASC", "DESC" ] } ], "responses": { "200": { "description": "Returns a list of device pins for a given enterprise.", "schema": { "$ref": "#/definitions/DevicePinners" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/terms_of_services": { "get": { "operationId": "get_terms_of_services", "summary": "List terms of services", "tags": [ "Terms of service" ], "description": "Returns the current terms of service text and settings\nfor the enterprise.", "parameters": [ { "name": "tos_type", "description": "Limits the results to the terms of service of the given type.", "in": "query", "required": false, "type": "string", "enum": [ "external", "managed" ] } ], "responses": { "200": { "description": "Returns a collection of terms of service text and settings for the\nenterprise.", "schema": { "$ref": "#/definitions/TermsOfServices" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_terms_of_services", "tags": [ "Terms of service" ], "summary": "Create terms of service", "description": "Creates a terms of service for a given enterprise\nand type of user.", "responses": { "200": { "description": "Returns a new task object", "schema": { "$ref": "#/definitions/Task" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "status", "text" ], "properties": { "status": { "description": "Whether this terms of service is active.", "type": "string", "enum": [ "enabled", "disabled" ] }, "tos_type": { "description": "The type of user to set the terms of\nservice for.", "type": "string", "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" } } } } ] } }, "/terms_of_services/{terms_of_service_id}": { "get": { "operationId": "get_terms_of_services_id", "summary": "Get terms of service", "tags": [ "Terms of service" ], "description": "Fetches a specific terms of service.", "parameters": [ { "name": "terms_of_service_id", "description": "The ID of the terms of service.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a terms of service object.", "schema": { "$ref": "#/definitions/TermsOfService" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_terms_of_services_id", "summary": "Update terms of service", "tags": [ "Terms of service" ], "description": "Updates a specific terms of service.", "parameters": [ { "name": "terms_of_service_id", "description": "The ID of the terms of service.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "status", "text" ], "properties": { "status": { "description": "Whether this terms of service is active.", "type": "string", "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" } } } } ], "responses": { "200": { "description": "Returns an updated terms of service object.", "schema": { "$ref": "#/definitions/TermsOfService" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/terms_of_service_user_statuses": { "get": { "operationId": "get_terms_of_service_user_statuses", "summary": "List terms of service user statuses", "tags": [ "Terms of service user statuses" ], "description": "Retrieves an overview of users and their status for a\nterms of service, including Whether they have accepted\nthe terms and when.", "parameters": [ { "name": "tos_id", "description": "The ID of the terms of service.", "in": "query", "required": true, "type": "string" }, { "name": "user_id", "description": "Limits results to the given user ID.", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns a list of terms of service statuses.", "schema": { "$ref": "#/definitions/TermsOfServiceUserStatuses" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_terms_of_service_user_statuses", "summary": "Create terms of service status for new user", "tags": [ "Terms of service user statuses" ], "description": "Sets the status for a terms of service for a user.", "responses": { "200": { "description": "Returns a terms of service status object.", "schema": { "$ref": "#/definitions/TermsOfServiceUserStatus" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "tos", "user", "is_accepted" ], "properties": { "tos": { "type": "object", "description": "The terms of service to set the status for.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "The type of object.", "enum": [ "terms_of_service" ] }, "id": { "type": "string", "description": "The ID of terms of service" } } }, "user": { "type": "object", "description": "The user to set the status for.", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "description": "The type of object.", "enum": [ "user" ] }, "id": { "type": "string", "description": "The ID of user" } } }, "is_accepted": { "type": "boolean", "description": "Whether the user has accepted the terms." } } } } ] } }, "/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", "tags": [ "Terms of service user statuses" ], "description": "Updates the status for a terms of service for a user.", "parameters": [ { "name": "terms_of_service_user_status_id", "description": "The ID of the terms of service status.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "is_accepted" ], "properties": { "is_accepted": { "type": "boolean", "description": "Whether the user has accepted the terms." } } } } ], "responses": { "200": { "description": "Returns the updated terms of service status object.", "schema": { "$ref": "#/definitions/TermsOfServiceUserStatus" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/collaboration_whitelist_entries": { "get": { "operationId": "get_collaboration_whitelist_entries", "summary": "List allowed collaboration domains", "tags": [ "Domain restrictions for collaborations" ], "description": "Returns the list domains that have been deemed safe to create collaborations\nfor within the current enterprise.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a collection of domains that are allowed for collaboration.", "schema": { "$ref": "#/definitions/CollaborationAllowlistEntries" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_collaboration_whitelist_entries", "summary": "Add domain to list of allowed collaboration domains", "tags": [ "Domain restrictions for collaborations" ], "description": "Creates a new entry in the list of allowed domains to allow\ncollaboration for.", "responses": { "200": { "description": "Returns a new entry on the list of allowed domains.", "schema": { "$ref": "#/definitions/CollaborationAllowlistEntry" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "domain", "direction" ], "properties": { "domain": { "type": "string", "description": "The domain to add to the list of allowed domains." }, "direction": { "type": "string", "description": "The direction in which to allow collaborations.", "enum": [ "inbound", "outbound", "both" ] } } } } ] } }, "/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}": { "get": { "operationId": "get_collaboration_whitelist_entries_id", "summary": "Get allowed collaboration domain", "tags": [ "Domain restrictions for collaborations" ], "description": "Returns a domain that has been deemed safe to create collaborations\nfor within the current enterprise.", "parameters": [ { "name": "collaboration_whitelist_entry_id", "description": "The ID of the entry in the list.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns an entry on the list of allowed domains.", "schema": { "$ref": "#/definitions/CollaborationAllowlistEntry" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_collaboration_whitelist_entries_id", "summary": "Remove domain from list of allowed collaboration domains", "tags": [ "Domain restrictions for collaborations" ], "description": "Removes a domain from the list of domains that have been deemed safe to create\ncollaborations for within the current enterprise.", "parameters": [ { "name": "collaboration_whitelist_entry_id", "description": "The ID of the entry in the list.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "A blank response is returned if the entry was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/collaboration_whitelist_exempt_targets": { "get": { "operationId": "get_collaboration_whitelist_exempt_targets", "summary": "List users exempt from collaboration domain restrictions", "tags": [ "Domain restrictions (User exemptions)" ], "description": "Returns a list of users who have been exempt from the collaboration\ndomain restrictions.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a collection of user exemptions.", "schema": { "$ref": "#/definitions/CollaborationAllowlistExemptTargets" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_collaboration_whitelist_exempt_targets", "summary": "Create user exemption from collaboration domain restrictions", "tags": [ "Domain restrictions (User exemptions)" ], "description": "Exempts a user from the restrictions set out by the allowed list of domains\nfor collaborations.", "responses": { "200": { "description": "Returns a new exemption entry.", "schema": { "$ref": "#/definitions/CollaborationAllowlistExemptTarget" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "type": "object", "description": "The user to exempt.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the user to exempt." } } } } } } ] } }, "/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", "tags": [ "Domain restrictions (User exemptions)" ], "description": "Returns a users who has been exempt from the collaboration\ndomain restrictions.", "parameters": [ { "name": "collaboration_whitelist_exempt_target_id", "description": "The ID of the exemption to the list.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the user's exempted from the list of collaboration domains.", "schema": { "$ref": "#/definitions/CollaborationAllowlistExemptTarget" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_collaboration_whitelist_exempt_targets_id", "summary": "Remove user from list of users exempt from domain restrictions", "tags": [ "Domain restrictions (User exemptions)" ], "description": "Removes a user's exemption from the restrictions set out by the allowed list\nof domains for collaborations.", "parameters": [ { "name": "collaboration_whitelist_exempt_target_id", "description": "The ID of the exemption to the list.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "A blank response is returned if the exemption was\nsuccessfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/storage_policies": { "get": { "operationId": "get_storage_policies", "summary": "List storage policies", "tags": [ "Storage policies" ], "description": "Fetches all the storage policies in the enterprise.", "parameters": [ { "name": "fields", "description": "A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.", "in": "query", "required": false, "type": "array", "items": { "type": "string" } }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a collection of storage policies.", "schema": { "$ref": "#/definitions/StoragePolicies" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/storage_policies/{storage_policy_id}": { "get": { "operationId": "get_storage_policies_id", "summary": "Get storage policy", "tags": [ "Storage policies" ], "description": "Fetches a specific storage policy.", "parameters": [ { "name": "storage_policy_id", "description": "The ID of the storage policy.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a storage policy object.", "schema": { "$ref": "#/definitions/StoragePolicy" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/storage_policy_assignments": { "get": { "operationId": "get_storage_policy_assignments", "summary": "List storage policy assignments", "tags": [ "Storage policy assignments" ], "description": "Fetches all the storage policy assignment for an enterprise or user.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "resolved_for_type", "in": "query", "description": "The target type to return assignments for", "required": true, "type": "string", "enum": [ "user", "enterprise" ] }, { "name": "resolved_for_id", "in": "query", "required": true, "description": "The ID of the user or enterprise to return assignments for", "type": "string" } ], "responses": { "200": { "description": "Returns a collection of storage policies for\nthe enterprise or user.", "schema": { "$ref": "#/definitions/StoragePolicyAssignments" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_storage_policy_assignments", "summary": "Assign storage policy", "tags": [ "Storage policy assignments" ], "description": "Creates a storage policy assignment for an enterprise or user.", "responses": { "200": { "description": "Returns the new storage policy assignment created.", "schema": { "$ref": "#/definitions/StoragePolicyAssignment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "storage_policy", "assigned_to" ], "properties": { "storage_policy": { "type": "object", "description": "The storage policy to assign to the user or\nenterprise", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type to assign.", "enum": [ "storage_policy" ] }, "id": { "type": "string", "description": "The ID of the storage policy to assign." } } }, "assigned_to": { "type": "object", "description": "The user or enterprise to assign the storage\npolicy to.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type to assign the policy to.", "enum": [ "user", "enterprise" ] }, "id": { "type": "string", "description": "The ID of the user or enterprise" } } } } } } ] } }, "/storage_policy_assignments/{storage_policy_assignment_id}": { "get": { "operationId": "get_storage_policy_assignments_id", "summary": "Get storage policy assignment", "tags": [ "Storage policy assignments" ], "description": "Fetches a specific storage policy assignment.", "parameters": [ { "name": "storage_policy_assignment_id", "description": "The ID of the storage policy assignment.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a storage policy assignment object.", "schema": { "$ref": "#/definitions/StoragePolicyAssignment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "put": { "operationId": "put_storage_policy_assignments_id", "summary": "Update storage policy assignment", "tags": [ "Storage policy assignments" ], "description": "Updates a specific storage policy assignment.", "parameters": [ { "name": "storage_policy_assignment_id", "description": "The ID of the storage policy assignment.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "storage_policy" ], "properties": { "storage_policy": { "type": "object", "description": "The storage policy to assign to the user or\nenterprise", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The type to assign.", "enum": [ "storage_policy" ] }, "id": { "type": "string", "description": "The ID of the storage policy to assign." } } } } } } ], "responses": { "200": { "description": "Returns an updated storage policy assignment object.", "schema": { "$ref": "#/definitions/StoragePolicyAssignment" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "delete": { "operationId": "delete_storage_policy_assignments_id", "summary": "Unassign storage policy", "tags": [ "Storage policy assignments" ], "description": "Delete a storage policy assignment.\n\nDeleting a storage policy assignment on a user\nwill have the user inherit the enterprise's default\nstorage policy.\n\nThere is a rate limit for calling this endpoint of only\ntwice per user in a 24 hour time frame.", "parameters": [ { "name": "storage_policy_assignment_id", "description": "The ID of the storage policy assignment.", "in": "path", "required": true, "type": "string" } ], "responses": { "204": { "description": "Returns an empty response when the storage policy\nassignment is successfully deleted." }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/zip_downloads": { "post": { "operationId": "post_zip_downloads", "summary": "Create zip download", "tags": [ "Zip Downloads" ], "description": "Creates a request to download multiple files and folders as a single `zip`\narchive file. This API does not return the archive but instead performs all\nthe checks to ensure that the user has access to all the items, and then\nreturns a `download_url` and a `status_url` that can be used to download the\narchive.\n\nThe limit for an archive is either the Account's upload limit or\n10,000 files, whichever is met first", "responses": { "202": { "description": "If the `zip` archive is ready to be downloaded, the API will return a\nresponse that will include a `download_url`, a `status_url`, as well as\nany conflicts that might have occurred when creating the request.", "schema": { "$ref": "#/definitions/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\nnot valid.\n\nIn most cases, this error might happen because the JSON request body is\nnot valid JSON, any of the items has an incorrect or missing ID, any of\nthe items is not a file or folder, or the root folder with ID `0` has been\nadded 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\nof files and folders are empty. Additionally, it this error might be\nreturned when attempting to add the root folder with ID `0` to an archive.\n* `zip_download_file_count_exceeded_limit` - the requested files and\nfolders would result in an archive with more than 10,000 files. The\nrequest will have to be split into multiple requests to reduce the number\nof files per archive.\n* `zip_download_pre_compressed_bytes_exceeded_limit` - the requested files\nand folders would result in an archive with more than the allowed download\nlimit. The request will have to be split into multiple requests to reduce\nthe size of the archive.", "schema": { "$ref": "#/definitions/ClientError" } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned when an authorization header is provided but the user does not\nhave access to the items.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/ZipDownloadRequest" } } ] } }, "/zip_downloads/{zip_download_id}/status": { "get": { "operationId": "get_zip_downloads_id_status", "summary": "Get zip download status", "tags": [ "Zip Downloads" ], "description": "Returns the download status of a `zip` archive, allowing an application to\ninspect the progress of the download as well as the number of items that\nmight have been skipped.\n\nThis endpoint can only be accessed once the download has started.\nSubsequently this endpoint is valid for 12 hours from the start of the\ndownload.\n\nThe URL of this endpoint should not be considered as fixed. Instead, use\nthe [Create zip download](e://post_zip_downloads) API to request to create a\n`zip` archive, and then follow the `status_url` field in the response to\nthis endpoint.", "parameters": [ { "name": "zip_download_id", "description": "The unique identifier that represent this `zip` archive.", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns the status of the `zip` archive that is being downloaded.", "schema": { "$ref": "#/definitions/ZipDownloadStatus" } }, "401": { "description": "Returned when the access token provided in the `Authorization` header\nis not recognized or not provided.", "schema": { "$ref": "#/definitions/ClientError" } }, "403": { "description": "Returned when an authorization header is provided but the user does not\nhave access to the items.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the ID of this download request is not valid, or if\nthe status of a download is requested before the download has been\nstarted.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/sign_requests/{sign_request_id}/cancel": { "post": { "operationId": "post_sign_requests_id_cancel", "summary": "Cancel sign request", "tags": [ "Box Sign" ], "description": "Cancels a sign request.", "parameters": [ { "name": "sign_request_id", "description": "The ID of the sign request", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a Sign Request object.", "schema": { "$ref": "#/definitions/SignRequest" } }, "404": { "description": "Returns an error when the sign request cannot be found or the user does\nnot have access to the sign request.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/sign_requests/{sign_request_id}/resend": { "post": { "operationId": "post_sign_requests_id_resend", "summary": "Resend sign request", "tags": [ "Box Sign" ], "description": "Resends a sign request email to all outstanding signers.", "parameters": [ { "name": "sign_request_id", "description": "The ID of the sign request", "in": "path", "required": true, "type": "string" } ], "responses": { "202": { "description": "Returns an empty response when the API call was successful.\nThe email notifications will be sent asynchronously." }, "404": { "description": "Returns an error when the sign request cannot be found or the user does\nnot have access to the sign request.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/sign_requests/{sign_request_id}": { "get": { "operationId": "get_sign_requests_id", "summary": "Get sign request by ID", "tags": [ "Box Sign" ], "description": "Gets a sign request by ID.", "parameters": [ { "name": "sign_request_id", "description": "The ID of the sign request", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Returns a sign request", "schema": { "$ref": "#/definitions/SignRequest" } }, "404": { "description": "Returns an error when the sign request cannot be found or the user does\nnot have access to the sign request.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/sign_requests": { "get": { "operationId": "get_sign_requests", "summary": "List sign requests", "tags": [ "Box Sign" ], "description": "Gets sign requests created by a user.", "parameters": [ { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 } ], "responses": { "200": { "description": "Returns a collection of sign requests", "schema": { "$ref": "#/definitions/SignRequests" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } }, "post": { "operationId": "post_sign_requests", "summary": "Create sign request", "tags": [ "Box Sign" ], "description": "Creates a sign request. This involves preparing a document for signing and\nsending the sign request to signers.", "responses": { "201": { "description": "Returns a Sign Request object.", "schema": { "$ref": "#/definitions/SignRequest" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } }, "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/SignRequestCreateRequest" } } ] } }, "/workflows": { "get": { "operationId": "get_workflows", "summary": "List workflows", "tags": [ "Workflows" ], "description": "Returns list of workflows that act on a given `folder ID`, and\nhave a flow with a trigger type of `WORKFLOW_MANUAL_START`.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in to use this endpoint.", "parameters": [ { "name": "folder_id", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting this folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folder/123`\nthe `folder_id` is `123`.\n\nThe root folder of a Box account is\nalways represented by the ID `0`.", "in": "query", "required": true, "type": "string" }, { "name": "trigger_type", "description": "Type of trigger to search for.", "in": "query", "required": false, "type": "string" }, { "name": "limit", "description": "The maximum number of items to return per page.", "in": "query", "required": false, "type": "integer", "format": "int64", "maximum": 1000 }, { "name": "marker", "description": "Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "Returns the workflow.", "schema": { "$ref": "#/definitions/Workflows" } }, "400": { "description": "Returned if the trigger type is not `WORKFLOW_MANUAL_START`.", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returned if the folder is not found, or the user does not\nhave access to the folder.", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } }, "/workflows/{workflow_id}/start": { "post": { "operationId": "post_workflows_id_start", "summary": "Starts workflow based on request body", "tags": [ "Workflows" ], "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\nscope within the developer console.", "parameters": [ { "name": "workflow_id", "description": "The ID of the workflow.", "in": "path", "required": true, "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "flow", "files", "folder" ], "properties": { "type": { "type": "string", "description": "The type of the parameters object", "enum": [ "workflow_parameters" ] }, "flow": { "type": "object", "description": "The flow that will be triggered", "properties": { "type": { "type": "string", "description": "The type of the flow object" }, "id": { "type": "string", "description": "The id of the flow" } } }, "files": { "type": "array", "description": "The array of files for which the workflow should start. All files\nmust be in the workflow's configured folder.", "items": { "type": "object", "description": "A file the workflow should start for", "properties": { "type": { "type": "string", "description": "The type of the file object", "enum": [ "file" ] }, "id": { "type": "string", "description": "The id of the file" } } } }, "folder": { "type": "object", "description": "The folder object for which the workflow is configured.", "properties": { "type": { "type": "string", "description": "The type of the folder object", "enum": [ "folder" ] }, "id": { "type": "string", "description": "The id of the folder" } } }, "outcomes": { "type": "array", "description": "A list of outcomes required to be configured at start time.", "items": { "type": "object", "description": "A configurable outcome the workflow should complete. If you\nhave a `task_completion_rule`, you may input `all_assignees` or\n`any_assignee` in the `variable_value` field. Similarly, if you\nhave a `collaborator_role`, you may input `editor`, `viewer`,\n`previewer`, `uploader`, `previewer uploader`, `viewer uploader`\n, `co-owner` in the `variable_value` field." } } } } } ], "responses": { "204": { "description": "Starts the workflow." }, "400": { "description": "Returns an error if some of the parameters are missing or\nnot 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\n enabled for the specified folder id\n* `parameters_provided_do_not_match_target_outcome` when the provided\n parameters do not match the expected parameters", "schema": { "$ref": "#/definitions/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\n or folder\n* `missing_relay_full_access` when the user does not have access to Relay\n Full", "schema": { "$ref": "#/definitions/ClientError" } }, "404": { "description": "Returns an error if the workflow could not be found,\nor 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", "schema": { "$ref": "#/definitions/ClientError" } }, "default": { "description": "An unexpected client error.", "schema": { "$ref": "#/definitions/ClientError" } } } } } }, "securityDefinitions": { "OAuth2Security": { "type": "oauth2", "flow": "accessCode", "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": [] } ], "definitions": { "File": { "title": "File", "type": "object", "x-box-variant": "standard", "description": "A standard representation of a file, as returned from any\nfile API endpoints by default", "allOf": [ { "$ref": "#/definitions/File--Mini" }, { "properties": { "description": { "type": "string", "description": "The optional description of this file", "maxLength": 256 }, "size": { "type": "integer", "description": "The file size in bytes. Be careful parsing this integer as it can\nget very large and cause an integer overflow." }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "description": "The parent folders for this item", "items": { "$ref": "#/definitions/Folder--Mini" } } } }, { "description": "The tree of folders that this file is contained in,\nstarting at the root." }, {} ] }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the file was created on Box." }, "modified_at": { "type": "string", "format": "date-time", "description": "The date and time when the file was last updated on Box." }, "trashed_at": { "type": "string", "format": "date-time", "description": "The time at which this file was put in the trash." }, "purged_at": { "type": "string", "format": "date-time", "description": "The time at which this file is expected to be purged\nfrom the trash." }, "content_created_at": { "type": "string", "format": "date-time", "description": "The date and time at which this file was originally\ncreated, which might be before it was uploaded to Box." }, "content_modified_at": { "type": "string", "format": "date-time", "description": "The date and time at which this file was last updated,\nwhich might be before it was uploaded to Box." }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created this file" } ] }, "modified_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who last modified this file" }, {} ] }, "owned_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who owns this file" }, {} ] }, "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\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.", "type": "object", "properties": { "url": { "type": "string", "format": "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\ncan be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url`\nhas been set for this shared link." }, "download_url": { "type": "string", "format": "url", "x-box-premium-feature": true, "description": "A URL that can be used to download the file. This URL can be used in\na browser to download the file. This URL includes the file\nextension so that the file will be saved with the right file type.\n\nThis property will be `null` for folders." }, "vanity_url": { "type": "string", "format": "url", "description": "The \"Custom URL\" that can also be used to preview the item on Box. Custom\nURLs can only be created or modified in the Box Web application." }, "vanity_name": { "type": "string", "description": "The custom name of a shared link, as used in the `vanity_url` field." }, "access": { "type": "string", "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin.", "enum": [ "open", "company", "collaborators" ] }, "effective_access": { "type": "string", "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.", "enum": [ "open", "company", "collaborators" ] }, "effective_permission": { "type": "string", "description": "The effective permissions for this shared link.", "enum": [ "can_download", "can_preview" ] }, "unshared_at": { "type": "string", "format": "date-time", "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts." }, "is_password_enabled": { "type": "boolean", "description": "Defines if the shared link requires a password to access the item." }, "permissions": { "type": "object", "description": "Defines if this link allows a user to preview and download an item.", "properties": { "can_download": { "type": "boolean", "description": "Defines if the shared link allows for the item to be downloaded. For\nshared 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\nset to `open` or `company`, not `collaborators`." }, "can_preview": { "type": "boolean", "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\napplies to any items in the folder." } } }, "download_count": { "type": "integer", "description": "The number of times this item has been downloaded." }, "preview_count": { "type": "integer", "description": "The number of times this item has been previewed." } } }, { "description": "The shared link for this file. This will be\n`null` if no shared link has been created for this\nfile." }, {} ] }, "parent": { "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "description": "The folder that this file is located within." } ] }, "item_status": { "type": "string", "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.", "enum": [ "active", "trashed", "deleted" ] } } } ] }, "ClientError": { "title": "Client error", "type": "object", "description": "A generic error", "properties": { "type": { "description": "`error`", "type": "string", "enum": [ "error" ] }, "status": { "description": "The HTTP status of the response.", "type": "integer", "format": "int32" }, "code": { "description": "A Box-specific error code", "type": "string", "enum": [ "created", "accepted", "no_content", "redirect", "not_modified", "bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "precondition_failed", "too_many_requests", "internal_server_error", "unavailable", "item_name_invalid", "insufficient_scope" ] }, "message": { "description": "A short message describing the error.", "type": "string" }, "context_info": { "description": "A free-form object that contains additional context\nabout the error. The possible fields are defined on\na per-endpoint basis.", "type": "object" }, "help_url": { "description": "A URL that links to more information about why this error occurred.", "type": "string" }, "request_id": { "description": "A unique identifier for this response, which can be used\nwhen contacting Box support.", "type": "string" } } }, "UploadUrl": { "title": "Upload URL", "type": "object", "description": "The details for the upload session for the file.", "properties": { "upload_url": { "type": "string", "description": "A URL for an upload session that can be used to upload\nthe file." }, "upload_token": { "type": "string", "description": "An optional access token to use to upload the file" } } }, "ConflictError": { "title": "Conflict error", "type": "object", "description": "The error that occurs when a file can not be created due\nto a conflict.", "allOf": [ { "$ref": "#/definitions/ClientError" }, { "properties": { "context_info": { "type": "object", "properties": { "conflicts": { "type": "array", "description": "A list of the file conflicts that caused this error.", "items": { "$ref": "#/definitions/FileConflict" } } } } } } ] }, "Collaborations": { "title": "Collaborations", "type": "object", "description": "A list of collaborations", "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.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/Collaboration" } } } } ] }, "Comments": { "title": "Comments", "type": "object", "description": "A list of comments", "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.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/Comment" } } } } ] }, "Tasks": { "title": "Tasks", "type": "object", "description": "A list of tasks", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection.\nThe total number of entries in the collection may be less than\n`total_count`.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/Task" } } } }, "FileVersions": { "title": "File versions", "type": "object", "description": "A list of file versions", "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.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/FileVersion" } } } } ] }, "FileVersion": { "title": "File version", "type": "object", "x-box-variant": "standard", "description": "A standard representation of a file version", "allOf": [ { "$ref": "#/definitions/FileVersion--Mini" }, { "properties": { "name": { "type": "string", "description": "The name of the file version" }, "size": { "type": "integer", "format": "int64", "description": "Size of the file version in bytes" }, "created_at": { "type": "string", "format": "date-time", "description": "When the file version object was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the file version object was last updated" }, "modified_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who last updated the file version" } ] }, "trashed_at": { "type": "string", "description": "When the file version object was trashed.", "format": "date-time" }, "trashed_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who trashed the file version" } ] }, "restored_at": { "type": "string", "description": "When the file version was restored from the trash.", "format": "date-time" }, "restored_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who restored the file version from the trash." } ] }, "purged_at": { "type": "string", "description": "When the file version object will be permanently deleted.", "format": "date-time" }, "uploader_display_name": { "allOf": [ { "title": "Uploader display name", "type": "string", "description": "The display name of the user that uploaded the file. In most cases this is the\nname 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\nprovide an email address, this field is populated with that email address. If\nan email address was not required in the File Request form, this field is set\nto return a value of `File Request`.\n\nIn all other anonymous cases where no email was provided this field\nwill default to a value of `Someone`." } ] } } } ] }, "Metadatas": { "title": "Metadata instances", "type": "object", "description": "A list of metadata instances that have been applied to a file or folder.", "properties": { "entries": { "type": "array", "description": "A list of metadata instances, as applied to this file or folder.", "items": { "$ref": "#/definitions/Metadata" } }, "limit": { "description": "The limit that was used for this page of results.", "type": "integer" } } }, "Classification": { "title": "Classification", "type": "object", "description": "An instance of the classification metadata template, containing\nthe classification applied to the file or folder.\n\nTo get more details about the classification applied to an item,\nrequest the classification metadata template.", "properties": { "Box__Security__Classification__Key": { "type": "string", "description": "The name of the classification applied to the item." }, "$parent": { "type": "string", "description": "The identifier of the item that this metadata instance\nhas been attached to. This combines the `type` and the `id`\nof the parent in the form `{type}_{id}`." }, "$template": { "type": "string", "description": "`securityClassification-6VMVochwUWo`", "enum": [ "securityClassification-6VMVochwUWo" ] }, "$scope": { "type": "string", "description": "The scope of the enterprise that this classification has been\napplied for.\n\nThis will be in the format `enterprise_{enterprise_id}`." }, "$version": { "type": "integer", "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a classification is updated." }, "$type": { "type": "string", "description": "The unique ID of this classification instance. This will be include\nthe name of the classification template and a unique ID." }, "$typeVersion": { "type": "number", "description": "The version of the metadata template. This version starts at 0 and\nincreases every time the template is updated. This is mostly for internal\nuse." }, "$canEdit": { "type": "boolean", "description": "Whether an end user can change the classification." } } }, "Metadata": { "title": "Metadata instance", "type": "object", "x-box-variant": "standard", "description": "An instance of a metadata template, which has been applied to a file or\nfolder.", "allOf": [ { "$ref": "#/definitions/Metadata--Base" } ] }, "SkillCardsMetadata": { "title": "Skills metadata instance", "type": "object", "description": "The metadata assigned to a using for Box skills.", "properties": { "$canEdit": { "type": "boolean", "description": "Whether the user can edit this metadata" }, "$id": { "type": "string", "format": "uuid", "maxLength": 36, "description": "A UUID to identify the metadata object" }, "$parent": { "type": "string", "description": "An ID for the parent folder" }, "$scope": { "type": "string", "description": "An ID for the scope in which this template\nhas been applied" }, "$template": { "type": "string", "description": "The name of the template" }, "$type": { "type": "string", "description": "A unique identifier for the \"type\" of this instance. This is an internal\nsystem property and should not be used by a client application." }, "$typeVersion": { "type": "integer", "description": "The last-known version of the template of the object. This is an internal\nsystem property and should not be used by a client application." }, "$version": { "type": "integer", "description": "The version of the metadata object. Starts at 0 and increases every time\na user-defined property is modified." }, "cards": { "type": "array", "description": "A list of Box Skill cards that have been applied to this file.", "items": { "$ref": "#/definitions/SkillCard" } } } }, "SkillCard": { "type": "object", "title": "Skill Card", "description": "A generic Box Skill metadata card.", "required": [ "type", "skill_card_type", "skill", "invocation" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The optional date and time this card was created at." }, "type": { "type": "string", "description": "`skill_card`", "enum": [ "skill_card" ] }, "skill_card_type": { "type": "string", "description": "The type of card to add to the file.", "enum": [ "transcript", "keyword", "timeline", "status" ] }, "skill_card_title": { "type": "object", "description": "The title of the card.", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "An optional identifier for the title." }, "message": { "type": "string", "description": "The actual title to show in the UI." } } }, "status": { "type": "object", "description": "Used with a card of type `status` to set the status of the skill. This can be used to show a message to the user while the Skill is processing the data.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "A code for the status of this Skill invocation. By\ndefault each of these will have their own accompanied\nmessages. These can be adjusted by setting the `message`\nvalue on this object.", "enum": [ "invoked", "processing", "success", "transient_failure", "permanent_failure" ] }, "message": { "type": "string", "description": "A custom message that can be provided with this status.\nThis will be shown in the web app to the end user." } } }, "skill": { "type": "object", "description": "The service that applied this metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`service`", "enum": [ "service" ] }, "id": { "type": "string", "description": "A custom identifier that represent the service that\napplied this metadata." } } }, "invocation": { "type": "object", "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`skill_invocation`", "enum": [ "skill_invocation" ] }, "id": { "type": "string", "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." } } }, "duration": { "type": "integer", "description": "An optional total duration in seconds.\n\nUsed with a `skill_card_type` of `transcript` or\n`timeline`." }, "entries": { "type": "array", "description": "An optional list of entries in the metadata card.\n\nThis field is used with a `skill_card_type` of\n`transcript`, `keyword` or `timeline`.", "items": { "type": "object", "description": "An entry in the `entries` attribute of a metadata card", "properties": { "text": { "type": "string", "description": "The text of the entry. This would be the actual\nkeyword in a `keyword` card, the line of a\ntranscript in a `transcript` card, or the display\nname for an item when using the `timeline` entry." }, "appears": { "type": "array", "description": "Defines a list of timestamps for an entry. This is\nused with a `skill_card_type` of `transcript` as\nwell as `timeline` to place items on a timeline.\n\nFor a `skill_card_type` of `transcript` there can\nonly be one entry in this list for each item, and\nonly the `start` time is used to place the\ntranscript on the timeline.", "required": [ "start", "end" ], "items": { "type": "object", "description": "The timestamp for an entry.", "properties": { "start": { "type": "integer", "description": "The time in seconds when an\nentry should start appearing on a timeline." }, "end": { "type": "integer", "description": "The time in seconds when an\nentry should stop appearing on a timeline. For\na `skill_card_type` of `transcript` this value\nis ignored." } } } }, "image_url": { "type": "string", "description": "The image to show on a for an entry that appears\non a timeline. This image URL is required for any\n`timeline` cards. The image will be shown in a\nlist of items (for example faces), and clicking\nthe image will show the user where that entry\nappears during the duration of this entry." } } } } } }, "KeywordSkillCard": { "type": "object", "title": "Keyword Skill Card", "description": "A skill card that contains a set of keywords", "required": [ "type", "skill_card_type", "skill", "invocation", "entries" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The optional date and time this card was created at." }, "type": { "type": "string", "description": "`skill_card`", "enum": [ "skill_card" ] }, "skill_card_type": { "type": "string", "description": "`keyword`", "enum": [ "keyword" ] }, "skill_card_title": { "type": "object", "description": "The title of the card.", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "An optional identifier for the title." }, "message": { "type": "string", "description": "The actual title to show in the UI." } } }, "skill": { "type": "object", "description": "The service that applied this metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`service`", "enum": [ "service" ] }, "id": { "type": "string", "description": "A custom identifier that represent the service that\napplied this metadata." } } }, "invocation": { "type": "object", "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`skill_invocation`", "enum": [ "skill_invocation" ] }, "id": { "type": "string", "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." } } }, "entries": { "type": "array", "description": "An list of entries in the metadata card.", "items": { "type": "object", "description": "An entry in the `entries` attribute of a metadata card", "properties": { "text": { "type": "string", "description": "The text of the keyword." } } } } } }, "TimelineSkillCard": { "type": "object", "title": "Timeline Skill Card", "description": "A Box Skill metadata card that places a list of images on a\ntimeline.", "required": [ "type", "skill_card_type", "skill", "invocation", "entries" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The optional date and time this card was created at." }, "type": { "type": "string", "description": "`skill_card`", "enum": [ "skill_card" ] }, "skill_card_type": { "type": "string", "description": "`timeline`", "enum": [ "timeline" ] }, "skill_card_title": { "type": "object", "description": "The title of the card.", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "An optional identifier for the title." }, "message": { "type": "string", "description": "The actual title to show in the UI." } } }, "skill": { "type": "object", "description": "The service that applied this metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`service`", "enum": [ "service" ] }, "id": { "type": "string", "description": "A custom identifier that represent the service that\napplied this metadata." } } }, "invocation": { "type": "object", "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`skill_invocation`", "enum": [ "skill_invocation" ] }, "id": { "type": "string", "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." } } }, "duration": { "type": "integer", "description": "An total duration in seconds of the timeline." }, "entries": { "type": "array", "description": "A list of entries on the timeline.", "items": { "type": "object", "description": "An single item that's placed on multiple items on the timeline.", "properties": { "text": { "type": "string", "description": "The text of the entry. This would be the display\nname for an item being placed on the timeline, for example the name\nof the person who was detected in a video." }, "appears": { "type": "array", "description": "Defines a list of timestamps for when this item should appear on the\ntimeline.", "required": [ "start", "end" ], "items": { "type": "object", "description": "The timestamp for an entry.", "properties": { "start": { "type": "integer", "description": "The time in seconds when an\nentry should start appearing on a timeline." }, "end": { "type": "integer", "description": "The time in seconds when an\nentry should stop appearing on a timeline." } } } }, "image_url": { "type": "string", "description": "The image to show on a for an entry that appears\non a timeline. This image URL is required for every entry.\n\nThe image will be shown in a\nlist of items (for example faces), and clicking\nthe image will show the user where that entry\nappears during the duration of this entry." } } } } } }, "TranscriptSkillCard": { "type": "object", "title": "Transcript Skill Card", "description": "A Box Skill metadata card that adds a transcript to a file.", "required": [ "type", "skill_card_type", "skill", "invocation", "entries" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The optional date and time this card was created at." }, "type": { "type": "string", "description": "`skill_card`", "enum": [ "skill_card" ] }, "skill_card_type": { "type": "string", "description": "`transcript`", "enum": [ "transcript" ] }, "skill_card_title": { "type": "object", "description": "The title of the card.", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "An optional identifier for the title." }, "message": { "type": "string", "description": "The actual title to show in the UI." } } }, "skill": { "type": "object", "description": "The service that applied this metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`service`", "enum": [ "service" ] }, "id": { "type": "string", "description": "A custom identifier that represent the service that\napplied this metadata." } } }, "invocation": { "type": "object", "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`skill_invocation`", "enum": [ "skill_invocation" ] }, "id": { "type": "string", "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." } } }, "duration": { "type": "integer", "description": "An optional total duration in seconds.\n\nUsed with a `skill_card_type` of `transcript` or\n`timeline`." }, "entries": { "type": "array", "description": "An list of entries for the card. This represents the individual entries of\nthe transcription.", "items": { "type": "object", "description": "An entry in the `entries` attribute of a metadata card", "properties": { "text": { "type": "string", "description": "The text of the entry. This would be the transcribed text assigned\nto the entry on the timeline." }, "appears": { "type": "array", "description": "Defines when a transcribed bit of text appears. This only includes a\nstart time and no end time.", "required": [ "start" ], "items": { "type": "object", "description": "The timestamp for an entry.", "properties": { "start": { "type": "integer", "description": "The time in seconds when an\nentry should start appearing on a timeline." } } } } } } } } }, "StatusSkillCard": { "type": "object", "title": "Status Skill Card", "description": "A Box Skill metadata card that puts a status message in the metadata sidebar.", "required": [ "type", "skill_card_type", "skill", "invocation", "status" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The optional date and time this card was created at." }, "type": { "type": "string", "description": "`skill_card`", "enum": [ "skill_card" ] }, "skill_card_type": { "type": "string", "description": "`status`", "enum": [ "status" ] }, "skill_card_title": { "type": "object", "description": "The title of the card.", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "An optional identifier for the title." }, "message": { "type": "string", "description": "The actual title to show in the UI." } } }, "status": { "type": "object", "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.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "A code for the status of this Skill invocation. By\ndefault each of these will have their own accompanied\nmessages. These can be adjusted by setting the `message`\nvalue on this object.", "enum": [ "invoked", "processing", "success", "transient_failure", "permanent_failure" ] }, "message": { "type": "string", "description": "A custom message that can be provided with this status.\nThis will be shown in the web app to the end user." } } }, "skill": { "type": "object", "description": "The service that applied this metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`service`", "enum": [ "service" ] }, "id": { "type": "string", "description": "A custom identifier that represent the service that\napplied this metadata." } } }, "invocation": { "type": "object", "description": "The invocation of this service, used to track\nwhich instance of a service applied the metadata.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "`skill_invocation`", "enum": [ "skill_invocation" ] }, "id": { "type": "string", "description": "A custom identifier that represent the instance of\nthe service that applied this metadata. For example,\nif your `image-recognition-service` runs on multiple\nnodes, this field can be used to identify the ID of\nthe node that was used to apply the metadata." } } } } }, "Watermark": { "title": "Watermark", "type": "object", "description": "A watermark is a semi-transparent overlay on an embedded file\npreview that displays a viewer's email address or user ID\nand the time of access over a file's content", "properties": { "watermark": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When this watermark was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When this task was modified" } } } } }, "FileRequest": { "title": "File Request", "type": "object", "description": "A standard representation of a file request, as returned\nfrom any file request API endpoints by default.", "properties": { "id": { "type": "string", "description": "The unique identifier for this file request.", "readOnly": true }, "type": { "type": "string", "description": "`file-request`", "enum": [ "file-request" ], "readOnly": true }, "title": { "type": "string", "description": "The title of file request. This is shown\nin the Box UI to users uploading files.\n\nThis defaults to title of the file request that was\ncopied to create this file request." }, "description": { "type": "string", "description": "The optional description of this file request. This is\nshown in the Box UI to users uploading files.\n\nThis defaults to description of the file request that was\ncopied to create this file request." }, "status": { "type": "string", "description": "The status of the file request. This defaults\nto `active`.\n\nWhen the status is set to `inactive`, the file request\nwill no longer accept new submissions, and any visitor\nto the file request URL will receive a `HTTP 404` status\ncode.\n\nThis defaults to status of file request that was\ncopied to create this file request.", "enum": [ "active", "inactive" ] }, "is_email_required": { "type": "boolean", "description": "Whether a file request submitter is required to provide\ntheir email address.\n\nWhen this setting is set to true, the Box UI will show\nan email field on the file request form.\n\nThis defaults to setting of file request that was\ncopied to create this file request." }, "is_description_required": { "type": "boolean", "description": "Whether a file request submitter is required to provide\na description of the files they are submitting.\n\nWhen this setting is set to true, the Box UI will show\na description field on the file request form.\n\nThis defaults to setting of file request that was\ncopied to create this file request." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date after which a file request will no longer accept new\nsubmissions.\n\nAfter this date, the `status` will automatically be set to\n`inactive`." }, "folder": { "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "description": "The folder that this file request is associated with.\n\nFiles submitted through the file request form will be\nuploaded to this folder." } ] }, "url": { "type": "string", "description": "The generated URL for this file request. This URL can be shared\nwith users to let them upload files to the associated folder.", "readOnly": true }, "etag": { "type": "string", "description": "The HTTP `etag` of this file. This can be used in combination with\nthe `If-Match` header when updating a file request. By providing that\nheader, a change will only be performed on the file request if the `etag`\non the file request still matches the `etag` provided in the `If-Match`\nheader." }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created this file request." } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the file request was created." }, "updated_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who last modified this file request." }, {} ] }, "updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the file request was last updated." } } }, "FileRequestUpdateRequest": { "title": "File Request (Update)", "type": "object", "description": "The request body to update a file request.", "properties": { "title": { "type": "string", "description": "An optional new title for the file request. This can be\nused to change the title of the file request.\n\nThis will default to the value on the existing file request." }, "description": { "type": "string", "description": "An optional new description for the file request. This can be\nused to change the description of the file request.\n\nThis will default to the value on the existing file request." }, "status": { "type": "string", "description": "An optional new status of the file request.\n\nWhen the status is set to `inactive`, the file request\nwill no longer accept new submissions, and any visitor\nto the file request URL will receive a `HTTP 404` status\ncode.\n\nThis will default to the value on the existing file request.", "enum": [ "active", "inactive" ] }, "is_email_required": { "type": "boolean", "description": "Whether a file request submitter is required to provide\ntheir email address.\n\nWhen this setting is set to true, the Box UI will show\nan email field on the file request form.\n\nThis will default to the value on the existing file request." }, "is_description_required": { "type": "boolean", "description": "Whether a file request submitter is required to provide\na description of the files they are submitting.\n\nWhen this setting is set to true, the Box UI will show\na description field on the file request form.\n\nThis will default to the value on the existing file request." }, "expires_at": { "type": "string", "format": "date-time", "description": "The date after which a file request will no longer accept new\nsubmissions.\n\nAfter this date, the `status` will automatically be set to\n`inactive`.\n\nThis will default to the value on the existing file request." } } }, "FileRequestCopyRequest": { "title": "File Request (Copy)", "type": "object", "description": "The request body to copy a file request.", "required": [ "folder" ], "allOf": [ { "$ref": "#/definitions/FileRequestUpdateRequest" }, { "properties": { "folder": { "type": "object", "description": "The folder to associate the new file request to.", "required": [ "id" ], "properties": { "type": { "type": "string", "description": "`folder`", "enum": [ "folder" ] }, "id": { "type": "string", "description": "The ID of the folder to associate the new\nfile request to." } } } } } ] }, "Folder": { "title": "Folder", "type": "object", "x-box-variant": "standard", "description": "A standard representation of a folder, as returned from any\nfolder API endpoints by default", "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder." }, "modified_at": { "type": "string", "format": "date-time", "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder." }, "description": { "allOf": [ { "type": "string", "description": "The optional description of this folder", "maxLength": 256 }, {} ] }, "size": { "type": "integer", "format": "int64", "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large." }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "description": "The parent folders for this item", "items": { "$ref": "#/definitions/Folder--Mini" } } } }, { "description": "The tree of folders that this folder is contained in,\nstarting at the root." }, {} ] }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created this folder" }, {} ] }, "modified_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who last modified this folder." }, {} ] }, "trashed_at": { "type": "string", "format": "date-time", "description": "The time at which this folder was put in the trash." }, "purged_at": { "type": "string", "format": "date-time", "description": "The time at which this folder is expected to be purged\nfrom the trash." }, "content_created_at": { "type": "string", "format": "date-time", "description": "The date and time at which this folder was originally\ncreated." }, "content_modified_at": { "type": "string", "format": "date-time", "description": "The date and time at which this folder was last updated." }, "expires_at": { "type": "string", "format": "date-time", "description": "The time and which the folder will be automatically be deleted." }, "owned_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who owns this folder." }, {} ] }, "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\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.", "type": "object", "properties": { "url": { "type": "string", "format": "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\ncan be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url`\nhas been set for this shared link." }, "download_url": { "type": "string", "format": "url", "x-box-premium-feature": true, "description": "A URL that can be used to download the file. This URL can be used in\na browser to download the file. This URL includes the file\nextension so that the file will be saved with the right file type.\n\nThis property will be `null` for folders." }, "vanity_url": { "type": "string", "format": "url", "description": "The \"Custom URL\" that can also be used to preview the item on Box. Custom\nURLs can only be created or modified in the Box Web application." }, "vanity_name": { "type": "string", "description": "The custom name of a shared link, as used in the `vanity_url` field." }, "access": { "type": "string", "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin.", "enum": [ "open", "company", "collaborators" ] }, "effective_access": { "type": "string", "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.", "enum": [ "open", "company", "collaborators" ] }, "effective_permission": { "type": "string", "description": "The effective permissions for this shared link.", "enum": [ "can_download", "can_preview" ] }, "unshared_at": { "type": "string", "format": "date-time", "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts." }, "is_password_enabled": { "type": "boolean", "description": "Defines if the shared link requires a password to access the item." }, "permissions": { "type": "object", "description": "Defines if this link allows a user to preview and download an item.", "properties": { "can_download": { "type": "boolean", "description": "Defines if the shared link allows for the item to be downloaded. For\nshared 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\nset to `open` or `company`, not `collaborators`." }, "can_preview": { "type": "boolean", "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\napplies to any items in the folder." } } }, "download_count": { "type": "integer", "description": "The number of times this item has been downloaded." }, "preview_count": { "type": "integer", "description": "The number of times this item has been previewed." } } }, { "description": "The shared link for this folder. This will be\n`null` if no shared link has been created for this\nfolder." } ] }, "folder_upload_email": { "type": "object", "properties": { "access": { "type": "string", "enum": [ "open", "collaborators" ], "description": "When this parameter has been set, users can email files\nto the email address that has been automatically\ncreated for this folder.\n\nTo create an email address, set this property either when\ncreating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email\naddresses for collaborators will be accepted. This includes\nany email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email\naddress." }, "email": { "description": "The optional upload email address for this folder.", "type": "string", "format": "email" } } }, "parent": { "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." } ] }, "item_status": { "type": "string", "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.", "enum": [ "active", "trashed", "deleted" ] }, "item_collection": { "allOf": [ { "$ref": "#/definitions/Items" }, { "description": "A page of the items that are in the folder.\n\nThis field can only be requested when querying a folder's\ninformation, not when querying a folder's items." }, {} ] } } } ] }, "Items": { "title": "Items", "type": "object", "description": "A list of files, folders, and web links in\ntheir mini representation.", "allOf": [ { "type": "object", "description": "The part of an API response that describes pagination", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the entire collection.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "description": "The items in this collection.", "type": "array", "items": { "$ref": "#/definitions/File--Mini" } } } } ] }, "FolderLocks": { "title": "Folder Locks", "type": "object", "description": "A list of folder locks", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/FolderLock" } } } } ] }, "FolderLock": { "title": "Folder Lock", "type": "object", "description": "Folder locks define access restrictions placed by folder owners\nto prevent specific folders from being moved or deleted.", "properties": { "folder": { "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "description": "The folder that the lock applies to." } ] }, "id": { "type": "string", "description": "The unique identifier for this folder lock." }, "type": { "type": "string", "description": "The object type, always `folder_lock`." }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Base" }, { "description": "The user or group that created the lock." } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the folder lock object was created." }, "locked_operations": { "type": "object", "description": "The operations that have been locked. Currently the `move`\nand `delete` operations cannot be locked separately, and both need to be\nset to `true`.\n", "properties": { "move": { "type": "boolean", "description": "Whether moving the folder is restricted." }, "delete": { "type": "boolean", "description": "Whether deleting the folder is restricted." } } }, "lock_type": { "type": "string", "description": "The lock type, always `freeze`." } } }, "MetadataTemplates": { "title": "Metadata templates", "type": "object", "description": "A list of metadata templates", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/MetadataTemplate" } } } } ] }, "ClassificationTemplate": { "title": "Classification Template", "type": "object", "description": "A metadata template that holds the security classifications\ndefined by an enterprise.", "properties": { "id": { "type": "string", "description": "The ID of the classification template." }, "type": { "type": "string", "description": "`metadata_template`", "enum": [ "metadata_template" ] }, "scope": { "type": "string", "description": "The scope of the classification template. This is in the format\n`enterprise_{id}` where the `id` is the enterprise ID." }, "templateKey": { "type": "string", "description": "`securityClassification-6VMVochwUWo`", "enum": [ "securityClassification-6VMVochwUWo" ] }, "displayName": { "type": "string", "description": "The name of this template as shown in web and mobile interfaces.", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "description": "This template is always available in web and mobile interfaces." }, "copyInstanceOnItemCopy": { "type": "boolean", "description": "Classifications are always copied along when the file or folder is\ncopied." }, "fields": { "type": "array", "maxItems": 1, "minItems": 1, "description": "A list of fields for this classification template. This includes\nonly one field, the `Box__Security__Classification__Key`, which defines\nthe different classifications available in this enterprise.", "items": { "type": "object", "description": "The metadata template field that represents the available\nclassifications.", "properties": { "id": { "type": "string", "description": "The unique ID of the field." }, "type": { "type": "string", "description": "`enum`", "enum": [ "enum" ] }, "key": { "type": "string", "description": "`Box__Security__Classification__Key`", "enum": [ "Box__Security__Classification__Key" ] }, "displayName": { "type": "string", "description": "`Classification`", "enum": [ "Classification" ] }, "hidden": { "type": "boolean", "description": "Classifications are always visible to web and mobile users." }, "options": { "type": "array", "description": "A list of classifications available in this enterprise.", "minItems": 1, "items": { "type": "object", "description": "A single classification available in this enterprise.", "properties": { "id": { "type": "string", "description": "The unique ID of this classification." }, "key": { "type": "string", "description": "The display name and key for this classification." }, "staticConfig": { "type": "object", "description": "Additional information about the classification.", "properties": { "classification": { "type": "object", "description": "Additional information about the classification.\n\nThis is not an exclusive list of properties, and\nmore object fields might be returned. These fields\nare used for internal Box Shield and Box Governance\npurposes and no additional value must be derived from\nthese fields.", "properties": { "classificationDefinition": { "type": "string", "description": "A longer description of the classification." }, "colorID": { "type": "number", "description": "An internal Box identifier used to assign a color to\na classification label.\n\nMapping between a `colorID` and a color may change\nwithout notice. Currently, the color mappings are as\nfollows.\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" } } } } } } } } } } } } }, "MetadataTemplate": { "title": "Metadata template", "type": "object", "description": "A template for metadata that can be applied to files and folders", "properties": { "id": { "type": "string", "description": "The ID of the metadata template." }, "type": { "type": "string", "description": "`metadata_template`", "enum": [ "metadata_template" ] }, "scope": { "type": "string", "description": "The scope of the metadata template can either be `global` or\n`enterprise_*`. The `global` scope is used for templates that are\navailable to any Box enterprise. The `enterprise_*` scope represents\ntemplates that have been created within a specific enterprise, where `*`\nwill be the ID of that enterprise." }, "templateKey": { "type": "string", "description": "A unique identifier for the template. This identifier is unique across\nthe `scope` of the enterprise to which the metadata template is being\napplied, yet is not necessarily unique across different enterprises.", "maxLength": 64, "pattern": "^[a-zA-Z_][-a-zA-Z0-9_]*$" }, "displayName": { "type": "string", "description": "The display name of the template. This can be seen in the Box web app\nand mobile apps.", "maxLength": 4096 }, "hidden": { "type": "boolean", "description": "Defines if this template is visible in the Box web app UI, or if\nit is purely intended for usage through the API." }, "fields": { "type": "array", "description": "An ordered list of template fields which are part of the template. Each\nfield can be a regular text field, date field, number field, as well as a\nsingle or multi-select list.", "items": { "type": "object", "description": "A field within a metadata template. Fields can be a basic text, date, or\nnumber field, or a list of options.", "allOf": [ { "title": "Metadata Field (Write)", "description": "A field within a metadata template. Fields can be a basic text, date, or\nnumber field, or a list of options.", "required": [ "type", "key", "displayName" ], "type": "object", "properties": { "type": { "type": "string", "description": "The type of field. The basic fields are a `string` field for text, a\n`float` field for numbers, and a `date` fields to present the user with a\ndate-time picker.\n\nAdditionally, metadata templates support an `enum` field for a basic list\nof items, and ` multiSelect` field for a similar list of items where the\nuser can select more than one value.", "enum": [ "string", "float", "date", "enum", "multiSelect" ] }, "key": { "type": "string", "description": "A unique identifier for the field. The identifier must\nbe unique within the template to which it belongs.", "maxLength": 256 }, "displayName": { "type": "string", "description": "The display name of the field as it is shown to the user in the web and\nmobile apps.", "maxLength": 4096 }, "description": { "type": "string", "description": "A description of the field. This is not shown to the user.", "maxLength": 4096 }, "hidden": { "type": "boolean", "description": "Whether this field is hidden in the UI for the user and can only be set\nthrough the API instead." }, "options": { "description": "A list of options for this field. This is used in combination with the\n`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`.\nOptions represent the value(s) a user can select for the field either through\nthe UI or through the API.", "required": [ "key" ], "properties": { "key": { "description": "The text value of the option. This represents both the display name of the\noption and the internal key used when updating templates.", "type": "string" } } } } } }, { "properties": { "id": { "type": "string", "description": "The unique ID of the metadata template field." }, "options": { "description": "A list of options for this field. This is used in combination\nwith 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\n`multiSelect`. Options represent the value(s) a user can\nselect 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`.\nOptions represent the value(s) a user can select for the field either through\nthe UI or through the API.", "required": [ "key" ], "properties": { "key": { "description": "The text value of the option. This represents both the display name of the\noption and the internal key used when updating templates.", "type": "string" } } }, { "properties": { "id": { "type": "string", "description": "The internal unique identifier of the the option." } } } ] } } } } ] } }, "copyInstanceOnItemCopy": { "type": "boolean", "description": "Whether or not to include the metadata when a file or folder is copied." } } }, "MetadataCascadePolicies": { "title": "Metadata cascade policies", "type": "object", "description": "A list of metadata cascade policies.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/MetadataCascadePolicy" } } } } ] }, "MetadataCascadePolicy": { "title": "Metadata cascade policy", "type": "object", "description": "A metadata cascade policy automatically applies a metadata template instance\nto all the files and folders within the targeted folder.", "properties": { "id": { "type": "string", "description": "The ID of the metadata cascade policy object" }, "type": { "type": "string", "description": "`metadata_cascade_policy`", "enum": [ "metadata_cascade_policy" ] }, "owner_enterprise": { "type": "object", "description": "The enterprise that owns this policy.", "properties": { "type": { "type": "string", "description": "`enterprise`", "enum": [ "enterprise" ] }, "id": { "type": "string", "description": "The ID of the enterprise that owns the policy." } } }, "parent": { "type": "object", "description": "Represent the folder the policy is applied to.", "properties": { "type": { "type": "string", "description": "`folder`", "enum": [ "folder" ] }, "id": { "type": "string", "description": "The ID of the folder the policy is applied to." } } }, "scope": { "type": "string", "description": "The scope of the of the template that is cascaded down to the folder's\nchildren.", "enum": [ "global", "enterprise_*" ] }, "templateKey": { "type": "string", "description": "The key of the template that is cascaded down to the folder's\nchildren.\n\nIn many cases the template key is automatically derived\nof its display name, for example `Contract Template` would\nbecome `contractTemplate`. In some cases the creator of the\ntemplate will have provided its own template key.\n\nPlease [list the templates for an enterprise][list], or\nget all instances on a [file][file] or [folder][folder]\nto inspect a template's key.\n\n[list]: e://get-metadata-templates-enterprise\n[file]: e://get-files-id-metadata\n[folder]: e://get-folders-id-metadata" } } }, "MetadataQueryResults": { "title": "Metadata query search results", "type": "object", "description": "A page of files and folders that matched the metadata query.", "properties": { "entries": { "description": "The mini representation of the files and folders that match the search\nterms.\n\nBy default, this endpoint returns only the most basic info about the\nitems. To get additional fields for each item, including any of the\nmetadata, use the `fields` attribute in the query.", "type": "array", "x-box-resource-variant": 1, "items": { "$ref": "#/definitions/File" } }, "limit": { "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", "default": 100, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string" } } }, "MetadataQuery": { "title": "Metadata query search request", "type": "object", "description": "Create a search using SQL-like syntax to return items that match specific\nmetadata.", "required": [ "from", "ancestor_folder_id" ], "properties": { "from": { "type": "string", "description": "Specifies the template used in the query. Must be in the form\n`scope.templateKey`. Not all templates can be used in this field,\nmost notably the built-in, Box-provided classification templates\ncan not be used in a query." }, "query": { "type": "string", "description": "The query to perform. A query is a logical expression that is very similar\nto a SQL `SELECT` statement. Values in the search query can be turned into\nparameters specified in the `query_param` arguments list to prevent having\nto manually insert search values into the query string.\n\nFor example, a value of `:amount` would represent the `amount` value in\n`query_params` object." }, "query_params": { "type": "object", "description": "Set of arguments corresponding to the parameters specified in the\n`query`. The type of each parameter used in the `query_params` must match\nthe type of the corresponding metadata template field.", "additionalProperties": { "type": "string", "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\nmetadata template field.", "x-box-example-key": "amount" } }, "ancestor_folder_id": { "type": "string", "description": "The ID of the folder that you are restricting the query to. A\nvalue of zero will return results from all folders you have access\nto. A non-zero value will only return results found in the folder\ncorresponding to the ID or in any of its subfolders." }, "order_by": { "type": "array", "description": "A list of template fields and directions to sort the metadata query\nresults by.\n\nThe ordering `direction` must be the same for each item in the array.", "items": { "type": "object", "description": "An object representing one of the metadata template fields to sort the\nmetadata query results by.", "properties": { "field_key": { "type": "string", "description": "The metadata template field to order by.\n\nThe `field_key` represents the `key` value of a field from the\nmetadata template being searched for." }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending.\n\nThe `ordering` direction must be the same for each item in the\narray.", "enum": [ "ASC", "DESC", "asc", "desc" ] } } } }, "limit": { "type": "integer", "description": "A value between 0 and 100 that indicates the maximum number of results\nto return for a single request. This only specifies a maximum\nboundary and will not guarantee the minimum number of results\nreturned.", "default": 100, "minimum": 0, "maximum": 100 }, "marker": { "type": "string", "description": "Marker to use for requesting the next page." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "By default, this endpoint returns only the most basic info about the items for\nwhich the query matches. This attribute can be used to specify a list of\nadditional attributes to return for any item, including its metadata.\n\nThis attribute takes a list of item fields, metadata template identifiers,\nor metadata template field identifiers.\n\nFor example:\n\n* `created_by` will add the details of the user who created the item to\nthe response.\n* `metadata..` will return the mini-representation\nof the metadata instance identified by the `scope` and `templateKey`.\n* `metadata...` will return all the mini-representation\nof the metadata instance identified by the `scope` and `templateKey` plus\nthe field specified by the `field` name. Multiple fields for the same\n`scope` and `templateKey` can be defined." } } }, "MetadataQueryIndices": { "title": "Metadata query indices", "type": "object", "description": "A collection of metadata query indices.", "properties": { "entries": { "description": "A collection of metadata query indices.", "type": "array", "items": { "$ref": "#/definitions/MetadataQueryIndex" } }, "limit": { "description": "The limit that was used for this request.", "default": 100, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "string" } } }, "Comment": { "title": "Comment", "type": "object", "description": "Standard representation of a comment.", "x-box-variant": "standard", "allOf": [ { "$ref": "#/definitions/Comment--Base" }, { "properties": { "is_reply_comment": { "type": "boolean", "description": "Whether or not this comment is a reply to another\ncomment" }, "message": { "type": "string", "description": "The text of the comment, as provided by the user" }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "A mini user object representing the author of the\ncomment" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time this comment was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "The time this comment was last modified" }, "item": { "allOf": [ { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this object" }, "type": { "type": "string", "description": "The type for this object" } } }, { "description": "The file this comment was placed on" } ] } } } ] }, "Collaboration": { "title": "Collaboration", "type": "object", "description": "Collaborations define access permissions for users and groups to files and\nfolders, similar to access control lists. A collaboration object grants a\nuser or group access to a file or folder with permissions defined by a\nspecific role.", "properties": { "id": { "type": "string", "description": "The unique identifier for this collaboration." }, "type": { "type": "string", "description": "`collaboration`", "enum": [ "collaboration" ] }, "item": { "allOf": [ { "$ref": "#/definitions/File" }, { "description": "The file or folder to which access is granted. The field is\n`null` when the collaboration `status` is `pending`." } ] }, "accessible_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user or group that is granted access" } ] }, "invite_email": { "type": "string", "description": "The email address used to ****** an unregistered collaborator, if\nthey are not a registered user." }, "role": { "type": "string", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner", "owner" ], "description": "The level of access granted." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the collaboration will expire, or `null` if no expiration\ndate is set." }, "status": { "type": "string", "enum": [ "accepted", "pending", "rejected" ], "description": "The status of the collaboration invitation." }, "acknowledged_at": { "type": "string", "format": "date-time", "description": "When the `status` of the collaboration object changed to\n`accepted` or `rejected`" }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created the collaboration object" }, {} ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the collaboration object was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the collaboration object was last modified" }, "acceptance_requirements_status": { "type": "object", "properties": { "terms_of_service_requirement": { "type": "object", "properties": { "is_accepted": { "type": "boolean", "description": "Whether or not the terms of service have been accepted. The\nfield is `null` when there is no terms of service required." }, "terms_of_service": { "allOf": [ { "$ref": "#/definitions/TermsOfService--Mini" }, { "description": "The terms of service that must be accepted before the\ncollaboration can be accepted. The field is `null` when\nthere is no terms of service required." } ] } } }, "strong_password_requirement": { "type": "object", "properties": { "enterprise_has_strong_password_required_for_external_users": { "type": "boolean", "description": "Whether or not the enterprise that owns the content requires\na strong password to collaborate on the content." }, "user_has_strong_password": { "type": "boolean", "description": "Whether or not the user has a strong password set for their\naccount. The field is `null` when a strong password is not\nrequired." } } }, "two_factor_authentication_requirement": { "type": "object", "properties": { "enterprise_has_two_factor_auth_enabled": { "type": "boolean", "description": "Whether or not the enterprise that owns the content requires\ntwo-factor authentication to be enabled in order to\ncollaborate on the content." }, "user_has_two_factor_authentication_enabled": { "type": "boolean", "description": "Whether or not the user has two-factor authentication\nenabled. The field is `null` when two-factor\nauthentication is not required." } } } } } } }, "SearchResults": { "title": "Search Results", "type": "object", "description": "A list of files, folders and web links that matched the search query.", "allOf": [ { "type": "object", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the search results.\nThe total number of entries in the collection may be less than\n`total_count`.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter used.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "description": "The search results for the query provided.", "type": "array", "items": { "$ref": "#/definitions/File" } } } } ] }, "SearchResultsWithSharedLinks": { "title": "Search Results (including Shared Links)", "type": "object", "description": "A list of files, folders and web links that matched the search query,\nincluding the additional information about any shared links through\nwhich the item has been shared with the user.\n\nThis response format is only returned when the `include_recent_shared_links`\nquery parameter has been set to `true`.", "allOf": [ { "type": "object", "properties": { "total_count": { "description": "One greater than the offset of the last entry in the search results.\nThe total number of entries in the collection may be less than\n`total_count`.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for this search. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter used.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "description": "The search results for the query provided, including the\nadditional information about any shared links through\nwhich the item has been shared with the user.", "type": "array", "items": { "$ref": "#/definitions/SearchResultWithSharedLink" } } } } ] }, "Task": { "title": "Task", "type": "object", "description": "A task allows for file-centric workflows within Box. Users can\ncreate tasks on files and assign them to other users for them to complete the\ntasks.", "properties": { "id": { "type": "string", "description": "The unique identifier for this task" }, "type": { "type": "string", "description": "`task`", "enum": [ "task" ] }, "item": { "allOf": [ { "$ref": "#/definitions/File--Mini" }, { "description": "The file associated with the task" } ] }, "due_at": { "type": "string", "format": "date-time", "description": "When the task is due" }, "action": { "type": "string", "description": "The type of task the task assignee will be prompted to\nperform.", "enum": [ "review", "complete" ] }, "message": { "type": "string", "description": "A message that will be included with the task" }, "task_assignment_collection": { "allOf": [ { "$ref": "#/definitions/TaskAssignments" }, { "description": "A collection of task assignment objects\nassociated with the task" } ] }, "is_completed": { "type": "boolean", "description": "Whether the task has been completed" }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created the task" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the task object was created" }, "completion_rule": { "type": "string", "description": "Defines which assignees need to complete this task before the task\nis considered completed.\n\n* `all_assignees` requires all assignees to review or\napprove the the task in order for it to be considered completed.\n* `any_assignee` accepts any one assignee to review or\napprove the the task in order for it to be considered completed.", "enum": [ "all_assignees", "any_assignee" ] } } }, "TaskAssignments": { "title": "Task assignments", "type": "object", "description": "A list of task assignments", "properties": { "total_count": { "description": "The total number of items in this collection.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/TaskAssignment" } } } }, "TaskAssignment": { "title": "Task assignment", "type": "object", "description": "A task assignment defines which task is assigned to which user to complete.", "properties": { "id": { "type": "string", "description": "The unique identifier for this task assignment" }, "type": { "type": "string", "description": "`task_assignment`", "enum": [ "task_assignment" ] }, "item": { "allOf": [ { "$ref": "#/definitions/File--Mini" }, { "description": "The file that the task has been assigned to." } ] }, "assigned_to": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user that the task has been assigned to." } ] }, "message": { "type": "string", "description": "A message that will is included with the task\nassignment. This is visible to the assigned user in the web and mobile\nUI." }, "completed_at": { "type": "string", "format": "date-time", "description": "The date at which this task assignment was\ncompleted. This will be `null` if the task is not completed yet." }, "assigned_at": { "type": "string", "format": "date-time", "description": "The date at which this task was assigned to the user." }, "reminded_at": { "type": "string", "format": "date-time", "description": "The date at which the assigned user was reminded of this task\nassignment." }, "resolution_state": { "type": "string", "description": "The current state of the assignment. The available states depend on\nthe `action` value of the task object.", "enum": [ "completed", "incomplete", "approved", "rejected" ] }, "assigned_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who assigned this task." } ] } } }, "WebLink": { "title": "Web link", "type": "object", "x-box-variant": "standard", "description": "Web links are objects that point to URLs. These objects\nare also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects,\nthey will also support most actions that apply to regular files.", "allOf": [ { "$ref": "#/definitions/WebLink--Mini" }, { "properties": { "parent": { "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "description": "The parent object the web link belongs to" } ] }, "description": { "type": "string", "description": "The description accompanying the web link. This is\nvisible within the Box web application." }, "path_collection": { "allOf": [ { "title": "Path collection", "description": "A list of parent folders for an item.", "type": "object", "properties": { "total_count": { "description": "The number of folders in this list.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "description": "The parent folders for this item", "items": { "$ref": "#/definitions/Folder--Mini" } } } }, { "description": "The tree of folders that this web link is contained in,\nstarting at the root." }, {} ] }, "created_at": { "type": "string", "format": "date-time", "description": "When this file was created on Box’s servers." }, "modified_at": { "type": "string", "format": "date-time", "description": "When this file was last updated on the Box\nservers." }, "trashed_at": { "type": "string", "format": "date-time", "description": "When this file was last moved to the trash." }, "purged_at": { "type": "string", "format": "date-time", "description": "When this file will be permanently deleted." }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created this web link" } ] }, "modified_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who last modified this web link" } ] }, "owned_by": { "allOf": [ { "$ref": "#/definitions/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\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.", "type": "object", "properties": { "url": { "type": "string", "format": "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\ncan be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url`\nhas been set for this shared link." }, "download_url": { "type": "string", "format": "url", "x-box-premium-feature": true, "description": "A URL that can be used to download the file. This URL can be used in\na browser to download the file. This URL includes the file\nextension so that the file will be saved with the right file type.\n\nThis property will be `null` for folders." }, "vanity_url": { "type": "string", "format": "url", "description": "The \"Custom URL\" that can also be used to preview the item on Box. Custom\nURLs can only be created or modified in the Box Web application." }, "vanity_name": { "type": "string", "description": "The custom name of a shared link, as used in the `vanity_url` field." }, "access": { "type": "string", "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin.", "enum": [ "open", "company", "collaborators" ] }, "effective_access": { "type": "string", "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.", "enum": [ "open", "company", "collaborators" ] }, "effective_permission": { "type": "string", "description": "The effective permissions for this shared link.", "enum": [ "can_download", "can_preview" ] }, "unshared_at": { "type": "string", "format": "date-time", "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts." }, "is_password_enabled": { "type": "boolean", "description": "Defines if the shared link requires a password to access the item." }, "permissions": { "type": "object", "description": "Defines if this link allows a user to preview and download an item.", "properties": { "can_download": { "type": "boolean", "description": "Defines if the shared link allows for the item to be downloaded. For\nshared 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\nset to `open` or `company`, not `collaborators`." }, "can_preview": { "type": "boolean", "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\napplies to any items in the folder." } } }, "download_count": { "type": "integer", "description": "The number of times this item has been downloaded." }, "preview_count": { "type": "integer", "description": "The number of times this item has been previewed." } } }, { "description": "The shared link object for this item. Will be\n`null` if no shared link has been created." }, {} ] }, "item_status": { "type": "string", "enum": [ "active", "trashed", "deleted" ], "description": "Whether this item is deleted or not. Values include `active`,\n`trashed` if the file has been moved to the trash, and `deleted` if\nthe file has been permanently deleted" } } } ] }, "Users": { "title": "Users", "type": "object", "description": "A list of users.", "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.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/User" } } } } ] }, "User": { "title": "User", "type": "object", "x-box-variant": "standard", "description": "A standard representation of a user, as returned from any\nuser API endpoints by default", "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the user object was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the user object was last modified" }, "language": { "type": "string", "description": "The language of the user, formatted in modified version of the\n[ISO 639-1](/guides/api-calls/language-codes) format." }, "timezone": { "type": "string", "format": "timezone", "description": "The user's timezone" }, "space_amount": { "type": "integer", "format": "int64", "description": "The user’s total available space amount in bytes" }, "space_used": { "type": "integer", "format": "int64", "description": "The amount of space in use by the user" }, "max_upload_size": { "type": "integer", "format": "int64", "description": "The maximum individual file size in bytes the user can have" }, "status": { "type": "string", "enum": [ "active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload" ], "description": "The user's account status" }, "job_title": { "type": "string", "description": "The user’s job title", "maxLength": 100 }, "phone": { "type": "string", "description": "The user’s phone number", "maxLength": 100 }, "address": { "type": "string", "description": "The user’s address", "maxLength": 255 }, "avatar_url": { "type": "string", "description": "URL of the user’s avatar image" }, "notification_email": { "type": "object", "description": "An alternate notification email address to which email\nnotifications are sent. When it's confirmed, this will be\nthe email address to which notifications are sent instead of\nto the primary email address.", "properties": { "email": { "type": "string", "description": "The email address to send the notifications to." }, "is_confirmed": { "type": "boolean", "description": "Specifies if this email address has been confirmed." } } } } } ] }, "EmailAliases": { "title": "Email aliases", "type": "object", "description": "A list of email aliases", "properties": { "total_count": { "description": "The number of email aliases.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/EmailAlias" } } } }, "EmailAlias": { "title": "Email alias", "type": "object", "description": "An email alias for a user.", "properties": { "id": { "type": "string", "description": "The unique identifier for this object" }, "type": { "type": "string", "description": "`email_alias`", "enum": [ "email_alias" ] }, "email": { "type": "string", "description": "The email address" }, "is_confirmed": { "type": "boolean", "description": "Whether the email address has been confirmed" } } }, "GroupMemberships": { "title": "Group memberships", "type": "object", "description": "A list of group memberships.", "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.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/GroupMembership" } } } } ] }, "******": { "title": "******", "type": "object", "description": "An ****** for a user to an enterprise.", "properties": { "id": { "type": "string", "description": "The unique identifier for this ******" }, "type": { "type": "string", "description": "`******`", "enum": [ "******" ] }, "invited_to": { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise." }, "type": { "type": "string", "description": "`enterprise`", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "type": "string" } } }, "actionable_by": { "$ref": "#/definitions/User--Mini" }, "invited_by": { "$ref": "#/definitions/User--Mini" }, "status": { "description": "The status of the ******", "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "When the ****** was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the ****** was modified." } } }, "Groups": { "title": "Groups", "type": "object", "description": "A list of groups.", "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.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/Group--Mini" } } } } ] }, "Group": { "title": "Group", "type": "object", "x-box-variant": "standard", "description": "A standard representation of a group, as returned from any\ngroup API endpoints by default", "allOf": [ { "$ref": "#/definitions/Group--Mini" }, { "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the group object was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the group object was last modified" } } } ] }, "GroupMembership": { "title": "Group membership", "type": "object", "description": "Membership is used to signify that a user is part of a\ngroup.", "properties": { "id": { "type": "string", "description": "The unique identifier for this group membership" }, "type": { "type": "string", "description": "`group_membership`", "enum": [ "group_membership" ] }, "user": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user that the membership applies to" } ] }, "group": { "allOf": [ { "$ref": "#/definitions/Group--Mini" }, { "description": "The group that the membership applies to" } ] }, "role": { "type": "string", "description": "The role of the user in the group.", "enum": [ "member", "admin" ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time this membership was created." }, "modified_at": { "type": "string", "format": "date-time", "description": "The time this membership was last modified." } } }, "Webhooks": { "title": "Webhooks", "type": "object", "description": "A list of webhooks.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/Webhook" } } } } ] }, "Webhook": { "title": "Webhook", "type": "object", "description": "Represents a configured webhook.", "properties": { "id": { "type": "string", "description": "The unique identifier for this webhook." }, "type": { "type": "string", "description": "`webhook`", "enum": [ "webhook" ] }, "target": { "type": "object", "description": "The item that will trigger the webhook", "properties": { "id": { "description": "The ID of the item to trigger a webhook", "type": "string" }, "type": { "description": "The type of item to trigger a webhook", "type": "string", "enum": [ "file", "folder" ] } } }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created the webhook" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "A timestamp identifying the time that\nthe webhook was created." }, "address": { "type": "string", "description": "The URL that is notified by this webhook" }, "triggers": { "type": "array", "description": "An array of event names that this webhook is\nto be triggered for", "items": { "title": "Webhook Trigger", "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" ] } } } }, "RealtimeServers": { "title": "Real-time servers", "type": "object", "description": "A list of real-time servers that can\nbe used for long-polling.", "properties": { "chunk_size": { "description": "The number of items in this response.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/RealtimeServer" } } } }, "Events": { "title": "Events", "type": "object", "description": "A list of event objects", "properties": { "chunk_size": { "description": "The number of events returned in this response.", "type": "integer", "format": "int64" }, "next_stream_position": { "description": "The stream position of the start of the next page (chunk)\nof events.", "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/Event" } } } }, "Collections": { "title": "Collections", "type": "object", "description": "A list of collections", "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.\nThe total number of entries in the collection may be less than\n`total_count`.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "offset": { "description": "The 0-based offset of the first entry in this set. This will be the same\nas the `offset` query parameter.\n\nThis field is only returned for calls that use offset-based pagination.\nFor marker-based paginated APIs, this field will be omitted.", "type": "integer", "format": "int64" }, "order": { "description": "The order by which items are returned.\n\nThis field is only returned for calls that use offset-based pagination.\nFor 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" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "ASC", "DESC" ] } } } } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/Collection" } } } } ] }, "RecentItems": { "title": "Recent items", "type": "object", "description": "A list of recent items.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/RecentItem" } } } } ] }, "RetentionPolicies": { "title": "Retention policies", "type": "object", "description": "A list of retention policies", "properties": { "total_count": { "description": "The number of retention policies.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/RetentionPolicy" } } } }, "RetentionPolicy": { "title": "Retention policy", "type": "object", "x-box-variant": "standard", "description": "A retention policy blocks permanent deletion of content\nfor a specified amount of time. Admins can create retention\npolicies and then later assign them to specific folders\nor their entire enterprise. To use this feature, you must\nhave the manage retention policies scope enabled\nfor your API key via your application management console.", "allOf": [ { "$ref": "#/definitions/RetentionPolicy--Mini" }, { "properties": { "policy_type": { "type": "string", "description": "The type of the retention policy. A retention\npolicy type can either be `finite`, where a\nspecific amount of time to retain the content is known\nupfront, or `indefinite`, where the amount of time\nto retain the content is still unknown.", "enum": [ "finite", "indefinite" ] }, "status": { "type": "string", "description": "The status of the retention policy. The status of\na policy will be `active`, unless explicitly retired by an\nadministrator, in which case the status will be `retired`.\nOnce a policy has been retired, it cannot become\nactive again.", "enum": [ "active", "retired" ] }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "A mini user object representing the user that\ncreated the retention policy" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the retention policy object was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the retention policy object was last modified" } } } ] }, "RetentionPolicyAssignments": { "title": "Retention policy assignments", "type": "object", "description": "A list of retention policy assignments", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/RetentionPolicyAssignment" } } } } ] }, "RetentionPolicyAssignment": { "title": "Retention policy assignment", "type": "object", "description": "The retention policy assignment endpoint provides a way\nfor admins to apply a retention policy on a per-folder\nbasis, or place a blanket policy over the entire\nenterprise.", "properties": { "id": { "type": "string", "description": "The unique identifier for this retention policy assignment" }, "type": { "type": "string", "description": "`retention_policy_assignment`", "enum": [ "retention_policy_assignment" ] }, "retention_policy": { "allOf": [ { "$ref": "#/definitions/RetentionPolicy--Mini" }, { "description": "A mini retention policy object representing the\nretention policy that has been assigned to this content" } ] }, "assigned_to": { "allOf": [ { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this object" }, "type": { "type": "string", "description": "The type for this object" } } }, { "description": "The `type` and `id` of the content that is under\nretention. The `type` can either be `folder` or `\nenterprise`." } ] }, "assigned_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "A mini user object representing the user that\ncreated the retention policy assignment object" } ] }, "assigned_at": { "type": "string", "format": "date-time", "description": "When the retention policy assignment object was\ncreated" } } }, "FileVersionRetentions": { "title": "File version retentions", "type": "object", "description": "A list of file version retentions.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/FileVersionRetention" } } } } ] }, "LegalHoldPolicies": { "title": "Legal hold policies", "type": "object", "description": "A list of legal hold policies.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/LegalHoldPolicy" } } } } ] }, "LegalHoldPolicy": { "title": "Legal hold policy", "type": "object", "x-box-variant": "standard", "description": "Legal Hold Policy information describes the basic\ncharacteristics of the Policy, such as name, description,\nand filter dates.", "allOf": [ { "$ref": "#/definitions/LegalHoldPolicy--Mini" }, { "properties": { "policy_name": { "type": "string", "description": "Name of the legal hold policy.", "maxLength": 254 }, "description": { "type": "string", "description": "Description of the legal hold policy. Optional\nproperty with a 500 character limit.", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "applying", "releasing", "released" ], "description": "* 'active' - the policy is not in a transition state\n* 'applying' - that the policy is in the process of\n being applied\n* 'releasing' - that the process is in the process\n of being released\n* 'released' - the policy is no longer active" }, "assignment_counts": { "type": "object", "description": "Counts of assignments within this a legal hold policy by item type", "properties": { "user": { "type": "integer", "format": "int64", "description": "The number of users this policy is applied to" }, "folder": { "type": "integer", "format": "int64", "description": "The number of folders this policy is applied to" }, "file": { "type": "integer", "format": "int64", "description": "The number of files this policy is applied to" }, "file_version": { "type": "integer", "format": "int64", "description": "The number of file versions this policy is applied to" } } }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created the legal hold policy object" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the legal hold policy object was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the legal hold policy object was modified.\nDoes not update when assignments are added or removed." }, "deleted_at": { "type": "string", "format": "date-time", "description": "When the policy release request was sent. (Because\nit can take time for a policy to fully delete, this\nisn't quite the same time that the policy is fully deleted).\n\nIf `null`, the policy was not deleted." }, "filter_started_at": { "type": "string", "format": "date-time", "description": "User-specified, optional date filter applies to\nCustodian assignments only" }, "filter_ended_at": { "type": "string", "format": "date-time", "description": "User-specified, optional date filter applies to\nCustodian assignments only" }, "release_notes": { "type": "string", "description": "Optional notes about why the policy was created.", "maxLength": 500 } } } ] }, "LegalHoldPolicyAssignments": { "title": "Legal hold policy assignments", "type": "object", "description": "A list of legal hold policies assignments.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/LegalHoldPolicyAssignment--Base" } } } } ] }, "LegalHoldPolicyAssignment": { "title": "Legal hold policy assignment", "type": "object", "description": "Legal Hold Assignments are used to assign Legal Hold\nPolicies to Users, Folders, Files, or File Versions.\n\nCreating a Legal Hold Assignment puts a hold\non the File-Versions that belong to the Assignment's\n'apply-to' entity.", "allOf": [ { "$ref": "#/definitions/LegalHoldPolicyAssignment--Base" }, { "properties": { "legal_hold_policy": { "allOf": [ { "$ref": "#/definitions/LegalHoldPolicy--Mini" }, { "description": "The policy that the legal hold policy assignment\nis part of" } ] }, "assigned_to": { "allOf": [ { "$ref": "#/definitions/File" }, { "description": "The item that the the legal hold policy\nis assigned to. Includes type and ID." } ] }, "assigned_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who created the legal hold policy\nassignment" } ] }, "assigned_at": { "type": "string", "format": "date-time", "description": "When the legal hold policy assignment object was\ncreated" }, "deleted_at": { "type": "string", "format": "date-time", "description": "When the assignment release request was sent.\n(Because it can take time for an assignment to fully\ndelete, this isn't quite the same time that the\nassignment is fully deleted). If null, Assignment\nwas not deleted." } } } ] }, "FileVersionLegalHolds": { "title": "File version legal holds", "type": "object", "description": "A list of file version legal holds.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/FileVersionLegalHold" } } } } ] }, "FileVersionRetention": { "title": "File version retention", "type": "object", "description": "A retention policy blocks permanent deletion of content\nfor a specified amount of time. Admins can apply policies to\nspecified folders, or an entire enterprise. A file version retention\nis a record for a retained file version. To use this feature,\nyou must have the manage retention policies scope enabled for your\nAPI key via your application management console. For more information\nabout retention policies, please visit our help documentation", "properties": { "id": { "type": "string", "description": "The unique identifier for this file version retention." }, "type": { "type": "string", "description": "`file_version_retention`", "enum": [ "file_version_retention" ] }, "file_version": { "allOf": [ { "$ref": "#/definitions/FileVersion--Mini" }, { "description": "The file version this file version retention was\napplied to" } ] }, "file": { "allOf": [ { "$ref": "#/definitions/File--Mini" }, { "description": "The file this file version retention was applied to" } ] }, "applied_at": { "type": "string", "format": "date-time", "description": "When this file version retention object was\ncreated" }, "disposition_at": { "type": "string", "format": "date-time", "description": "When the retention expires on this file\nversion retention" }, "winning_retention_policy": { "allOf": [ { "$ref": "#/definitions/RetentionPolicy--Mini" }, { "description": "The winning retention policy applied to this file\nversion retention. A file version can have multiple\nretention policies applied." } ] } } }, "FileVersionLegalHold": { "title": "File version legal hold", "type": "object", "description": "File-Version-Legal-Hold is an entity representing all\nholds on a File Version.", "properties": { "id": { "type": "string", "description": "The unique identifier for this file version legal hold" }, "type": { "type": "string", "description": "`file_version_legal_hold`", "enum": [ "file_version_legal_hold" ] }, "file_version": { "allOf": [ { "$ref": "#/definitions/FileVersion--Mini" }, { "description": "The file version that is held" } ] }, "file": { "allOf": [ { "$ref": "#/definitions/File--Mini" }, { "description": "The file for the file version held.\nNote that there is no guarantee that the current\nversion of this file is held." } ] }, "legal_hold_policy_assignments": { "description": "List of assignments contributing to this Hold.", "type": "array", "items": { "$ref": "#/definitions/LegalHoldPolicyAssignment" } }, "deleted_at": { "type": "string", "format": "date-time", "description": "Time that this File-Version-Legal-Hold was\ndeleted." } } }, "DevicePinner": { "title": "Device pinner", "type": "object", "description": "Device pins allow enterprises to control what devices can\nuse native Box applications.", "properties": { "id": { "type": "string", "description": "The unique identifier for this device pin." }, "type": { "type": "string", "description": "`device_pinner`", "enum": [ "device_pinner" ] }, "owned_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user that the device pin belongs to" } ] }, "product_name": { "type": "string", "description": "The type of device being pinned" }, "created_at": { "type": "string", "format": "date-time", "description": "The time the device pin was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "The time the device pin was modified" } } }, "DevicePinners": { "title": "Device pinners", "type": "object", "description": "A list of device pins", "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/DevicePinner" } }, "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed.", "default": 100, "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "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", "enum": [ "id" ], "type": "string" }, "direction": { "type": "string", "description": "The direction to order by, either ascending or descending", "enum": [ "asc", "desc" ] } } } } } }, "TermsOfServices": { "title": "Terms of services", "type": "object", "description": "A list of terms of services", "properties": { "total_count": { "description": "The total number of objects.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/TermsOfService" } } } }, "TermsOfService": { "title": "Terms of service", "type": "object", "x-box-variant": "standard", "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", "allOf": [ { "$ref": "#/definitions/TermsOfService--Mini" }, { "properties": { "status": { "description": "Whether these terms are enabled or not", "type": "string", "enum": [ "enabled", "disabled" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise." }, "type": { "type": "string", "description": "`enterprise`", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "type": "string" } } }, { "description": "The enterprise these terms apply to" } ] }, "tos_type": { "description": "Whether to apply these terms to managed users or external users", "type": "string", "enum": [ "managed", "external" ] }, "text": { "description": "The text for your terms and conditions. This text could be\nempty if the `status` is set to `disabled`.", "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "When the legal item was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the legal item was modified." } } } ] }, "TermsOfServiceUserStatuses": { "title": "Terms of service user statuses", "type": "object", "description": "A list of terms of service user statuses", "properties": { "total_count": { "description": "The total number of objects.", "type": "integer", "format": "int64" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/TermsOfServiceUserStatus" } } } }, "TermsOfServiceUserStatus": { "title": "Terms of service user status", "type": "object", "description": "The association between a Terms of Service and a user", "properties": { "id": { "type": "string", "description": "The unique identifier for this terms of service user status" }, "type": { "type": "string", "description": "`terms_of_service_user_status`", "enum": [ "terms_of_service_user_status" ] }, "tos": { "allOf": [ { "$ref": "#/definitions/TermsOfService--Mini" }, { "description": "The terms of service" } ] }, "user": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user" } ] }, "is_accepted": { "type": "boolean", "description": "If the user has accepted the terms of services" }, "created_at": { "type": "string", "format": "date-time", "description": "When the legal item was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "When the legal item was modified." } } }, "CollaborationAllowlistEntries": { "title": "Allowed collaboration domains", "type": "object", "description": "A list of allowed domains for collaboration.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/CollaborationAllowlistEntry" } } } } ] }, "CollaborationAllowlistEntry": { "title": "Allowed collaboration domain", "type": "object", "description": "An entry that describes an approved domain for which users can collaborate\nwith files and folders in your enterprise or vice versa.", "properties": { "id": { "type": "string", "description": "The unique identifier for this entry" }, "type": { "type": "string", "description": "`collaboration_whitelist_entry`", "enum": [ "collaboration_whitelist_entry" ] }, "domain": { "type": "string", "description": "The whitelisted domain" }, "direction": { "type": "string", "description": "The direction of the collaborations to allow.", "enum": [ "inbound", "outbound", "both" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise." }, "type": { "type": "string", "description": "`enterprise`", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "type": "string" } } }, { "description": "The enterprise this list is applied to" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time the entry was created at" } } }, "CollaborationAllowlistExemptTargets": { "title": "Allowed collaboration domains user exemptions", "type": "object", "description": "A list of users that is exempt from any of the restrictions\nimposed by the list of allowed collaboration domains for this enterprise.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/CollaborationAllowlistExemptTarget" } } } } ] }, "CollaborationAllowlistExemptTarget": { "title": "Allowed collaboration domains user exemption", "type": "object", "description": "The user that is exempt from any of the restrictions\nimposed by the list of allowed collaboration domains for this enterprise.", "properties": { "id": { "type": "string", "description": "The unique identifier for this exemption" }, "type": { "type": "string", "description": "`collaboration_whitelist`", "enum": [ "collaboration_whitelist" ] }, "enterprise": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise." }, "type": { "type": "string", "description": "`enterprise`", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "type": "string" } } }, { "description": "The enterprise this entry belongs to" } ] }, "user": { "allOf": [ { "title": "Enterprise", "type": "object", "description": "A representation of a Box enterprise", "properties": { "id": { "type": "string", "description": "The unique identifier for this enterprise." }, "type": { "type": "string", "description": "`enterprise`", "enum": [ "enterprise" ] }, "name": { "description": "The name of the enterprise", "type": "string" } } }, { "description": "The user that has been exempt" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time the entry was created" }, "modified_at": { "type": "string", "format": "date-time", "description": "The time the entry was modified" } } }, "StoragePolicies": { "title": "Storage policies", "type": "object", "description": "A list of storage policies.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/StoragePolicy" } } } } ] }, "StoragePolicy": { "title": "Storage policy", "type": "object", "x-box-variant": "standard", "description": "The Storage Policy object describes the storage zone.", "allOf": [ { "$ref": "#/definitions/StoragePolicy--Mini" }, { "properties": { "name": { "description": "A descriptive name of the region", "type": "string" } } } ] }, "StoragePolicyAssignments": { "title": "Storage policy assignments", "type": "object", "description": "A list of storage policy assignments.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/StoragePolicyAssignment" } } } } ] }, "StoragePolicyAssignment": { "title": "Storage policy assignment", "type": "object", "description": "The assignment of a storage policy to a user or enterprise", "properties": { "storage_policy": { "allOf": [ { "$ref": "#/definitions/StoragePolicy--Mini" }, { "description": "The assigned storage policy" } ] }, "assigned_to": { "allOf": [ { "title": "Reference", "description": "The bare basic reference for an object", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for this object" }, "type": { "type": "string", "description": "The type for this object" } } }, { "description": "The enterprise or use the policy is assigned to" } ] } } }, "ZipDownload": { "title": "Zip download", "type": "object", "x-box-reference-category": "zip_downloads", "description": "Represents a successful request to create a `zip` archive of a list of files\nand folders.", "properties": { "download_url": { "type": "string", "description": "The URL that can be used to download the `zip` archive. A `Get` request to\nthis URL will start streaming the items requested. By default, this URL\nis only valid for a few seconds, until the `exires_at` time, unless a\ndownload is started after which it is valid for the duration of the\ndownload.\n\nIt is important to note that the domain and path of this URL might change\nbetween API calls, and therefore it's important to use this URL as-is." }, "status_url": { "type": "string", "description": "The URL that can be used to get the status of the `zip` archive being\ndownloaded. A `Get` request to this URL will return the number of files\nin the archive as well as the number of items already downloaded or\nskipped. By default, this URL is only valid for a few seconds, until the\n`exires_at` time, unless a download is started after which the URL is\nvalid 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\nbetween API calls, and therefore it's important to use this URL as-is." }, "expires_at": { "type": "string", "format": "date-time", "description": "The time and date when this archive will expire. After this time the\n`status_url` and `download_url` will return an error.\n\nBy default, these URLs are only valid for a few seconds, unless a download\nis started after which the `download_url` is valid for the duration of the\ndownload, and the `status_url` is valid for 12 hours from the start of the\ndownload." }, "name_conflicts": { "type": "array", "description": "A list of conflicts that occurred when trying to create the archive. This\nwould occur when multiple items have been requested with the\nsame name.\n\nTo solve these conflicts, the API will automatically rename an item\nand return a mapping between the original item's name and its new\nname.\n\nFor every conflict, both files will be renamed and therefore this list\nwill always be a multiple of 2.", "items": { "type": "array", "description": "An individual conflict that occurred when trying to create the archive.\nThis includes an array of 2 objects, each containing the original name\nand the renamed filename of a file or folder for which the names\nconflicted.", "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": { "type": "string", "description": "The identifier of the item" }, "type": { "type": "string", "description": "The type of this item", "enum": [ "file", "folder" ] }, "original_name": { "type": "string", "description": "The original name of this item" }, "download_name": { "type": "string", "description": "The new name of this item as it will appear in the\ndownloaded `zip` archive." } } } } } } }, "ZipDownloadRequest": { "title": "Create a `zip` archive", "type": "object", "description": "A request to create a `zip` archive to download", "required": [ "items" ], "properties": { "items": { "type": "array", "description": "A list of items to add to the `zip` archive. These can\nbe folders or files.", "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": { "type": "string", "description": "The type of the item to add to the archive.", "enum": [ "file", "folder." ] }, "id": { "type": "string", "description": "The identifier of the item to add to the archive. When this item is\na folder then this can not be the root folder with ID `0`." } } } }, "download_file_name": { "type": "string", "description": "The optional name of the `zip` archive. This name will be appended by the\n`.zip` file extension, for example `January Financials.zip`." } } }, "ZipDownloadStatus": { "title": "Zip download status", "type": "object", "x-box-reference-category": "zip_downloads", "description": "The status of a `zip` archive being downloaded.", "properties": { "total_file_count": { "type": "integer", "description": "The total number of files in the archive.", "minimum": 0, "maximum": 10000 }, "downloaded_file_count": { "type": "integer", "description": "The number of files that have already been downloaded.", "minimum": 0 }, "skipped_file_count": { "type": "integer", "description": "The number of files that have been skipped as they could not be\ndownloaded. In many cases this is due to permission issues that have\nsurfaced between the creation of the request for the archive and the\narchive being downloaded.", "minimum": 0 }, "skipped_folder_count": { "type": "integer", "description": "The number of folders that have been skipped as they could not be\ndownloaded. In many cases this is due to permission issues that have\nsurfaced between the creation of the request for the archive and the\narchive being downloaded.", "minimum": 0 }, "state": { "type": "string", "description": "The state of the archive being downloaded.", "default": "in_progeress", "enum": [ "in_progress", "failed", "success" ] } } }, "SignRequest": { "title": "Sign Request", "type": "object", "description": "A Sign Request Object", "allOf": [ { "$ref": "#/definitions/SignRequestCreateRequest" }, { "properties": { "type": { "type": "string", "enum": [ "sign-request" ], "description": "object type" }, "signers": { "type": "array", "items": { "$ref": "#/definitions/SignRequestSigner" }, "description": "Array of signers for the sign request" }, "id": { "type": "string", "description": "Sign request ID" }, "prepare_url": { "type": "string", "description": "This URL is returned if `is_document_preparation_needed` is\nset to `true` in the request. It is used to prepare the sign request\nvia UI. The sign request is not sent until preparation is complete." }, "signing_log": { "allOf": [ { "$ref": "#/definitions/File--Mini" }, { "description": "Reference to a file that holds a log of all signer activity for\nthe request" } ] }, "status": { "type": "string", "enum": [ "converting", "created", "sent", "viewed", "signed", "cancelled", "declined", "error_converting", "error_sending", "expired" ], "description": "Describes the status of the sign request" }, "sign_files": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/definitions/File--Mini" } }, "is_ready_for_download": { "type": "boolean", "description": "Indicates whether the `sign_files` documents are processing\nand the PDFs may be out of date. A change to any document\nrequires processing on all `sign_files`. We\nrecommended waiting until processing is finished\n(and this value is true) before downloading the PDFs." } }, "description": "List of files that will be signed, which are copies of the original\nsource files. A new version of these files are created as signers sign\nand can be downloaded at any point in the signing process." }, "auto_expire_at": { "type": "string", "format": "date-time", "description": "Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned." } } } ] }, "SignRequests": { "title": "Box Sign", "type": "object", "description": "A standard representation of a sign request, as returned from any Box Sign\nAPI endpoints by default.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/SignRequest" } } } } ] }, "SignRequestCreateRequest": { "title": "Create a sign request", "type": "object", "description": "A request to create a sign request object", "required": [ "signers", "source_files", "parent_folder" ], "properties": { "is_document_preparation_needed": { "type": "boolean", "description": "Indicates if the sender should receive a `prepare_url` in the response to complete document preparation via UI." }, "are_text_signatures_enabled": { "type": "boolean", "description": "Disables the usage of signatures generated by typing (text)", "default": true }, "email_subject": { "type": "string", "description": "Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used." }, "email_message": { "type": "string", "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." }, "are_reminders_enabled": { "type": "boolean", "description": "Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers." }, "signers": { "type": "array", "items": { "$ref": "#/definitions/SignRequestCreateSigner" }, "description": "Array of signers for the sign request. 35 is the max number of signers permitted." }, "source_files": { "type": "array", "items": { "$ref": "#/definitions/File--Mini" }, "description": "List of files to create a signing document from. This is currently limited to one file. Only the ID and type fields are required for each file." }, "parent_folder": { "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "description": "The destination folder to place final, signed document and signing\nlog. Only `ID` and `type` fields are required. The root folder,\nfolder ID `0`, cannot be used." } ] }, "prefill_tags": { "type": "array", "items": { "$ref": "#/definitions/SignRequestPrefillTag" }, "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." }, "days_valid": { "type": "integer", "description": "Number of days after which this request will automatically expire if not completed", "minimum": 1, "maximum": 730 }, "external_id": { "type": "string", "description": "This can be used to reference an ID in an external system that the sign request is related to." } } }, "Workflows": { "title": "Workflows", "type": "object", "description": "A list of workflows.\n\nYou application must be authorized to use the `Manage Box Relay` application\nscope within the developer console in order to use this resource.", "allOf": [ { "type": "object", "description": "The part of an API response that describes marker\nbased pagination", "properties": { "limit": { "description": "The limit that was used for these entries. This will be the same as the\n`limit` query parameter unless that value exceeded the maximum value\nallowed. The maximum value varies by API.", "type": "integer", "format": "int64" }, "next_marker": { "description": "The marker for the start of the next page of results.", "type": "integer", "format": "int64" }, "prev_marker": { "description": "The marker for the start of the previous page of results.", "type": "integer", "format": "int64" } } }, { "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/Workflow" } } } } ] }, "File--Mini": { "title": "File (Mini)", "type": "object", "x-box-variant": "mini", "description": "A mini representation of a file, used when\nnested under another resource.", "allOf": [ { "$ref": "#/definitions/File--Base" }, { "properties": { "sequence_id": { "allOf": [ { "type": "string", "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." }, {} ] }, "name": { "type": "string", "description": "The name of the file" }, "sha1": { "type": "string", "format": "digest", "description": "The SHA1 hash of the file. This can be used to compare the contents\nof a file on Box with a local file." }, "file_version": { "allOf": [ { "$ref": "#/definitions/FileVersion--Mini" }, { "description": "The information about the current version of the file." } ] } } } ] }, "Folder--Mini": { "title": "Folder (Mini)", "type": "object", "x-box-variant": "mini", "description": "A mini representation of a file version, used when\nnested under another resource.", "allOf": [ { "$ref": "#/definitions/Folder--Base" }, { "properties": { "sequence_id": { "allOf": [ { "type": "string", "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." }, {} ] }, "name": { "type": "string", "description": "The name of the folder." } } } ] }, "User--Mini": { "title": "User (Mini)", "type": "object", "x-box-variant": "mini", "description": "A mini representation of a user, as can be returned when nested within other\nresources.", "allOf": [ { "$ref": "#/definitions/User--Base" }, { "properties": { "name": { "type": "string", "description": "The display name of this user", "maxLength": 50 }, "login": { "type": "string", "format": "email", "description": "The primary email address of this user" } } } ] }, "FileConflict": { "title": "File (Conflict)", "type": "object", "description": "A representation of a file that is used to show", "allOf": [ { "$ref": "#/definitions/File--Mini" }, { "properties": { "sha1": { "type": "string", "description": "The SHA1 hash of the file." }, "file_version": { "$ref": "#/definitions/FileVersion--Mini" } } } ] }, "FileVersion--Mini": { "title": "File version (Mini)", "type": "object", "x-box-variant": "mini", "description": "A mini representation of a file version, used when\nnested within another resource.", "allOf": [ { "$ref": "#/definitions/FileVersion--Base" }, { "properties": { "sha1": { "type": "string", "description": "The SHA1 hash of this version of the file." } } } ] }, "Metadata--Base": { "title": "Metadata instance (Base)", "type": "object", "x-box-variants": [ "base", "standard", "full" ], "x-box-variant": "base", "description": "The base representation of a metadata instance.", "properties": { "$parent": { "type": "string", "description": "The identifier of the item that this metadata instance\nhas been attached to. This combines the `type` and the `id`\nof the parent in the form `{type}_{id}`." }, "$template": { "type": "string", "description": "The name of the template" }, "$scope": { "type": "string", "description": "An ID for the scope in which this template\nhas been applied. This will be `enterprise_{enterprise_id}` for templates\ndefined for use in this enterprise, and `global` for general templates\nthat are available to all enterprises using Box." }, "$version": { "type": "integer", "description": "The version of the metadata instance. This version starts at 0 and\nincreases every time a user-defined property is modified." } } }, "WebLink--Mini": { "title": "Web link (Mini)", "type": "object", "x-box-variant": "mini", "description": "Web links are objects that point to URLs. These objects\nare also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects,\nthey will also support most actions that apply to regular files.", "allOf": [ { "$ref": "#/definitions/WebLink--Base" }, { "properties": { "url": { "type": "string", "description": "The URL this web link points to" }, "sequence_id": { "allOf": [ { "type": "string", "description": "A numeric identifier that represents the most recent user event\nthat has been applied to this item.\n\nThis can be used in combination with the `GET /events`-endpoint\nto filter out user events that would have occurred before this\nidentifier was read.\n\nAn example would be where a Box Drive-like application\nwould fetch an item via the API, and then listen to incoming\nuser events for changes to the item. The application would\nignore any user events where the `sequence_id` in the event\nis smaller than or equal to the `sequence_id` in the originally\nfetched resource." }, {} ] }, "name": { "type": "string", "description": "The name of the web link" } } } ] }, "User--Base": { "title": "User (Base)", "type": "object", "x-box-variants": [ "base", "mini", "standard", "full" ], "x-box-variant": "base", "description": "A mini representation of a user, used when\nnested within another resource.", "properties": { "id": { "type": "string", "description": "The unique identifier for this user" }, "type": { "type": "string", "description": "`user`", "enum": [ "user" ] } } }, "MetadataQueryIndex": { "title": "Metadata query index", "type": "object", "description": "A metadata query index", "properties": { "id": { "type": "string", "description": "The ID of the metadata query index." }, "type": { "type": "string", "description": "Value is always `metadata_query_index`" }, "status": { "type": "string", "description": "The status of the metadata query index", "enum": [ "building", "active", "disabled" ] }, "fields": { "type": "array", "description": "A list of template fields which make up the index.", "items": { "type": "object", "description": "The field which makes up the index.", "allOf": [ { "properties": { "key": { "type": "string", "description": "The metadata template field key." }, "sort_direction": { "type": "string", "description": "The sort direction of the field.", "enum": [ "asc", "desc" ] } } } ] } } } }, "Comment--Base": { "title": "Comment (Base)", "type": "object", "x-box-variants": [ "base", "standard", "full" ], "x-box-variant": "base", "description": "Base representation of a comment.", "properties": { "id": { "type": "string", "description": "The unique identifier for this comment." }, "type": { "type": "string", "description": "`comment`", "enum": [ "comment" ] } } }, "TermsOfService--Mini": { "title": "Terms of service (Mini)", "type": "object", "x-box-variants": [ "mini", "standard" ], "x-box-variant": "mini", "description": "The root-level record that is supposed to represent a\nsingle Terms of Service.", "properties": { "id": { "type": "string", "description": "The unique identifier for this terms of service." }, "type": { "type": "string", "description": "`terms_of_service`", "enum": [ "terms_of_service" ] } } }, "SearchResultWithSharedLink": { "title": "Search Result (including Shared Link)", "type": "object", "description": "A single of files, folder or web link that matched the search query,\nincluding the additional information about the shared link through\nwhich the item has been shared with the user.\n\nThis response format is only returned when the\n`include_recent_shared_links` query parameter has been set to `true`.", "properties": { "accessible_via_shared_link": { "description": "The optional shared link through which the user has access to this\nitem. This value is only returned for items for which the user has\nrecently accessed the file through a shared link. For all other\nitems this value will return `null`." }, "item": { "allOf": [ { "$ref": "#/definitions/File" }, { "description": "The file, folder or web link that matched the\nsearch query." } ] }, "type": { "description": "The result type. The value is always `search_result`." } } }, "Group--Mini": { "title": "Group (Mini)", "type": "object", "x-box-variant": "mini", "description": "Mini representation of a group, including id and name of\ngroup.", "allOf": [ { "$ref": "#/definitions/Group--Base" }, { "properties": { "name": { "type": "string", "description": "The name of the group" }, "group_type": { "type": "string", "description": "The type of the group.", "enum": [ "managed_group", "all_users_group" ] } } } ] }, "RealtimeServer": { "title": "Real-time server", "type": "object", "description": "A real-time server that can be used for\nlong polling user events", "properties": { "type": { "description": "`realtime_server`", "type": "string" }, "url": { "type": "string", "description": "The URL for the server." }, "ttl": { "description": "The time in minutes for which this server is available", "type": "integer" }, "max_retries": { "description": "The maximum number of retries this server will\nallow before a new long poll should be started by\ngetting a [new list of server](#options-events).", "type": "integer" }, "retry_timeout": { "description": "The maximum number of seconds without a response\nafter which you should retry the long poll connection.\n\nThis helps to overcome network issues where the long\npoll looks to be working but no packages are coming\nthrough.", "type": "integer" } } }, "Event": { "title": "Event", "type": "object", "description": "The description of an event that happened within Box", "properties": { "type": { "description": "`event`", "type": "string" }, "event_id": { "type": "string", "description": "The ID of the event object. You can use this to detect duplicate events" }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user that performed the action represented by the event.\nSome events may be performed by users not logged into Box.\nIn that case, not all attributes of the object are populated and the\nevent is attributed to a unknown user (`user_id = 2`)" } ] }, "event_type": { "allOf": [ { "title": "Event Type", "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", "APPLICATION_CREATED", "APPLICATION_PUBLIC_KEY_ADDED", "APPLICATION_PUBLIC_KEY_DELETED", "CHANGE_ADMIN_ROLE", "CHANGE_FOLDER_PERMISSION", "COLLABORATION_ACCEPT", "COLLABORATION_EXPIRATION", "COLLABORATION_INVITE", "COLLABORATION_REMOVE", "COLLABORATION_ROLE_CHANGE", "COLLAB_ADD_COLLABORATOR", "COLLAB_INVITE_COLLABORATOR", "COLLAB_REMOVE_COLLABORATOR", "COLLAB_ROLE_CHANGE", "COMMENT_CREATE", "COMMENT_DELETE", "CONTENT_ACCESS", "CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY", "CONTENT_WORKFLOW_AUTOMATION_ADD", "CONTENT_WORKFLOW_AUTOMATION_DELETE", "CONTENT_WORKFLOW_POLICY_ADD", "CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION", "CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION", "COPY", "DATA_RETENTION_CREATE_RETENTION", "DATA_RETENTION_REMOVE_RETENTION", "DELETE", "DELETE_USER", "DEVICE_TRUST_CHECK_FAILED", "DOWNLOAD", "EDIT", "EDIT_USER", "EMAIL_ALIAS_CONFIRM", "EMAIL_ALIAS_REMOVE", "ENABLE_TWO_FACTOR_AUTH", "ENTERPRISE_APP_AUTHORIZATION_UPDATE", "FAILED_LOGIN", "FILE_MARKED_MALICIOUS", "FILE_WATERMARKED_DOWNLOAD", "GROUP_ADD_ITEM", "GROUP_ADD_USER", "GROUP_CREATION", "GROUP_DELETION", "GROUP_EDITED", "GROUP_REMOVE_ITEM", "GROUP_REMOVE_USER", "ITEM_COPY", "ITEM_CREATE", "ITEM_DOWNLOAD", "ITEM_MAKE_CURRENT_VERSION", "ITEM_MODIFY", "ITEM_MOVE", "ITEM_OPEN", "ITEM_PREVIEW", "ITEM_RENAME", "ITEM_SHARED", "ITEM_SHARED_CREATE", "ITEM_SHARED_UNSHARE", "ITEM_SHARED_UPDATE", "ITEM_SYNC", "ITEM_TRASH", "ITEM_UNDELETE_VIA_TRASH", "ITEM_UNSYNC", "ITEM_UPLOAD", "LEGAL_HOLD_ASSIGNMENT_CREATE", "LEGAL_HOLD_ASSIGNMENT_DELETE", "LEGAL_HOLD_POLICY_CREATE", "LEGAL_HOLD_POLICY_DELETE", "LEGAL_HOLD_POLICY_UPDATE", "LOCK", "LOCK_CREATE", "LOCK_DESTROY", "LOGIN", "MASTER_INVITE_ACCEPT", "MASTER_INVITE_REJECT", "METADATA_INSTANCE_CREATE", "METADATA_INSTANCE_DELETE", "METADATA_INSTANCE_UPDATE", "METADATA_TEMPLATE_CREATE", "METADATA_TEMPLATE_DELETE", "METADATA_TEMPLATE_UPDATE", "MOVE", "NEW_USER", "PREVIEW", "REMOVE_DEVICE_ASSOCIATION", "REMOVE_LOGIN_ACTIVITY_DEVICE", "RENAME", "RETENTION_POLICY_ASSIGNMENT_ADD", "SHARE", "SHARE_EXPIRATION", "SHIELD_ALERT", "SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED", "SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION", "SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED", "SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION", "SHIELD_JUSTIFICATION_APPROVAL", "STORAGE_EXPIRATION", "TAG_ITEM_CREATE", "TASK_ASSIGNMENT_CREATE", "TASK_ASSIGNMENT_DELETE", "TASK_ASSIGNMENT_UPDATE", "TASK_CREATE", "TASK_UPDATE", "TERMS_OF_SERVICE_ACCEPT", "TERMS_OF_SERVICE_REJECT", "UNDELETE", "UNLOCK", "UNSHARE", "UPDATE_COLLABORATION_EXPIRATION", "UPDATE_SHARE_EXPIRATION", "UPLOAD", "USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE", "WATERMARK_LABEL_CREATE", "WATERMARK_LABEL_DELETE" ] }, { "description": "The event type that triggered this event" } ] }, "session_id": { "type": "string", "description": "The session of the user that performed the action. Not all events will\npopulate this attribute." }, "source": { "allOf": [ { "$ref": "#/definitions/User" }, { "description": "The item that triggered this event" } ] }, "additional_details": { "type": "object", "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\ninformation to correlate an event to external KeySafe logs. Not all events\nhave an `additional_details` object. This object is only available in the\nEnterprise Events." } } }, "Collection": { "title": "Collection", "type": "object", "description": "A collection of items, including files and folders.\n\nCurrently, the only collection available\nis the `favorites` collection.\n\nThe contents of a collection can be explored in a\nsimilar way to which the contents of a folder is\nexplored.", "properties": { "id": { "type": "string", "description": "The unique identifier for this collection." }, "type": { "type": "string", "description": "`collection`", "enum": [ "collection" ] }, "name": { "type": "string", "description": "The name of the collection.", "enum": [ "Favorites" ] }, "collection_type": { "type": "string", "description": "The type of the collection. This is used to\ndetermine the proper visual treatment for\ncollections.", "enum": [ "favorites" ] } } }, "RecentItem": { "title": "Recent item", "type": "object", "description": "A recent item accessed by a user.", "properties": { "type": { "type": "string", "description": "`recent_item`" }, "item": { "allOf": [ { "$ref": "#/definitions/File" }, { "description": "The item that was recently accessed." } ] }, "interaction_type": { "type": "string", "description": "The most recent type of access the user performed on\nthe item.", "enum": [ "item_preview", "item_upload", "item_comment", "item_open", "item_modify" ] }, "interacted_at": { "type": "string", "format": "date-time", "description": "The time of the most recent interaction." }, "interaction_shared_link": { "type": "string", "description": "If the item was accessed through a shared link it will appear here,\notherwise this will be null." } } }, "RetentionPolicy--Mini": { "title": "Retention policy (Mini)", "type": "object", "x-box-variant": "mini", "description": "A mini representation of a retention policy, used when\nnested within another resource.", "allOf": [ { "$ref": "#/definitions/RetentionPolicy--Base" }, { "properties": { "policy_name": { "type": "string", "description": "The name given to the retention policy" }, "retention_length": { "type": "string", "format": "int32", "minimum": 1, "description": "The length of the retention policy. This length\nspecifies the duration in days that the retention\npolicy will be active for after being assigned to\ncontent. If the policy has A `policy_type` of\n`indefinite`, the `retention_length` will also be\n`indefinite`." }, "disposition_action": { "type": "string", "description": "The disposition action of the retention policy.\nThis action can be `permanently_delete`, which\nwill cause the content retained by the policy\nto be permanently deleted, or `remove_retention`,\nwhich will lift the retention policy from the content,\nallowing it to be deleted by users,\nonce the retention policy has expired.", "enum": [ "permanently_delete", "remove_retention" ] } } } ] }, "LegalHoldPolicy--Mini": { "title": "Legal hold policy (Mini)", "type": "object", "x-box-variants": [ "mini", "standard" ], "x-box-variant": "mini", "description": "A mini legal hold policy", "properties": { "id": { "type": "string", "description": "The unique identifier for this legal hold policy" }, "type": { "type": "string", "description": "`legal_hold_policy`", "enum": [ "legal_hold_policy" ] } } }, "LegalHoldPolicyAssignment--Base": { "title": "Legal hold policy assignment (Base)", "type": "object", "x-box-variants": [ "base", "standard" ], "x-box-variant": "base", "description": "Legal Hold Assignments are used to assign Legal Hold\nPolicies to Users, Folders, Files, or File Versions.\n\nCreating a Legal Hold Assignment puts a hold\non the File-Versions that belong to the Assignment's\n'apply-to' entity.", "properties": { "id": { "type": "string", "description": "The unique identifier for this legal hold assignment" }, "type": { "type": "string", "description": "`legal_hold_policy_assignment`", "enum": [ "legal_hold_policy_assignment" ] } } }, "StoragePolicy--Mini": { "title": "Storage policy (Mini)", "type": "object", "x-box-variants": [ "standard", "mini" ], "x-box-variant": "mini", "description": "A mini description of a Storage Policy object", "properties": { "id": { "type": "string", "description": "The unique identifier for this storage policy" }, "type": { "type": "string", "description": "`storage_policy`", "enum": [ "storage_policy" ] } } }, "SignRequestSigner": { "title": "Signer fields for GET Sign Request response", "type": "object", "description": "The schema for a Signer in a GET Sign Request request body", "required": [ "email" ], "allOf": [ { "$ref": "#/definitions/SignRequestCreateSigner" }, { "properties": { "has_viewed_document": { "type": "boolean", "readOnly": true, "description": "Set to `true` if the signer views the document" }, "signer_decision": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "signed", "declined" ], "description": "Type of decision made by the signer" }, "finalized_at": { "type": "string", "format": "date-time", "description": "Date and Time that the decision was made" } }, "description": "Final decision made by the signer" }, "inputs": { "type": "array", "items": { "$ref": "#/definitions/SignRequestSignerInput" }, "readOnly": true }, "embed_url": { "type": "string", "readOnly": true, "description": "URL to direct a signer to for signing" } } } ] }, "SignRequestCreateSigner": { "title": "Signer fields for Create Sign Request", "type": "object", "description": "The schema for a Signer in a POST Sign Request request body", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Email address of the signer" }, "role": { "type": "string", "enum": [ "signer", "approver", "final_copy_reader" ], "description": "Defines the role of the signer in the sign request. A `signer`\nmust sign the document and an `approver` must approve the document. A\n`final_copy_reader` only receives the final signed document and signing\nlog.", "default": "signer" }, "is_in_person": { "type": "boolean", "description": "Used in combination with an embed URL for a sender. After the\nsender signs, they will be redirected to the next `in_person` signer." }, "order": { "type": "integer", "description": "Order of the signer", "minimum": 0 }, "embed_url_external_user_id": { "type": "string", "description": "User ID for the signer in an external application responsible\nfor authentication when accessing the embed URL." } } }, "SignRequestPrefillTag": { "title": "Sign Request Prefill Tag", "type": "object", "description": "Prefill tags are used to prefill placeholders with signer input data. Only\none value field can be included.", "properties": { "document_tag_id": { "type": "string", "description": "This references the ID of a specific tag contained in a file of the sign request." }, "text_value": { "type": "string", "description": "Text prefill value" }, "checkbox_value": { "type": "boolean", "description": "Checkbox prefill value" }, "date_value": { "type": "string", "format": "date-time", "description": "Date prefill value" } } }, "Workflow": { "title": "Workflow", "type": "object", "x-box-variant": "standard", "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\nscope within the developer console in order to use this resource.", "allOf": [ { "$ref": "#/definitions/Workflow--Mini" }, { "properties": { "flows": { "type": "array", "description": "A list of flows assigned to a workflow.", "items": { "type": "object", "description": "A step in a Box Relay Workflow. Each flow contains a `Trigger` and\na collection of Outcomes to perform once the conditions of a\n`Trigger` are met", "properties": { "id": { "type": "string", "description": "The identifier of the flow" }, "type": { "type": "string", "description": "The flow's resource type", "enum": [ "flow" ] }, "trigger": { "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The trigger's resource type", "enum": [ "trigger" ] }, "trigger_type": { "type": "string", "description": "The type of trigger selected for this flow", "enum": [ "WORKFLOW_MANUAL_START" ] }, "scope": { "type": "array", "description": "List of trigger scopes", "items": { "type": "object", "description": "Object that describes where and how a Trigger condition is met", "properties": { "type": { "type": "string", "description": "The trigger scope's resource type", "enum": [ "trigger_scope" ] }, "ref": { "type": "string", "description": "Indicates the path of the condition value to check" }, "object": { "type": "object", "description": "The object the `ref` points to", "properties": { "type": { "type": "string", "description": "The type of the object", "enum": [ "folder" ] }, "id": { "type": "string", "description": "The id of the object" } } } } } } } }, { "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": { "type": "string", "description": "The identifier of the outcome" }, "type": { "type": "string", "description": "The outcomes resource type", "enum": [ "outcome" ] }, "name": { "type": "string", "description": "The name of the outcome" }, "action_type": { "allOf": [ { "title": "Action Type", "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" } ] }, "outcome_parameters": { "type": "object", "description": "Information about how to complete the outcome which varies based on\n`action_type` selected" }, "if_rejected": { "type": "array", "description": "If `action_type` is `assign_task` and the task is rejected, returns a\nlist of outcomes to complete", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier of the outcome" }, "type": { "type": "string", "description": "The outcomes resource type", "enum": [ "outcome" ] }, "name": { "type": "string", "description": "The name of the outcome" }, "action_type": { "allOf": [ { "title": "Action Type", "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" } ] }, "outcome_parameters": { "type": "object", "description": "Information about how to complete the outcome which varies based on\n`action_type` selected" } } } } } } }, { "description": "Actions that are completed once the flow is triggered" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When this flow was created" }, "created_by": { "allOf": [ { "$ref": "#/definitions/User--Base" }, { "description": "The user who created this flow" } ] } } } } } } ] }, "File--Base": { "title": "File (Base)", "type": "object", "x-box-variants": [ "base", "mini", "standard", "full" ], "x-box-variant": "base", "description": "The bare basic representation of a file, the minimal\namount of fields returned when using the `fields` query\nparameter.", "properties": { "id": { "type": "string", "description": "The unique identifier that represent a file.\n\nThe ID for any file can be determined\nby visiting a file in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/files/123`\nthe `file_id` is `123`." }, "etag": { "type": "string", "description": "The HTTP `etag` of this file. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the file if (no) changes have happened." }, "type": { "type": "string", "description": "`file`", "enum": [ "file" ] } } }, "Folder--Base": { "title": "Folder (Base)", "type": "object", "x-box-variants": [ "base", "mini", "standard", "full" ], "x-box-variant": "base", "description": "The bare basic representation of a folder, the minimal\namount of fields returned when using the `fields` query\nparameter.", "properties": { "id": { "type": "string", "description": "The unique identifier that represent a folder.\n\nThe ID for any folder can be determined\nby visiting a folder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/folders/123`\nthe `folder_id` is `123`." }, "etag": { "type": "string", "description": "The HTTP `etag` of this folder. This can be used within some API\nendpoints in the `If-Match` and `If-None-Match` headers to only\nperform changes on the folder if (no) changes have happened." }, "type": { "type": "string", "description": "`folder`", "enum": [ "folder" ] } } }, "FileVersion--Base": { "title": "File version (Base)", "type": "object", "x-box-variants": [ "base", "mini", "standard" ], "x-box-variant": "base", "description": "The bare basic representation of a file version, the minimal\namount of fields returned when using the `fields` query\nparameter.", "properties": { "id": { "type": "string", "description": "The unique identifier that represent a file version." }, "type": { "type": "string", "description": "`file_version`", "enum": [ "file_version" ] } } }, "WebLink--Base": { "title": "Web link (Base)", "type": "object", "x-box-variants": [ "base", "mini", "standard" ], "x-box-variant": "base", "description": "Web links are objects that point to URLs. These objects\nare also known as bookmarks within the Box web application.\n\nWeb link objects are treated similarly to file objects,\nthey will also support most actions that apply to regular files.", "properties": { "id": { "type": "string", "description": "The unique identifier for this web link" }, "type": { "type": "string", "description": "`web_link`", "enum": [ "web_link" ] }, "etag": { "type": "string", "description": "The entity tag of this web link. Used with `If-Match`\nheaders." } } }, "Group--Base": { "title": "Group (Base)", "type": "object", "x-box-variants": [ "base", "mini", "standard", "full" ], "x-box-variant": "base", "description": "A base representation of a group.", "properties": { "id": { "type": "string", "description": "The unique identifier for this object" }, "type": { "type": "string", "description": "`group`", "enum": [ "group" ] } } }, "EventSource": { "title": "Event source", "type": "object", "description": "The source file or folder that triggered an event in\nthe event stream.", "properties": { "item_type": { "type": "string", "enum": [ "file", "folder" ], "description": "The type of the item that the event\nrepresents. Can be `file` or `folder`.\n" }, "item_id": { "type": "string", "description": "The unique identifier that represents the\nitem.\n" }, "item_name": { "type": "string", "description": "The name of the item.\n" }, "parent": { "allOf": [ { "$ref": "#/definitions/Folder--Mini" }, { "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder." } ] }, "owned_by": { "allOf": [ { "$ref": "#/definitions/User--Mini" }, { "description": "The user who owns this item." }, {} ] } } }, "RetentionPolicy--Base": { "title": "Retention policy (Base)", "type": "object", "x-box-variants": [ "base", "mini", "standard" ], "x-box-variant": "base", "description": "The bare basic representation of a file version, the minimal\namount of fields returned when using the `fields` query\nparameter.", "properties": { "id": { "type": "string", "description": "The unique identifier that represent a file version." }, "type": { "type": "string", "description": "`retention_policy`", "enum": [ "retention_policy" ] } } }, "SignRequestSignerInput": { "title": "Sign Request Signer Input", "type": "object", "description": "Input created by a Signer on a Sign Request", "required": [ "page_index" ], "allOf": [ { "$ref": "#/definitions/SignRequestPrefillTag" }, { "properties": { "type": { "type": "string", "enum": [ "signature", "date", "text", "checkbox" ], "description": "Type of input" }, "page_index": { "type": "integer", "description": "Index of page that the input is on" } } } ] }, "Workflow--Mini": { "title": "Workflow (Mini)", "type": "object", "x-box-variants": [ "mini", "standard", "full" ], "x-box-variant": "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\nscope within the developer console in order to use this resource.", "properties": { "id": { "type": "string", "description": "The unique identifier for the workflow" }, "type": { "type": "string", "description": "`workflow`", "enum": [ "workflow" ] }, "name": { "type": "string", "description": "The name of the workflow" }, "description": { "type": "string", "description": "The description for a workflow." }, "is_enabled": { "type": "boolean", "description": "Specifies if this workflow is enabled" } } } } }